Date and Time Formatting
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(<ime), 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