Documentation

Class

DurationFmt

DurationFmt(optionsnullable)

Create a new duration formatter instance. The duration formatter is immutable once it is created, but can format as many different durations as needed with the same options. Create different duration formatter instances for different purposes and then keep them cached for use later if you have more than one duration to format.

Duration formatters format lengths of time. The duration formatter is meant to format durations of such things as the length of a song or a movie or a meeting, or the current position in that song or movie while playing it. If you wish to format a period of time that has a specific start and end date/time, then use a [DateRngFmt] instance instead and call its format method.

The options may contain any of the following properties:

  • locale - locale to use when formatting the duration. If the locale is not specified, then the default locale of the app or web page will be used.
  • 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 duration. This is the most compact format possible for the locale. eg. 1y 1m 1w 1d 1:01:01
    • medium - use a medium length representation of the duration. This is a slightly longer format. eg. 1 yr 1 mo 1 wk 1 dy 1 hr 1 mi 1 se
    • long - use a long representation of the duration. This is a fully specified format, but some of the textual parts may still be abbreviated. eg. 1 yr 1 mo 1 wk 1 day 1 hr 1 min 1 sec
    • full - use a full representation of the duration. This is a fully specified format where all the textual parts are spelled out completely. eg. 1 year, 1 month, 1 week, 1 day, 1 hour, 1 minute and 1 second
  • style - whether hours, minutes, and seconds should be formatted as a text string or as a regular time as on a clock. eg. text is "1 hour, 15 minutes", whereas clock is "1:15:00". Valid values for this property are "text" or "clock". Default if this property is not specified is "text".
  • useNative - the flag used to determaine whether to use the native script settings for formatting the numbers .
  • onLoad - a callback function to call when the format data is fully loaded. When the onLoad option is given, this class 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.

Constructor

# new DurationFmt(optionsnullable)

Parameters:
Name Type Attributes Description
options Object <nullable>

options governing the way this date formatter instance works

View Source DurationFmt.js, line 95

Methods

# format(components) → {IString}

Format a duration according to the format template of this formatter instance.

The components parameter should be an object that contains any or all of these numeric properties:

  • year
  • month
  • week
  • day
  • hour
  • minute
  • second

When a property is left out of the components parameter or has a value of 0, it will not be formatted into the output string, except for times that include 0 minutes and 0 seconds.

This formatter will not ensure that numbers for each component property is within the valid range for that component. This allows you to format durations that are longer than normal range. For example, you could format a duration has being "33 hours" rather than "1 day, 9 hours".

Parameters:
Name Type Description
components Object

date/time components to be formatted into a duration string

View Source DurationFmt.js, line 353

a string with the duration formatted according to the style and locale set up for this formatter instance. If the components parameter is empty or undefined, an empty string is returned.

IString

# getLength() → {string}

Return the length that was used to construct this duration formatter object. If the length was not given as parameter to the constructor, this method returns the default length. Valid values are "short", "medium", "long", and "full".

View Source DurationFmt.js, line 406

length that this duration formatter was constructed with

string

# getLocale() → {Locale}

Return the locale that was used to construct this duration formatter object. If the locale was not given as parameter to the constructor, this method returns the default locale of the system.

View Source DurationFmt.js, line 395

locale that this duration formatter was constructed with

Locale

# getStyle() → {string}

Return the style that was used to construct this duration formatter object. Returns one of "text" or "clock".

View Source DurationFmt.js, line 416

style that this duration formatter was constructed with

string