Class: DateTimeFormatter

A utility class for creating time formatters.

Each time formatter is a function which generates output strings from input time values, expressed as UNIX timestamps in milliseconds. The formatting behavior of a formatter is defined by its format template and options.

Please refer to the DateTimeFormatterOptions type documentation for more information on individual formatting options.

Format templates are strings which contain zero or more fragments enclosed by curly braces ({}); For a given format template, an output string is generated from an input duration by replacing each fragment in the template with a string generated from the input. The parts of the template string that are not contained in any fragment are passed to the output unchanged. Each fragment defines how its replacement string is generated. There are two types of fragments:

• Integer fragment. In EBNF notation, these take the form {x} where x = 'M' | 'd' | 'w'. Each numeric fragment is replaced with an integer representation of the month (M), day of month (d), or day of week (w) part of the input time. The number of x characters in the definition controls the number of leading zeroes with which the output will be padded.
• Numeric fragment. In EBNF notation, these take the form {x}, ['?'], ['.', [{x}], ['(', {x}, ')']] where x = 'H' | 'h' | 'm' | 's'. Each numeric fragment is replaced with a numeric representation of the hour-24 (H), hour-12 (h), minute (m), or second (s) part of the input time. The number of x characters in the definition controls the number of leading zeroes with which the output will be padded. If the optional '?' character is present, the output will drop all digits to the left of the decimal point if all such digits are equal to 0. The total number of x characters to the right of the decimal point in the definition controls the decimal precision of the output. Trailing zeroes to the right of the decimal point will be added to the output to a number of decimal places equal to the number of non-parenthetical x characters to the right of the decimal point in the definition. If there are no x characters to the right of the decimal point in the definition, then the output will have infinite decimal precision with no extraneous trailing zeroes. Rounding behavior is always round down.
• Year fragment. In EBNF notation, these take the form 'YY' | 'YYYY'. Each year fragment is replaced with either the two-digit (YY) or unlimited-digit (YYYY) year of the input time.
• Month fragment. In EBNF notation, these take the form ('mon', ['.']) | ('MON', ['.']) | 'month' | 'MONTH'. Each month fragment is replaced with the name of the month of the input time. The case of the definition determines the case of the output. mon will use abbreviated names. The presence of the optional '.' character will add a period to the end of the abbreviated names.
• Day-of-week fragment. In EBNF notation, these take the form ('dy', ['.']) | ('DY', ['.']) | 'day' | 'DAY'. Each day-of-week fragment is replaced with the name of the day-of-week of the input time. The case of the definition determines the case of the output. dy will use abbreviated names. The presence of the optional '.' character will add a period to the end of the abbreviated names.
• AM/PM fragment. In EBNF notation, these take the form 'am' | 'a.m.' | 'AM' | 'A.M.'. Each AM/PM fragment is replaced with an AM/PM string depending on the time of day of the input. The case of the definition determines the case of the output. Use of periods in the definition will add periods to the output.

Example

const formatter = DateTimeFormatter.create('{dd}-{MM}-{YY}');
formatter(0);              // 01-01-70
formatter(1597723200000);  // 18-08-20

Example

const formatter = DateTimeFormatter.create('{HH}:{mm}:{ss}');
formatter(0);              // 00:00:00
formatter(5145000);        // 01:25:45
formatter(57600000);       // 16:00:00

Example

const formatter = DateTimeFormatter.create('{hh}:{mm}:{ss} {am}');
formatter(0);              // 12:00:00 am
formatter(5145000);        // 01:25:45 am
formatter(57600000);       // 04:00:00 pm

Example

const formatter = DateTimeFormatter.create('{H}:{mm.m(m)}');
formatter(0);              // 0:00.0
formatter(5145000);        // 1:25.75

Example

const formatter = DateTimeFormatter.create('{YYYY}-{MM}-{dd}T{HH}:{mm}:{ss}');
formatter(0);              // 1970-01-01T00:00:00
formatter(1597723200000);  // 2020-08-18T04:00:00

Constructors

constructor

• new DateTimeFormatter(): DateTimeFormatter

Returns

DateTimeFormatter

Properties

DEFAULT_OPTIONS

▪ Static Readonly DEFAULT_OPTIONS: Readonly<DateTimeFormatterOptions>

Defined in

src/sdk/graphics/text/DateTimeFormatter.ts:118

Methods

create

▸ create(format, options?): (time: number) => string

Creates a function which formats times, expressed as UNIX timestamps in milliseconds, to strings. The formatting behavior of the function is defined by a specified format template and options. For more information on format templates and their syntax, please refer to the DateTimeFormatter class documentation. For more information on individual formatting options, please refer to the DateTimeFormatterOptions type documentation.

Parameters

Name	Type	Description
format	string	A template defining how the function formats durations.
options?	Readonly<Partial<DateTimeFormatterOptions>>	Options to customize the formatter. Options not explicitly defined will be set to the following default values: monthNames = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'] monthNamesShort = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] dayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'] dayNamesShort = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'] * nanString = 'NaN'

Returns

fn

A function which formats times, expressed as UNIX timestamps in milliseconds, to strings.

▸ (time): string

Parameters

Name	Type
time	number

Returns

string

Defined in

src/sdk/graphics/text/DateTimeFormatter.ts:148