API Referencefunction

function fmt()

Returns a (lazily) formatted string incorporating the provided values.

function fmt(
  format: StringConvertible | StringConvertible[],
  ...values: any[]
): DeferredString;

Parameters

• format — The format string, which may include placeholders for dynamically formatted values; or an array passed by a template literal source
• values — Any number of values to include in the result; if no values are provided, the result is a DeferredString instance that can be formatted later

Return value

An instance of DeferredString.

Description

This function creates a new instance of DeferredString with the specified format string. When converted to a string, the text is translated, formatted, and cached (until the cache is invalidated, e.g. when the application I18n provider is changed).

The syntax of placeholders is as follows:

• {}: inserts the value at the current position of the argument list.
• {:f}: inserts the value at the current position, formatted using the format f (see below).
• {0} or {p}: inserts the value at the position 0 (any number) in the argument list, OR a property p of the first argument as an object.
• {0:f} or {p:f}: inserts the value of argument 0 or property p as above, formatted using the format f (see below).
• {#...}: ignored (i.e. removed from the result). This can be used to insert a comment or a marker that may be used for translation.

The following set of format specifiers can be used to format each value:

• :s: inserts the value as a string (default if the value is not a number).
• :d: inserts the value as a number (with at most 6 decimal places; default if the value is a number).
• :.2d: inserts the value as a number with at most 2 decimal places (or any number as specfied).
• :.2f: inserts the value as a fixed-point number, with 2 decimal places (or any number as specfied).
• :i: inserts the value as a rounded integer.
• :x: inserts the value as a hexadecimal number.
• :X: inserts the value as a hexadecimal number in uppercase.
• :L...: inserts the value as a localized string, using the current i18n provider and the type immediately following the L (e.g. L, Ldate, Ltime). The format string is split on / characters, with each part passed as a separate argument (e.g. Ldate/short).
• :?/foo/bar: inserts foo or bar if the value is equal to boolean true or false, respectively.
• :+/foo/bar: inserts one of the options, depending on the value and the current i18n pluralization rules; defaults to foo only if the value is 1, if no i18n provider is available.

Within all format specifiers, additional placeholders such as {0} or {p} can be used to insert the value of another value from the argument list, or a property of the first argument as an object — e.g. for number of decimal places, or replacements passed to the ? placeholder. Such nested placeholders cannot contain format specifiers themselves.

Examples

// Format a string including a single number:
let s = fmt("Package weight: {} kg", 75.5);
String(s) // => "Package weight: 75.5 kg"

// Format a string including a single number:
let s = fmt("Package weight: {:.2f} kg", weight);
String(s) // => "Package weight: 75.50 kg"

// Format a string with multiple values:
let s = fmt("Customer ID {}: {}", 123, "John Doe");
String(s) // => "Customer ID 123: John Doe"

// or more explicitly:
let s = fmt("Customer ID {0}: {1}", 123, "John Doe");
String(s) // => "Customer ID 123: John Doe"

// ...or using an object:
let s = fmt("Customer ID {id}: {name}", { id: 123, name: "John Doe" });
String(s) // => "Customer ID 123: John Doe"

// Format a string with boolean check and pluralization:
let s = fmt("You have {:?/{0}/no} {0:+/message/messages}", 0);
String(s) // => "You have no messages"