Description

The Date and Time formatting functions are intended to provide a set of simple, cross platform functions that Mozilla developers can use to perform locale sensitive date and time formatting operations.

The caller first need to instanciate nsILocale.
FormatTime performs a locale sensitive date formatting operation on the time_t parameter. The formatted string is returned in nsString. The date/time string is formatted according to conventions of the given locale and the given selectors.
FormatTMTime performs a locale sensitive date formatting operation on the struct tm parameter. The formatted string is returned in nsString. The date/time string is formatted according to conventions of the given locale and the given selectors.

API

typedef enum {
  kDateFormatNone,                // do not include the date in the format string
  kDateFormatLong,                // provides the long date format for the given locale
  kDateFormatShort,               // provides the short date format for the given locale
  kDateFormatYearMonth,           // formats using only the year and month
  kDateFormatWeekday              // week day (e.g. Mon, Tue)
} nsDateFormatSelector;

typedef enum {
  kTimeFormatNone,                // don't include the time in the format string
  kTimeFormatSeconds,             // provides the time format with seconds in the given locale
  kTimeFormatNoSeconds,           // provides the time format without seconds in the given locale
  kTimeFormatSecondsForce24Hour,  // forces the time format to use the 24 clock, regardless of the locale conventions
  kTimeFormatNoSecondsForce24Hour // forces the time format to use the 24 clock, regardless of the locale conventions
} nsTimeFormatSelector;


// Create a date/time format interface for an input locale.
//

class nsIDateTimeFormat : public nsISupports {

public:

  // performs a locale sensitive date formatting operation on the time_t parameter
  NS_IMETHOD FormatTime(nsILocale* locale,
            const nsDateFormatSelector dateFormatSelector,
            const nsTimeFormatSelector timeFormatSelector,
            const time_t timetTime,
            nsString& stringOut) = 0;

  // performs a locale sensitive date formatting operation on the struct tm parameter
  NS_IMETHOD FormatTMTime(nsILocale* locale,
             const nsDateFormatSelector dateFormatSelector,
             const nsTimeFormatSelector timeFormatSelector,
             const struct tm* tmTime,
             nsString& stringOut) = 0;

  // performs a locale sensitive date formatting operation on the PRTime parameter
  NS_IMETHOD FormatPRTime(nsILocale* locale,
             const nsDateFormatSelector dateFormatSelector,
             const nsTimeFormatSelector timeFormatSelector,
             const PRTime prTime,
             nsString& stringOut) = 0;

  // performs a locale sensitive date formatting operation on the PRExplodedTime parameter
  NS_IMETHOD FormatPRExplodedTime(nsILocale* locale,
                 const nsDateFormatSelector dateFormatSelector,
                 const nsTimeFormatSelector timeFormatSelector,
                 const PRExplodedTime* explodedTime,
                 nsString& stringOut) = 0;
};

Example

Following example format a current time by using both FormatTime and FormatTMTime. Details omitted.

 nsAutoString dateString;
 time_t timetTime;
 // create a nsILocale by nsILocaleService
 
 // create an instance
 res = nsComponentManager::CreateInstance(kDateTimeFormatCID,
       NULL, nsIDateTimeFormat::GetIID(), (void**) &inst);

 // get a current time
 time(&timetTime);

 // format by using FormatTime
 res = inst->FormatTime(locale, kDateFormatShort, kTimeFormatSeconds,
       timetTime, dateString);

 // format by using FormatTMTime
 res = inst->FormatTMTime(locale, kDateFormatWeekday, kTimeFormatNoSecondsForce24Hour,
       localtime(&ltime), dateString);

 NS_RELEASE(inst);

Undecided (or unimplemented) issues

Input string is specifed as nsStrings, this may change (to whatever appropriate for XPIDL) => new scriptable interface is available nsIScriptableDateFormat