Skip to Main Content

# Namespace: locale

## QuickNav

## apex.locale

The apex.locale namespace contains Oracle APEX functions related to formatting numbers and dates according to a specific locale. For localizing text messages see apex.lang.

Since:
  - 20.1

### Functions

#### (static) formatCompactNumber(pValue, pOptionsopt) → {string}

Formats the given number in a compact, locale specific way. For example in the US English locale the number 123400 would be formatted as "123.4K" and 1234000 as "1.23M".

This function relies on additional resources that are loaded when the page first loads. Calling this function before the resources are loaded returns the number as an unformatted string. See apex.locale.resourcesLoaded.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pValue` | number |  | The number value to be formatted.
`pOptions` | object | <optional> | An options object that affect the way the number is formatted. All properties optional. ###### Properties
Name | Type | Description
--- | --- | ---
`maximumFractionDigits` | number | The maximum number of digits to display after the decimal point. Default 2.
`minimumFractionDigits` | number | The minimum number of digits to display after the decimal point. Default 0.
`minimumIntegerDigits` | number | The minimum number of integer digits to display before the decimal point. Default 1.
`roundingMode` | string | One of 'DEFAULT', 'HALF_UP', 'HALF_DOWN', 'HALF_EVEN', 'UP', 'DOWN', 'CEILING', 'FLOOR'. The default is "DEFAULT".
`separators` | string | The characters to use for the decimal and group separator. The default is to use the appropriate locale specific characters. ###### Properties
Name | Type | Description
--- | --- | ---
`decimal` | string | The decimal separator character.
`group` | string | The group separator character.
`useGrouping` | boolean | If true use locale specific rules to separate digits into groups. The default is true.

##### Returns:

The compact formatted number.

Type
  string

##### Examples

Format the large number 123456789.12 in a compact format and display it in an alert message.

    var largeNumber = 123456789.12;
    var formattedNumber = apex.locale.formatCompactNumber( largeNumber );
    // In the US English locale this will display: "The number is: 123.46M"
    apex.message.alert( "The number is: " + formattedNumber, function() {
         // do something after message is shown if needed
    } );

Format the same large number 123456789.12 in a compact format using an option to not include any fraction digits.

    var largeNumber = 123456789.12;
    var formattedNumber = apex.locale.formatCompactNumber( largeNumber, { maximumFractionDigits: 0 } );
    // In the US English locale the formattedNumber is equal to 123M"

#### (static) formatNumber(pValue, pFormatopt, pOptionsopt) → {string}

Formats a number using a database format model similar to the SQL `TO_CHAR(number)` function.

See the Oracle SQL Language reference section on Format Models for more information on the pFormat parameter. The format elements RN, TM, and EEEE are not supported.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pValue` | number |  | The number to format.
`pFormat` | string | <optional> | The database format model. The format elements RN, TM, and EEEE are not supported. If the format is not given the number is returned as a string with only the decimal separator replaced with the locale specific decimal separator.
`pOptions` | object | <optional> | Options to override default locale settings. All properties optional. ###### Properties
Name | Type | Description
--- | --- | ---
`NLS_NUMERIC_CHARACTERS` | string | A string where the first letter is the decimal separator and the second letter is the group separator
`NLS_CURRENCY` | string | The local currency string.
`NLS_DUAL_CURRENCY` | string | The dual currency string.
`NLS_ISO_CURRENCY` | string | The ISO currency string. Note: This option differs from the corresponding database parameter. It is the ISO currency string such as "CAD" rather than the territory name such as "CANADA".

##### Returns:

The formatted number.

Type
  string

##### Example

Format the number 1234.569 with locale specific currency symbol and 2 decimal places.

    var formattedNumber = apex.locale.formatNumber( 1234.569, "FML999G999G999G999G990D00" );
    // In the US English locale this will display: "The cost is: $1,234.57"
    apex.message.alert( "The cost is: " + formattedNumber, function() {
         // do something after message is shown if needed
    } );

#### (static) getAbbrevDayNames() → {array}

Return the database abbreviated day names as an array. First element of the array is the first day of the week in the current locale.

##### Returns:

Array of abbreviated day names. For example ["Sun","Mon","Tue","Wed",...,"Sat"]

Type
  array

#### (static) getAbbrevMonthNames() → {array}

Return the database abbreviated month names as an array. First element of the array is the first month of the year in the current locale.

##### Returns:

Array of abbreviated month names. For example ["Jan","Feb","Mar", ..., "Dec"]

Type
  array

#### (static) getCurrency() → {string}

Return the database locale specific currency symbol.

##### Returns:

Type
  string

#### (static) getDLDateFormat() → {string}

Return the database defined DL date format mask.

##### Returns:

DL Date format mask. For example "fmDay, Month fmdd, yyyy" or "fmDay, dd. Month yyyy"

Type
  string

#### (static) getDSDateFormat() → {string}

Return the database defined DS date format mask.

##### Returns:

DS Date format mask. For example "fmMM/DD/RRRR" or "DD.MM.RRRR"

Type
  string

#### (static) getDateFormat() → {string}

Return the database defined date format mask.

##### Returns:

Date format mask. For example "YYYY/MM/DD" or "DD.MM.YYYY"

Type
  string

#### (static) getDayNames() → {array}

Return the database day names as an array. First element of the array is the first day of the week in the current locale.

##### Returns:

Array of day names. For example ["Sunday","Monday","Tuesday","Wednesday", ...,"Saturday"]

Type
  array

#### (static) getDecimalSeparator() → {string}

Return the database locale specific decimal separator for numeric values.

##### Returns:

The decimal separator. For example "." (US) or "," (Germany).

Type
  string

#### (static) getDualCurrency() → {string}

Return the database locale specific dual currency symbol.

##### Returns:

Type
  string

#### (static) getGroupSeparator() → {string}

Return the database locale specific group separator for numeric values.

##### Returns:

The group separator. For example "," (US) or "." (Germany).

Type
  string

#### (static) getISOCurrency() → {string}

Return the database locale specific ISO currency string.

##### Returns:

Type
  string

#### (static) getLanguage() → {string}

Return the current language locale.

##### Returns:

current language. For example "en", "de", "en-US", ...

Type
  string

#### (static) getMonthNames() → {array}

Return the database month names as an array. First element of the array is the first month of the year in the current locale.

##### Returns:

Array of month names. For example ["January","February","March", ...,"December"]

Type
  array

#### (static) resourcesLoaded(pCallbackopt) → {Promise}

Used to determine if the resources needed by some of the apex.locale functions have been loaded.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pCallback` | function | <optional> | A Function to call when the resources have been loaded. If the resources are already loaded the function is called right away.

##### Returns:

A promise object. The promise is resolved when the resources have been loaded.

Type
  Promise

##### Examples

Wait until the resources are loaded before formatting a number.

    apex.locale.resourcesLoaded( function() {
        var formattedNumber = apex.locale.formatCompactNumber( 123456789.12 );
        // In the US English locale this will log: "The number is: 123.46M"
        console.log( "The number is: " + formattedNumber );
    } );

This is the same as the previous example except it uses the returned promise.

    var p = apex.locale.resourcesLoaded();
    p.done( function() {
        var formattedNumber = apex.locale.formatCompactNumber( 123456789.12 );
        // In the US English locale this will log: "The number is: 123.46M"
        console.log( "The number is: " + formattedNumber );
    } );

This checks to see if the resources are loaded.

    if ( apex.locale.resourcesLoaded().state() === "resolved" ) {
        // resources are loaded
    } else {
        // resources are not yet loaded
    }

#### (static) toNumber(pValue, pFormatopt) → {number}

Convert the given string value into a number. It does not strictly validate against the given format but will strip potential format characters from the number so it can be converted to a number. The intention is to allow natural human data entry of numbers. The locale decimal and group separators are considered. If the number exceeds the precision of a JavaScript number (IEEE 754) then NaN is returned unless the loss of precision is to the right of the decimal point and any decimal places specified in the format mask.

The octal (0o) and binary (0b) prefixes are never allowed. Only when the format model is hex, the hex (0x) prefix is allowed but not required. Although the scientific notation format model (EEEE) is not supported, strings in scientific notation will be converted using the locale specific decimal separator but group separators and currency symbols are not allowed.

##### Parameters:

Name | Type | Attributes | Description
--- | --- | --- | ---
`pValue` | string |  | The potentially formatted or partially formatted number string to convert.
`pFormat` | string | <optional> | The optional expected format of the value to convert. This is a database format model. The format elements V, RN, TM, and EEEE are not supported and will be ignored.

##### Returns:

the converted number or NaN if pValue cannot be converted to a number

Type
  number

##### Examples

In a locale that uses comma as the group separator, period as the decimal separator and $ as the locale currency symbol the following all result in the same number 1234.56.

    var number = apex.locale.toNumber( "1,234.56" );
    number = apex.locale.toNumber( "$1,234.56", "FML999G999G990D00" );
    number = apex.locale.toNumber( "$1234.56", "FML999G999G990D00" );
    // number is 1234.56

In a locale that uses period as the group separator, comma as the decimal separator and € as the locale currency symbol the following all result in the same number 1234.56.

    var number = apex.locale.toNumber( "1.234,56" );
    number = apex.locale.toNumber( "&#x20AC;1.234,56", "FML999G999G990D00" );
    number = apex.locale.toNumber( "&#x20AC;1234,56", "FML999G999G990D00" );
    // number is 1234.56