Class: Formatters


Default number formatting functions in the style of ICU's simpleArg syntax implemented using the Intl object defined by ECMA-402.

In MessageFormat source, a formatter function is called with the syntax {var, name, arg}, where var is a variable, name is the formatter name (by default, either date, duration, number or time; spellout and ordinal are not supported by default), and arg is an optional string argument.

In JavaScript, a formatter is a function called with three parameters:

  • The value of the variable; this can be of any user-defined type
  • The current locale code
  • The trimmed arg string value, or null if not set

As formatter functions may be used in a precompiled context, they should not refer to any variables that are not defined by the function parameters or within the function body. To add your own formatter, either add it to the static MessageFormat.formatters object, or use MessageFormat#addFormatters to add it to a MessageFormat instance.

Methods


<static> date(value [, type])

Represent a date as a short/default/long/full string

The input value needs to be in a form that the Date object can process using its single-argument form, new Date(value).

Parameters:
Name Type Argument Default Description
value number | string

Either a Unix epoch time in milliseconds, or a string value representing a date

type string <optional>
'default'

One of 'short', 'default', 'long' , or full

Source:
Example
var mf = new MessageFormat(['en', 'fi']);

mf.compile('Today is {T, date}')({ T: Date.now() })
// 'Today is Feb 21, 2016'

mf.compile('Tänään on {T, date}', 'fi')({ T: Date.now() })
// 'Tänään on 21. helmikuuta 2016'

mf.compile('Unix time started on {T, date, full}')({ T: 0 })
// 'Unix time started on Thursday, January 1, 1970'

var cf = mf.compile('{sys} became operational on {d0, date, short}');
cf({ sys: 'HAL 9000', d0: '12 January 1999' })
// 'HAL 9000 became operational on 1/12/1999'

<static> duration(value)

Represent a duration in seconds as a string

Input should be a finite number; output will include one or two : separators, and match the pattern hhhh:mm:ss, possibly with a leading - for negative values and a trailing .sss part for non-integer input

Parameters:
Name Type Description
value number | string

A finite number, or its string representation

Source:
Example
var mf = new MessageFormat();

mf.compile('It has been {D, duration}')({ D: 123 })
// 'It has been 2:03'

mf.compile('Countdown: {D, duration}')({ D: -151200.42 })
// 'Countdown: -42:00:00.420'

<static> number(value, type)

Represent a number as an integer, percent or currency value

Available in MessageFormat strings as {VAR, number, integer|percent|currency}. Internally, calls Intl.NumberFormat with appropriate parameters. currency will default to USD; to change, set MessageFormat#currency to the appropriate three-letter currency code, or use the currency:EUR form of the argument.

Parameters:
Name Type Description
value number

The value to operate on

type string

One of 'integer', 'percent' , 'currency', or /currency:[A-Z]{3}/

Source:
Example
var mf = new MessageFormat('en');
mf.currency = 'EUR';  // needs to be set before first compile() call

mf.compile('{N} is almost {N, number, integer}')({ N: 3.14 })
// '3.14 is almost 3'

mf.compile('{P, number, percent} complete')({ P: 0.99 })
// '99% complete'

mf.compile('The total is {V, number, currency}.')({ V: 5.5 })
// 'The total is €5.50.'

mf.compile('The total is {V, number, currency:GBP}.')({ V: 5.5 })
// 'The total is £5.50.'

<static> time(value [, type])

Represent a time as a short/default/long string

The input value needs to be in a form that the Date object can process using its single-argument form, new Date(value).

Parameters:
Name Type Argument Default Description
value number | string

Either a Unix epoch time in milliseconds, or a string value representing a date

type string <optional>
'default'

One of 'short', 'default', 'long' , or full

Source:
Example
var mf = new MessageFormat(['en', 'fi']);

mf.compile('The time is now {T, time}')({ T: Date.now() })
// 'The time is now 11:26:35 PM'

mf.compile('Kello on nyt {T, time}', 'fi')({ T: Date.now() })
// 'Kello on nyt 23.26.35'

var cf = mf.compile('The Eagle landed at {T, time, full} on {T, date, full}');
cf({ T: '1969-07-20 20:17:40 UTC' })
// 'The Eagle landed at 10:17:40 PM GMT+2 on Sunday, July 20, 1969'