numToWords
Converts a number to words.
The optional parameters allow you to choose cardinal or ordinal form, define the threshold for number-to-word conversion, and select a word for representing the value 0.
Parameters
NUMBER (number)
The input number. Can be an integer or a decimal. The function formats the number before performing the number-to-words conversion. To understand this better, see decimal examples.
TYPE (string)
Optional. Whether to convert the number in cardinal or ordinal form. Cardinal numbers describe quantity (e.g. one pot) whereas ordinal numbers signify relative position (e.g. first in line).
Default: cardinal
THRESHOLD (number or string)
Optional. Defines the maximum value for which the number-to-word conversion occurs. If set to 12, only numbers <= 12 are converted. Set to wordsOnly to convert any number.
Default: wordsOnly
ZERO FORMAT (string)
Optional. How to express 0 in words. Options: zero, no, none, or a string of your choice.
Default: zero
Examples
ATL in Script | Result |
|---|---|
| three |
| third |
| 3rd |
| eleven |
| twelve |
| 13 |
| zero |
| zilch |
Decimal examples
Assume the settings in Settings > Number and Currency are:
Setting | Value |
|---|---|
LOCALE |
|
NUMBER FORMAT |
|
The NUMBER FORMAT setting ensures number are, by default, formatted to two decimal places with trailing zeros stripped. numToWords applies this formatting before the number-to-words conversion.
ATL in Script | Result |
|---|---|
| one point two three |
| 1.23 |
In both cases, the input number is formatted as 1.23 (as per the NUMBER FORMAT pattern), then converted to words. The second result is 1.23 because decimals can't be expressed in ordinal form.
Important
The default formatting works differently in legacy projects. See Legacy Behaviors.
You can override the project's default number format pattern using formatting functions. However, numToWords does not spell out trailing zeros, even if the number is formatted to display them.
ATL in Script | Result |
|---|---|
| one hundred twenty-five |
Here, the input number is formatted as 125.000 prior to the conversion. Note, however, that the decimal point and three trailing zeros are not included in the output text.
numToWords with locales
A locale is a code representing a language and country. In number formatting, the locale defines which characters are used for decimal and thousand separators in the printed output.
The default locale en_US (English, United States) uses a period (full stop) for the decimal separator and a comma for thousand separators. Other locales use different characters. For example, de_DE (German, Germany) uses a comma for the decimal separator and a period for thousand separators.
numToWords performs its number-to-words conversion of a formatted number regardless of what locale applies; however, the output text is always in English. For example:
ATL in Script | Result |
|---|---|
| 500,000.00 |
| Five hundred thousandth |
| 500.000,00 |
| Five hundred thousandth |
Important
Calls such as [[numToWords(500.000,00)]] or [[numToWords('500.000,00')]] produce errors. This is because an input literal or string must use a period (full stop) for the decimal separator and a comma for any thousand separators.
