# Global.Intl.NumberFormat
Immutable object used to convert numbers to localized numeric strings.
# Overview
A NumberFormat
object is used to convert a Number
value to a localized numeric string.
It provides various formatting options controlling the number of integer and fractional digits
to be displayed. It can also output currency values, percentage based values, and
scientific notation.
For more detail, see the MDN website about Intl.NumberFormat (opens new window).
# Examples
# Format with Leading Zeros
// Set up to pad first 3 integer digits with zeros if needed.
const formatter = new Intl.NumberFormat(Ti.Locale.currentLocale, {
minimumIntegerDigits: 3,
useGrouping: false
});
// Logs: 000
console.log(formatter.format(0));
// Logs: 001
console.log(formatter.format(1));
// Logs: 001.23
console.log(formatter.format(1.23));
// Logs: 12345
console.log(formatter.format(12345));
# Round to Significant Digits
// Round up to 3 significant digits.
// All trailing non-fractional digits will be zero.
const formatter = new Intl.NumberFormat(Ti.Locale.currentLocale, {
maximumSignificantDigits: 3,
useGrouping: false
});
// Logs: 12300
console.log(formatter.format(12345.6));
// Logs: -12300
console.log(formatter.format(-12345.6));
// Logs: 1.23
console.log(formatter.format(1.23456));
# Currency Format
// Set up currency style format options.
const options = {
style: 'currency',
maximumFractionDigits: 2,
minimumFractionDigits: 2,
useGrouping: true
};
// Format in dollars in USA. Logs: $1,000.00
// Note that the "currency" option is required.
let formatter = Intl.NumberFormat('en-US', Object.assign({ currency: 'USD' }, options));
console.log(formatter.format(1000));
// Format in euros in USA. Logs: €1,000.00
formatter = Intl.NumberFormat('en-US', Object.assign({ currency: 'EUR' }, options));
console.log(formatter.format(1000));
// Format in euros in Germany. Logs: 1.000,00 €
formatter = Intl.NumberFormat('de-DE', Object.assign({ currency: 'EUR' }, options));
console.log(formatter.format(1000));
// Format in dollars in Germany. Logs: 1.000,00 $
formatter = Intl.NumberFormat('de-DE', Object.assign({ currency: 'USD' }, options));
console.log(formatter.format(1000));
# Percentage Format
// Set up percentage style numeric formatting.
const formatter = new Intl.NumberFormat(Ti.Locale.currentLocale, {
style: 'percent',
maximumFractionDigits: 1,
minimumFractionDigits: 1,
useGrouping: false
});
// Logs: 25.0%
console.log(formatter.format(0.25));
// Logs: 100.0%
console.log(formatter.format(1.0));
// Logs: 1234.5%
console.log(formatter.format(12.345));
// Logs: 1234.6%
// Since value exceeds "maximumFractionDigits" of 1, it is rounded.
console.log(formatter.format(12.3456));
# Scientific Notation (Android Only)
// Logs: 1.235E5
// Decimal point will be a period, comma, or space depending on the locale.
const formatter = new Intl.NumberFormat(Ti.Locale.currentLocale, { notation: 'scientific' });
console.log(formatter.format(123456.7));
# Properties
# constructor READONLY
Creates a new Intl.NumberFormat
object with the given locale and formatting options.
# Syntax
new Intl.NumberFormat([locales[, options]])
# Parameters
-
locales
: Global.String/Global.String[]
(optional)The BCP 47 language and country code(s) to use for localized formatting. Can provide multiple locales where the best-supported locale will be favored in the order provided by the array. If parameter is not assigned, then the system may use the
'en-US'
locale by default instead of the system's current locale. It's recommended to set this parameter using currentLocale. -
options
: NumberFormatOptions (optional)Provides settings indicating how a number should be formatted to a string.
# Methods
# format
Formats the given number to a localized numeric string.
Parameters
Name | Type | Description |
---|---|---|
value | Number | The number to be formatted. |
Returns
The localized numeric string.
- Type
- String
# formatToParts
Formats given number to an array of components describing what the formmated string would produce.
Returns an array of objects providing the "type" and "value" of each component the formatted string would produce. Can be used to fetch localized separator chracters, currency characters, currency symbol positions, etc.
For more detail, see the MDN website about formatToParts.
Parameters
Name | Type | Description |
---|---|---|
value | Number | The number to be formatted into parts. |
Returns
Array of objects providing the "type" and "value" of each component in formatted string.
- Type
- Array<NumberFormattedPart>
# resolvedOptions
Gets the object's formatting options.
Returns the formatting options the format object uses.
For more detail, see the MDN website about resolvedOptions.
Returns
Returns the formatting options used.
- Type
- NumberFormatOptions
# supportedLocalesOf
Static method indicating what locales are supported by NumberFormat
from the given locale(s).
For more detail, see the MDN website about supportedLocalesOf.
Parameters
Name | Type | Description |
---|---|---|
locales | String | Array<String> | A string or array of strings providing BCP 47 locale identifiers to query. |
Returns
Array containing a subset of the given locale strings supported by NumberFormat
objects.
- Type
- Array<String>