Skip to main content

abbreviateNumber

Abbreviates a large number and displays it with an appropriate suffix.

You can abbreviate numbers at the levels of thousands, millions, billions, and trillions. You can define your own suffixes or select from the parameter dropdowns in the Function Builder.

You can define default values for this function in the project settings — see Settings > Number and Currency.

Parameters

  • VALUE (number)

    The number to abbreviate.

  • THRESHOLD (number)

    Optional. The number below which no abbreviation occurs. Enter a value of your choice or choose a suggested value from the parameter dropdown in the Function Builder.

    Default: 1000

  • THOUSANDS (string)

    Optional. The suffix for abbreviating values in the thousands. Define your own suffix or select one from the parameter dropdown in the Function Builder. The dropdown options: K, k, thousand, and none.

    Default: K

    Tip

    When this parameter is set to none, the function will not abbreviate at this level. The same principle applies to the MILLIONS, BILLIONS, and TRILLIONS parameters described below.

  • MILLIONS (string)

    Optional. The suffix for abbreviating values in the millions. Define your own suffix or select one from the parameter dropdown in the Function Builder. The dropdown options: M, MM, m, million, and none.

    Default: m

  • BILLIONS (string)

    Optional. The suffix for abbreviating values in the billions. Define your own suffix or select one from the parameter dropdown in the Function Builder. The dropdown options: B, Bn, Bil, b, bn, bil, billion, and none.

    Default: bn

  • TRILLIONS (string)

    Optional. The suffix for abbreviating values in the trillions. Define your own suffix or select one from the parameter dropdown in the Function Builder. The dropdown options: T, Tn, Tr, t, tn, tr, trillion, and none.

    Default: tn

Important

The default values above are the system defaults. You can change these defaults in your project settings — see Settings > Number and Currency for guidance.

The project settings also include DECIMAL PLACES FOR ABBREVIATION and STRIP TRAILING ZEROS FOR ABBREVIATION, which control the display precision for all abbreviated numbers.

Examples

Assume the settings in Settings > Number and Currency are:

Setting

Value

NUMBER FORMAT

#,##0.##

ABBREVIATION THRESHOLD

1000

THOUSAND SYMBOL

K

MILLION SYMBOL

m

BILLION SYMBOL

bn

TRILLION SYMBOL

tn

DECIMAL PLACES FOR ABBREVIATION

2

STRIP TRAILING ZEROS FOR ABBREVIATION

true

These examples don't use the optional parameters; therefore, the project settings apply.

ATL in Script

Result

[[abbreviateNumber(1245)]]

1.25K

[[abbreviateNumber(1245678)]]

1.25m

[[abbreviateNumber(1245678900)]]

1.25bn

[[abbreviateNumber(1245678900000)]]

1.25tn

These examples demonstrate use of the second parameter:

ATL in Script

Result

Notes

[[abbreviateNumber(1250,10000)]]

1,250

The THRESHOLD parameter is set to 10000. The input number is less than the threshold, so no abbreviation occurs.

[[abbreviateNumber(950,500)]]

0.95K

The THRESHOLD parameter is set to a value below the lowest abbreviation level, so the number is abbreviated to a fractional value below 1. The 'K' suffix applies as the project default.

To add a space between the number and suffix, just include a space in the parameter string:

ATL in Script

Result

Note

[[abbreviateNumber(1245,'',' K')]]

1.25 K

The blank space included in the third parameter is replicated in the result. The second parameter is unspecified, so the project setting for the threshold (1000) applies by default.

These examples show how the function works when suffixes are specified for multiple abbreviation levels:

ATL in Script

Result

Note

[[abbreviateNumber(13500000,'','K','M','B','T')]]

13.5M

The function uses the suffix given for MILLIONS as that's the most suitable level for the input number.

[[abbreviateNumber(13500000,'','K','none','B','T')]]

13,500K

The MILLIONS parameter is set to none, so the function uses the suffix for the next lowest level.

[[abbreviateNumber(13500000,'','none','none','B','T')]]

0.01B

The THOUSANDS and MILLIONS parameters are set to 'none', so the number is abbreviated at the lowest level with a suffix.

[[abbreviateNumber(13500000,'','none','none','none','none')]]

13,500,000

THOUSANDS, MILLIONS, BILLIONS, and TRILLIONS are set to 'none'. In this case, no abbreviation occurs.

The display precision for abbreviated numbers is controlled by the project settings DECIMAL PLACES FOR ABBREVIATION and STRIP TRAILING ZEROS FOR ABBREVIATION. You can override these settings using the precision function. For example:

ATL In Script

Result

Notes

[[abbreviateNumber(1250,'','K')]]

1.25K

The number is abbreviated to two decimal places because the project's DECIMAL PLACES FOR ABBREVIATION setting is 2.

[[precision(abbreviateNumber(1250,'','K'),1)]]

1.3K

The DECIMAL PLACES FOR ABBREVIATION setting is 2, but the display precision has been changed to one decimal place using precision.

© Arria Data2Text Limited