Documentation

Class

DateFmt

DateFmt(options)

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
    eg. The "short" format for an en_US date may be "MM/dd/yy", whereas the long format might be "d MMM, yyyy". In the long format, the month name is textual instead of numeric and is longer, the year is 4 digits instead of 2, and the format contains slightly more spaces and formatting characters.

    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
    Default components, if this property is not specified, is "dmy". This property may be specified but has no affect if the current formatter is for times only.

    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
    If you want to format a length of time instead of a particular instant in time, use the duration formatter object (DurationFmt) instead because this formatter is geared towards instants. A date formatter will make sure that each component of the time is within the normal range for that component. That is, the minutes will always be between 0 and 59, no matter what is specified in the date to format. A duration format will allow the number of minutes to exceed 59 if, for example, you were displaying the length of a movie of 198 minutes.

    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
    • B - the current day period
    • 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 name abbreviation
    • MMMM - fully spelled out month name
    • L - 1 character stand-alone month name abbreviation
    • LL - 2 character stand-alone month name abbreviation
    • LLL - 3 character stand-alone month name abbreviation
    • LLLL - fully spelled out stand-alone 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
    • c - stand-alone day-of-week name, abbreviated to a single character
    • cc - stand-alone day-of-week name, abbreviated to a max of 2 characters
    • ccc - stand-alone day-of-week name, abbreviated to a max of 3 characters
    • cccc - stand-alone 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.
  • useIntl - choose whether Intl.DateTimeFormat object for formatting. When it is set to true, the Intl object is available, it supports the requested locale, and the parameters can be converted to equivalent parameters for the Intl.DateTimeFormat object, then it will format the date relatively quickly using Intl. When they cannot be converted, the Intl object is not available, or the Intl object does not support the requested locale, it will perform the relatively slow formatting using regular ilib code written in Javascript. The code will often return different results depending on the platform and version of the Javascript engine and which version of CLDR it supports. If you need consistency across versions and platforms, do not use the useIntl flag. Just stick with the regular ilib formatting code.
  • 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.

Any substring containing letters within single or double quotes will be used as-is in the final output and will not be interpretted for codes as above.

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.

All other options will be ignored and their corresponding getter methods will return the empty string.

Constructor

# new DateFmt(options)

Parameters:
Name Type Description
options Object

options governing the way this date formatter instance works

View Source DateFmt.js, line 303

Methods

# format(dateLike) → {string}

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:
Name Type Description
dateLike IDate | number | string | Date | JulianDay | null | undefined

a date-like object to format

View Source DateFmt.js, line 1528

the formatted version of the given date instance

string

# formatRelative(reference, date) → {string}

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:
Name Type Description
reference IDate | number | string | Date | JulianDay | null | undefined

a date that the date parameter should be relative to
date IDate | number | string | Date | JulianDay | null | undefined

a date being formatted

View Source DateFmt.js, line 1589

"Wrong calendar type" when the start or end dates are not the same calendar type as the formatter itself

the formatted relative date

string

# getCalendar() → {string}

Return the name of the calendar used to format date/times for this formatter instance.

View Source DateFmt.js, line 1020

the name of the calendar used by this formatter

string

# getClock() → {string}

Return the clock option set in the constructor. If the clock option was not given, the default from the locale is returned instead.

View Source DateFmt.js, line 1077

"12" or "24" depending on whether this formatter uses the 12-hour or 24-hour clock

string

# getDateComponentOrder() → {string}

Return the order of the year, month, and date components for the current locale.

When implementing a date input widget in a UI, it would be useful to know what order to put the year, month, and date input fields so that it conforms to the user expectations for the locale. This method gives that order by returning a string that has a single "y", "m", and "d" character in it in the correct order.

For example, the return value "ymd" means that this locale formats the year first, the month second, and the date third, and "mdy" means that the month is first, the date is second, and the year is third. Four of the 6 possible permutations of the three letters have at least one locale that uses that ordering, though some combinations are far more likely than others. The ones that are not used by any locales are "dym" and "myd", though new locales are still being added to CLDR frequently, and possible orderings cannot be predicted. Your code should support all 6 possibilities, just in case.

View Source DateFmt.js, line 1002

a string giving the date component order

string

# getDateComponents() → {string}

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.

View Source DateFmt.js, line 1044

the date components that this formatter formats

string

# getDaysOfWeek(optionsopt) → {Array}

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:
Name Type Attributes Description
options Object <optional>

an object-literal that contains one key "length" with the standard length strings

View Source DateFmt.js, line 1280

an array of all of the names of the days of the week

Array

# getLength() → {string}

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.

View Source DateFmt.js, line 1030

the length of formats this formatter returns

string

# getLocale() → {Locale}

Return the locale used with this formatter instance.

View Source DateFmt.js, line 965

the Locale instance for this formatter

Locale

# getMeridiemsRange() → {Array.<{name:string, start:string, end:string}>}

Return the meridiems range in current locale.

View Source DateFmt.js, line 1085

the range of available meridiems

Array.<{name:string, start:string, end:string}>

# getMonthsOfYear(optionsopt) → {Array}

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:
Name Type Attributes Description
options Object <optional>

an object-literal that contains any of the above properties

View Source DateFmt.js, line 1236

an array of the names of all of the months of the year in the current calendar

Array

# getTemplate() → {string}

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.

View Source DateFmt.js, line 978

the format template for this formatter

string

# getTimeComponents() → {string}

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.

View Source DateFmt.js, line 1058

the time components that this formatter formats

string

# getTimeZone() → {TimeZone}

Return the time zone used to format date/times for this formatter instance.

View Source DateFmt.js, line 1067

a time zone object that this formatter is formatting for

TimeZone

# getType() → {string}

Return the type of this formatter. The type is a string that has one of the following values: "time", "date", "datetime".

View Source DateFmt.js, line 1011

the type of the formatter

string

# toString() → {string}

Convert this formatter to a string representation by returning the format template. This method delegates to getTemplate.

View Source DateFmt.js, line 1297

the format template

string

# static getMeridiemsRange(options) → {Array.<{name:string, start:string, end:string}>}

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:
Name Type Description
options Object

options governing the way this date formatter instance works for getting meridiems range

View Source DateFmt.js, line 636

Array.<{name:string, start:string, end:string}>

# static isIntlDateTimeAvailable(locale) → {Boolean}

return true if the locale is supported in date and time formatting for Intl.DateTimeFormat Object

  • locale - locale to check if it is available or not. If the locale is not specified, then it returns false.
Parameters:
Name Type Description
locale string

locale to check if it is available or not.

View Source DateFmt.js, line 663

true if it is available to use, false otherwise

Boolean