Class ilib.DurFmt
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 [ilib.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.
Depends directive: !depends durfmt.js
Defined in: ilib-dyn-full.js.
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
ilib.DurFmt(options)
|
| Method Attributes | Method Name and Description |
|---|---|
|
format(components)
Format a duration according to the format template of this formatter instance.
|
|
|
Return the length that was used to construct this duration formatter object.
|
|
|
Return the locale that was used to construct this duration formatter object.
|
|
|
getStyle()
Return the style that was used to construct this duration formatter object.
|
- Parameters:
- {?Object} options
- options governing the way this date formatter instance works
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:
- {Object} components
- date/time components to be formatted into a duration string
- Returns:
- {ilib.String} 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.
- Returns:
- {string} length that this duration formatter was constructed with
- Returns:
- {ilib.Locale} locale that this duration formatter was constructed with
- Returns:
- {string} style that this duration formatter was constructed with