Class DateFmt
Create a new date formatter instance. The date formatter is immutable once it is created, but can format as many different dates as needed with the same options. Create different date formatter instances for different purposes and then keep them cached for use later if you have more than one date to format.
The options may contain any of the following properties:
- locale - locale to use when formatting the date/time. If the locale is not specified, then the default locale of the app or web page will be used.
- calendar - the type of calendar to use for this format. The value should be a sting containing the name of the calendar. Currently, the supported types are "gregorian", "julian", "arabic", "hebrew", or "chinese". If the calendar is not specified, then the default calendar for the locale is used. When the calendar type is specified, then the format method must be called with an instance of the appropriate date type. (eg. Gregorian calendar means that the format method must be called with a GregDate instance.)
- timezone - time zone to use when formatting times. This may be a time zone instance or a time zone specifier from the IANA list of time zone database names (eg. "America/Los_Angeles"), the string "local", or a string specifying the offset in RFC 822 format. The IANA list of time zone names can be viewed at this page. If the time zone is given as "local", the offset from UTC as given by the Javascript system is used. If the offset is given as an RFC 822 style offset specifier, it will parse that string and use the resulting offset. If the time zone is not specified, the default time zone for the locale is used. If both the date object and this formatter instance contain time zones and those time zones are different from each other, the formatter will calculate the offset between the time zones and subtract it from the date before formatting the result for the current time zone. The theory is that a date object that contains a time zone specifies a specific instant in time that is valid around the world, whereas a date object without one is a local time and can only be used for doing things in the local time zone of the user.
- type - Specify whether this formatter should format times only, dates only, or
both times and dates together. Valid values are "time", "date", and "datetime". Note that
in some locales, the standard format uses the order "time followed by date" and in others,
the order is exactly opposite, so it is better to create a single "datetime" formatter
than it is to create a time formatter and a date formatter separately and concatenate the
results. A "datetime" formatter will get the order correct for the locale.
The default type if none is specified in with the type option is "date".
- length - Specify the length of the format to use. The length is the approximate size of the
formatted string.
- short - use a short representation of the time. This is the most compact format possible for the locale.
- medium - use a medium length representation of the time. This is a slightly longer format.
- long - use a long representation of the time. This is a fully specified format, but some of the textual components may still be abbreviated
- full - use a full representation of the time. This is a fully specified format where all the textual components are spelled out completely
Note that the length parameter does not specify which components are to be formatted. Use the "date" and the "time" properties to specify the components. Also, very few of the components of a time format differ according to the length, so this property has little to no affect on time formatting.
- date - This property tells
which components of a date format to use. For example,
sometimes you may wish to format a date that only contains the month and date
without the year, such as when displaying a person's yearly birthday. The value
of this property allows you to specify only those components you want to see in the
final output, ordered correctly for the locale.
Valid values are:
- dmwy - format all components, weekday, date, month, and year
- dmy - format only date, month, and year
- dmw - format only weekday, date, and month
- dm - format only date and month
- my - format only month and year
- dw - format only the weekday and date
- d - format only the date
- m - format only the month, in numbers for shorter lengths, and letters for longer lengths
- n - format only the month, in letters only for all lengths
- y - format only the year
As of ilib 12.0, you can now pass ICU style skeletons in this option similar to the ones you get from DateTimePatternGenerator.getSkeleton(). It will not extract the length from the skeleton so you still need to pass the length property, but it will extract the date components.
- time - This property gives which components of a time format to use. The time will be formatted
correctly for the locale with only the time components requested. For example, a clock might only display
the hour and minute and not need the seconds or the am/pm component. In this case, the time property should be set
to "hm".
Valid values for this property are:
- ahmsz - format the hours, minutes, seconds, am/pm (if using a 12 hour clock), and the time zone
- ahms - format the hours, minutes, seconds, and am/pm (if using a 12 hour clock)
- hmsz - format the hours, minutes, seconds, and the time zone
- hms - format the hours, minutes, and seconds
- ahmz - format the hours, minutes, am/pm (if using a 12 hour clock), and the time zone
- ahm - format the hours, minutes, and am/pm (if using a 12 hour clock)
- hmz - format the hours, minutes, and the time zone
- ah - format only the hours and am/pm if using a 12 hour clock
- hm - format only the hours and minutes
- ms - format only the minutes and seconds
- h - format only the hours
- m - format only the minutes
- s - format only the seconds
Default value if this property is not specified is "hma".
As of ilib 12.0, you can now pass ICU style skeletons in this option similar to the ones you get from DateTimePatternGenerator.getSkeleton(). It will not extract the length from the skeleton so you still need to pass the length property, but it will extract the time components.
- clock - specify that the time formatter should use a 12 or 24 hour clock.
Valid values are "12" and "24".
In some locales, both clocks are used. For example, in en_US, the general populace uses a 12 hour clock with am/pm, but in the US military or in nautical or aeronautical or scientific writing, it is more common to use a 24 hour clock. This property allows you to construct a formatter that overrides the default for the locale.
If this property is not specified, the default is to use the most widely used convention for the locale.
- template - use the given template string as a fixed format when formatting
the date/time. Valid codes to use in a template string are as follows:
- a - am/pm marker
- d - 1 or 2 digit date of month, not padded
- dd - 1 or 2 digit date of month, 0 padded to 2 digits
- O - ordinal representation of the date of month (eg. "1st", "2nd", etc.)
- D - 1 to 3 digit day of year
- DD - 1 to 3 digit day of year, 0 padded to 2 digits
- DDD - 1 to 3 digit day of year, 0 padded to 3 digits
- M - 1 or 2 digit month number, not padded
- MM - 1 or 2 digit month number, 0 padded to 2 digits
- N - 1 character month name abbreviation
- NN - 2 character month name abbreviation
- MMM - 3 character month month name abbreviation
- MMMM - fully spelled out month name
- yy - 2 digit year
- yyyy - 4 digit year
- E - day-of-week name, abbreviated to a single character
- EE - day-of-week name, abbreviated to a max of 2 characters
- EEE - day-of-week name, abbreviated to a max of 3 characters
- EEEE - day-of-week name fully spelled out
- G - era designator
- w - week number in year
- ww - week number in year, 0 padded to 2 digits
- W - week in month
- h - hour (12 followed by 1 to 11)
- hh - hour (12, followed by 1 to 11), 0 padded to 2 digits
- k - hour (1 to 24)
- kk - hour (1 to 24), 0 padded to 2 digits
- H - hour (0 to 23)
- HH - hour (0 to 23), 0 padded to 2 digits
- K - hour (0 to 11)
- KK - hour (0 to 11), 0 padded to 2 digits
- m - minute in hour
- mm - minute in hour, 0 padded to 2 digits
- s - second in minute
- ss - second in minute, 0 padded to 2 digits
- S - millisecond (1 to 3 digits)
- SSS - millisecond, 0 padded to 3 digits
- z - general time zone
- Z - RFC 822 time zone
- useNative - the flag used to determine whether to use the native script settings for formatting the numbers.
- meridiems - string that specifies what style of meridiems to use with this format. The choices are "default", "gregorian", "ethiopic", and "chinese". The "default" style is often the simple Gregorian AM/PM, but the actual style is chosen by the locale. (For almost all locales, the Gregorian AM/PM style is most frequently used.) The "ethiopic" style uses 5 different meridiems for "morning", "noon", "afternoon", "evening", and "night". The "chinese" style uses 7 different meridiems corresponding to the various parts of the day. N.B. Even for the Chinese locales, the default is "gregorian" when formatting dates in the Gregorian calendar.
- onLoad - a callback function to call when the date format object is fully loaded. When the onLoad option is given, the DateFmt object will attempt to load any missing locale data using the ilib loader callback. When the constructor is done (even if the data is already preassembled), the onLoad function is called with the current instance as a parameter, so this callback can be used with preassembled or dynamic loading or a mix of the two.
- sync - tell whether to load any missing locale data synchronously or asynchronously. If this option is given as "false", then the "onLoad" callback must be given, as the instance returned from this constructor will not be usable for a while.
- loadParams - an object containing parameters to pass to the loader callback function when locale data is missing. The parameters are not interpretted or modified in any way. They are simply passed along. The object may contain any property/value pairs as long as the calling code is in agreement with the loader callback function as to what those parameters mean.
Example: a date format in Spanish might be given as: "'El' d. 'de' MMMM", where the 'El' and the 'de' are left as-is in the output because they are quoted. Typical output for this example template might be, "El 5. de Mayo". The following options will be used when formatting a date/time with an explicit template:
- locale - the locale is only used for translations of things like month names or day-of-week names.
- calendar - used to translate a date instance into date/time component values that can be formatted into the template
- timezone - used to figure out the offset to add or subtract from the time to get the final time component values
- clock - used to figure out whether to format times with a 12 or 24 hour clock. If this option is specified, it will override the hours portion of a time format. That is, "hh" is switched with "HH" and "kk" is switched with "KK" as appropriate. If this option is not specified, the 12/24 code in the template will dictate whether to use the 12 or 24 clock, and the 12/24 default in the locale will be ignored.
Defined in: ilib-full-dyn.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
DateFmt(options)
|
| Method Attributes | Method Name and Description |
|---|---|
|
format(dateLike)
Format a particular date instance according to the settings of this
formatter object.
|
|
|
formatRelative(reference, date)
Return a string that describes a date relative to the given
reference date.
|
|
|
Return the name of the calendar used to format date/times for this
formatter instance.
|
|
|
getClock()
Return the clock option set in the constructor.
|
|
|
Return the date components that this formatter formats.
|
|
|
getDaysOfWeek(options)
Returns an array of the days of the week, formatted to the optional length specified.
|
|
|
Return the length used to format date/times in this formatter.
|
|
|
Return the locale used with this formatter instance.
|
|
| <static> |
DateFmt.getMeridiemsRange(options)
Return the range of possible meridiems (times of day like "AM" or
"PM") in this date formatter.
|
|
Return the meridiems range in current locale.
|
|
|
getMonthsOfYear(options)
Returns an array of the months of the year, formatted to the optional length specified.
|
|
|
Return the template string that is used to format date/times for this
formatter instance.
|
|
|
Return the time components that this formatter formats.
|
|
|
Return the time zone used to format date/times for this formatter
instance.
|
|
|
getType()
Return the type of this formatter.
|
|
|
toString()
Convert this formatter to a string representation by returning the
format template.
|
Class Detail
DateFmt(options)
- Parameters:
- {Object} options
- options governing the way this date formatter instance works
Method Detail
{string}
format(dateLike)
Format a particular date instance according to the settings of this
formatter object. The type of the date instance being formatted must
correspond exactly to the calendar type with which this formatter was
constructed. If the types are not compatible, this formatter will
produce bogus results.
- Parameters:
- {IDate|Number|String|Date|JulianDay|null|undefined} dateLike
- a date-like object to format
- Returns:
- {string} the formatted version of the given date instance
{string}
formatRelative(reference, date)
Return a string that describes a date relative to the given
reference date. The string returned is text that for the locale that
was specified when the formatter instance was constructed.
The date can be in the future relative to the reference date or in the past, and the formatter will generate the appropriate string.
The text used to describe the relative reference depends on the length of time between the date and the reference. If the time was in the past, it will use the "ago" phrase, and in the future, it will use the "in" phrase. Examples:
- within a minute: either "X seconds ago" or "in X seconds"
- within an hour: either "X minutes ago" or "in X minutes"
- within a day: either "X hours ago" or "in X hours"
- within 2 weeks: either "X days ago" or "in X days"
- within 12 weeks (~3 months): either "X weeks ago" or "in X weeks"
- within two years: either "X months ago" or "in X months"
- longer than 2 years: "X years ago" or "in X years"
- Parameters:
- {IDate|Number|String|Date|JulianDay|null|undefined} reference
- a date that the date parameter should be relative to
- {IDate|Number|String|Date|JulianDay|null|undefined} date
- a date being formatted
- Throws:
- "Wrong calendar type" when the start or end dates are not the same calendar type as the formatter itself
- Returns:
- {string} the formatted relative date
{string}
getCalendar()
Return the name of the calendar used to format date/times for this
formatter instance.
- Returns:
- {string} the name of the calendar used by this formatter
{string}
getClock()
Return the clock option set in the constructor. If the clock option was
not given, the default from the locale is returned instead.
- Returns:
- {string} "12" or "24" depending on whether this formatter uses the 12-hour or 24-hour clock
{string}
getDateComponents()
Return the date components that this formatter formats. This is either the
value of the date option to the constructor, or the default value. If this
formatter is a time-only formatter, this method will return the empty
string. The date component letters may be specified in any order in the
constructor, but this method will reorder the given components to a standard
order.
- Returns:
- {string} the date components that this formatter formats
{Array}
getDaysOfWeek(options)
Returns an array of the days of the week, formatted to the optional length specified.
i.e. ...getDaysOfWeek() OR ...getDaysOfWeek({length: "short"})
The options parameter may contain any of the following properties:
- length - length of the names of the months being sought. This may be one of "short", "medium", "long", or "full"
- Parameters:
- {Object=} options
- an object-literal that contains one key "length" with the standard length strings
- Returns:
- {Array} an array of all of the names of the days of the week
{string}
getLength()
Return the length used to format date/times in this formatter. This is either the
value of the length option to the constructor, or the default value.
- Returns:
- {string} the length of formats this formatter returns
{Locale}
getLocale()
Return the locale used with this formatter instance.
- Returns:
- {Locale} the Locale instance for this formatter
<static>
{Array.<{name:string|start:string|end:string}>}
DateFmt.getMeridiemsRange(options)
Return the range of possible meridiems (times of day like "AM" or
"PM") in this date formatter.
The options may contain any of the following properties:
- locale - locale to use when formatting the date/time. If the locale is not specified, then the default locale of the app or web page will be used.
- meridiems - string that specifies what style of meridiems to use with this format. The choices are "default", "gregorian", "ethiopic", and "chinese". The "default" style is often the simple Gregorian AM/PM, but the actual style is chosen by the locale. (For almost all locales, the Gregorian AM/PM style is most frequently used.) The "ethiopic" style uses 5 different meridiems for "morning", "noon", "afternoon", "evening", and "night". The "chinese" style uses 7 different meridiems corresponding to the various parts of the day. N.B. Even for the Chinese locales, the default is "gregorian" when formatting dates in the Gregorian calendar.
- Parameters:
- {Object} options
- options governing the way this date formatter instance works for getting meridiems range
- Returns:
- {Array.<{name:string|start:string|end:string}>}
{Array.<{name:string|start:string|end:string}>}
getMeridiemsRange()
Return the meridiems range in current locale.
- Returns:
- {Array.<{name:string|start:string|end:string}>} the range of available meridiems
{Array}
getMonthsOfYear(options)
Returns an array of the months of the year, formatted to the optional length specified.
i.e. ...getMonthsOfYear() OR ...getMonthsOfYear({length: "short"})
The options parameter may contain any of the following properties:
- length - length of the names of the months being sought. This may be one of "short", "medium", "long", or "full"
- date - retrieve the names of the months in the date of the given date
- year - retrieve the names of the months in the given year. In some calendars, the months have different names depending if that year is a leap year or not.
- Parameters:
- {Object=} options
- an object-literal that contains any of the above properties
- Returns:
- {Array} an array of the names of all of the months of the year in the current calendar
{string}
getTemplate()
Return the template string that is used to format date/times for this
formatter instance. This will work, even when the template property is not explicitly
given in the options to the constructor. Without the template option, the constructor
will build the appropriate template according to the options and use that template
in the format method.
- Returns:
- {string} the format template for this formatter
{string}
getTimeComponents()
Return the time components that this formatter formats. This is either the
value of the time option to the constructor, or the default value. If this
formatter is a date-only formatter, this method will return the empty
string. The time component letters may be specified in any order in the
constructor, but this method will reorder the given components to a standard
order.
- Returns:
- {string} the time components that this formatter formats
getTimeZone()
Return the time zone used to format date/times for this formatter
instance.
- Returns:
- a string naming the time zone
{string}
getType()
Return the type of this formatter. The type is a string that has one of the following
values: "time", "date", "datetime".
- Returns:
- {string} the type of the formatter
{string}
toString()
Convert this formatter to a string representation by returning the
format template. This method delegates to getTemplate.
- Returns:
- {string} the format template