# Global.Intl.NumberFormat

> Immutable object used to convert numbers to localized numeric strings.

- Source: https://titaniumsdk.com/docs/sdk/13.1.1/Global.Intl.NumberFormat
- Titanium SDK version: 13.1.1
- Kind: module
- Platforms: Android, iPhone, iPad, macOS
- Since: Titanium SDK iPhone 6.0.0, iPad 6.0.0, Android 9.1.0, macOS 9.2.0

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](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat).

## Example: Format with Leading Zeros

``` js
// 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));
```

## Example: Round to Significant Digits

``` js
// 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));
```

## Example: Currency Format

``` js
// 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));
```

## Example: Percentage Format

``` js
// 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));
```

## Example: Scientific Notation (Android Only)

``` js
// 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

- Type: Global.Intl.NumberFormat
- Platforms: Android, iPhone, iPad, macOS
- Permission: read-only

Creates a new `Intl.NumberFormat` object with the given locale and formatting options.

#### Syntax

``` js
new Intl.NumberFormat([locales[, options]])
```

#### Parameters

*    `locales`: [String](https://titaniumsdk.com/docs/sdk/Global.String.md)/[String](https://titaniumsdk.com/docs/sdk/Global.String.md)`[]` (optional)

     The [BCP 47](https://www.unicode.org/reports/tr35/tr35.html#BCP_47_Conformance) 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 [Titanium.Locale.currentLocale](https://titaniumsdk.com/docs/sdk/Titanium.Locale.md#currentLocale).

*    `options`: [NumberFormatOptions](https://titaniumsdk.com/docs/sdk/NumberFormatOptions.md) (optional)

     Provides settings indicating how a number should be formatted to a string.

## Methods

### format

- Platforms: Android, iPhone, iPad, macOS

Formats the given number to a localized numeric string.

Parameters:

- `value` (Number): The number to be formatted.

Returns: String - The localized numeric string.

### formatToParts

- Platforms: Android, iPhone, iPad, macOS
- Requires: iOS 13.0+

Formats given number to an array of components describing what the formatted 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 characters, currency characters,
currency symbol positions, etc.

For more detail, see the MDN website about
[formatToParts](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/formatToParts).

Parameters:

- `value` (Number): The number to be formatted into parts.

Returns: Array<NumberFormattedPart> - Array of objects providing the "type" and "value" of each component in formatted string.

### resolvedOptions

- Platforms: Android, iPhone, iPad, macOS

Gets the object's formatting options.

Returns the formatting options the format object uses.

For more detail, see the MDN website about
[resolvedOptions](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/resolvedOptions).

Returns: NumberFormatOptions - Returns the formatting options used.

### supportedLocalesOf

- Platforms: Android, iPhone, iPad, macOS

Static method indicating what locales are supported by `NumberFormat` from the given locale(s).

For more detail, see the MDN website about
[supportedLocalesOf](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/supportedLocalesOf).

Parameters:

- `locales` (String | Array<String>): A string or array of strings providing BCP 47 locale identifiers to query.

Returns: Array<String> - Array containing a subset of the given locale strings supported by `NumberFormat` objects.

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.