Class: DurationFormatter

Defined in: src/sdk/graphics/text/DurationFormatter.ts:75

A utility class for creating duration formatters.

Each duration formatter is a function which generates output strings from input duration values. The formatting behavior of a formatter is defined by its format template.

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:

• Sign fragment. In EBNF notation, these take the form ['+', ['[', x, ']']], ('-' , ['[', y, ']']), where x and y are arbitrary strings. Each sign fragment is replaced with a string representing the sign of the input. The negative sign string is defined by y. If y is not defined, the negative sign string defaults to '-' (dash). The positive sign string is defined by x. If the positive sign token does not appear in the fragment definition, the positive sign string defaults to '' (the empty string), otherwise it defaults to '+'.
• Numeric fragment. In EBNF notation, these take the form {x}, ['?'], ['.', [{x}], ['(', {x}, ')']], where x = 'H' | 'M' | 'S' | 'h' | 'm' | 's'. Each numeric fragment is replaced with the numeric value of the duration in hours, minutes, or seconds, depending on which character is used for x. With uppercase letters, the entire portion of the input value is used. With lowercase letters, only the portion of the input value that does not divide evenly into the next smallest unit is used (for hours, which is the largest unit, there is no difference between using 'H' and 'h').
  • The number of x characters to the left of the decimal point (including all characters if no decimal point is present) 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.

Examples

const formatter = DurationFormatter.create('{h}:{mm}:{ss}', UnitType.SECOND);
formatter(3616);       // 1:00:16
formatter(36016.9);    // 10:00:16

const formatter = DurationFormatter.create('{h}:{mm}:{ss.s(s)}', UnitType.SECOND);
formatter(3600);       // 1:00:00.0
formatter(3600.55);    // 1:00:00.55

const formatter = DurationFormatter.create('{MM}:{ss}', UnitType.SECOND);
formatter(600);        // 10:00
formatter(4200);       // 70:00

const formatter = DurationFormatter.create('{-}{h}:{mm}', UnitType.SECOND);
formatter(3600);                   // 1:00
formatter(-3600);                  // -1:00

const formatterWithPositiveSign = DurationFormatter.create('{+-}{h}:{mm}', UnitType.SECOND);
formatterWithPositiveSign(3600);   // +1:00

const formatterWithRealMinusSign = DurationFormatter.create('{-[–]}{h}:{mm}', UnitType.SECOND);
formatterWithRealMinusSign(3600);  // –1:00

Constructors

Constructor

new DurationFormatter(): DurationFormatter

Returns

DurationFormatter

Properties

DEFAULT_OPTIONS

readonly static DEFAULT_OPTIONS: Readonly<DurationFormatterOptions>

Defined in: src/sdk/graphics/text/DurationFormatter.ts:90

The default options for duration formatters.

Methods

create()

Call Signature

static create(format, unit, precision, nanString?): (duration) => string

Defined in: src/sdk/graphics/text/DurationFormatter.ts:108

Creates a function which formats durations, expressed as numeric values, to strings. The formatting behavior of the function is defined by a specified format template. For more information on format templates and their syntax, please refer to the DurationFormatter class documentation. All formatter options except nanString, if specified, will use their default values.

Parameters

Parameter	Type	Description
format	string	A template defining how the function formats durations.
unit	Unit<Duration>	The unit type in which the input duration values are expressed.
precision	number	The precision of the formatter, in the unit type defined by the unit argument. Input values will be rounded to the nearest multiple of this quantity. Precision values less than or equal to zero will be taken to mean infinite precision (i.e. no rounding will take place).
nanString?	string	The string to output when the input duration is NaN. Defaults to 'NaN'.

Returns

A function which formats durations, expressed as numeric values, to strings.

(duration): string

Parameters

Parameter	Type
duration	number

Returns

string

Call Signature

static create(format, unit, precision, options?): (duration) => string

Defined in: src/sdk/graphics/text/DurationFormatter.ts:129

Creates a function which formats durations, expressed as numeric values, to strings. The formatting behavior of the function is defined by a specified format template. For more information on format templates and their syntax, please refer to the DurationFormatter class documentation.

Parameters

Parameter	Type	Description
format	string	A template defining how the function formats durations.
unit	Unit<Duration>	The unit type in which the input duration values are expressed.
precision	number	The precision of the formatter, in the unit type defined by the unit argument. Input values will be rounded to the nearest multiple of this quantity. Precision values less than or equal to zero will be taken to mean infinite precision (i.e. no rounding will take place).
options?	Readonly<Partial<DurationFormatterOptions>>	Options to configure the formatter. Options not explicitly defined will be set to the following default values: * nanString = 'NaN' * cache = false

Returns

A function which formats durations, expressed as numeric values, to strings.

(duration): string

Parameters

Parameter	Type
duration	number

Returns

string

---

createForNumberUnit()

Call Signature

static createForNumberUnit(format, precision, nanString?): (duration) => string

Defined in: src/sdk/graphics/text/DurationFormatter.ts:197

Creates a function which formats durations, expressed as NumberUnitInterface objects, to strings. The formatting behavior of the function is defined by a specified format template. For more information on format templates and their syntax, please refer to the DurationFormatter class documentation. All formatter options except nanString, if specified, will use their default values.

Parameters

Parameter	Type	Description
format	string	A template defining how the function formats durations.
precision	NumberUnitInterface<Duration>	The precision of the formatter. Input values will be rounded to the nearest multiple of this quantity. Precision values less than or equal to zero will be taken to mean infinite precision (i.e. no rounding will take place).
nanString?	string	The string to output when the input duration is NaN. Defaults to 'NaN'.

Returns

A function which formats durations, expressed as NumberUnitInterface objects, to strings.

(duration): string

Parameters

Parameter	Type
duration	NumberUnitInterface<Duration>

Returns

string

Call Signature

static createForNumberUnit(format, precision, options?): (duration) => string

Defined in: src/sdk/graphics/text/DurationFormatter.ts:216

Creates a function which formats durations, expressed as NumberUnitInterface objects, to strings. The formatting behavior of the function is defined by a specified format template. For more information on format templates and their syntax, please refer to the DurationFormatter class documentation.

Parameters

Parameter	Type	Description
format	string	A template defining how the function formats durations.
precision	NumberUnitInterface<Duration>	The precision of the formatter. Input values will be rounded to the nearest multiple of this quantity. Precision values less than or equal to zero will be taken to mean infinite precision (i.e. no rounding will take place).
options?	Readonly<Partial<DurationFormatterOptions>>	Options to configure the formatter. Options not explicitly defined will be set to the following default values: * nanString = 'NaN' * cache = false

Returns

A function which formats durations, expressed as NumberUnitInterface objects, to strings.

(duration): string

Parameters

Parameter	Type
duration	NumberUnitInterface<Duration>

Returns

string