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
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
|
Returns:
- 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"
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
|
Returns:
- 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
} );
Returns:
- Type
- array
Returns:
- Type
- array
Returns:
- Type
- string
Returns:
- Type
- string
Returns:
- Type
- array
Returns:
- Type
- string
Returns:
- Type
- string
Returns:
- Type
- string
Returns:
- Type
- string
Returns:
- Type
- string
Returns:
- Type
- string
Returns:
- Type
- string
Returns:
- Type
- array
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:
- 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
}
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.
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:
- 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( "€1.234,56", "FML999G999G990D00" );
number = apex.locale.toNumber( "€1234,56", "FML999G999G990D00" );
// number is 1234.56