Skip to content

Format Numbers

Language-sensitive number and currency formatting.


Set the num style to format numbers.

    # Format using active application-wide locale.
    box('=Active: {donuts num}', data=dict(donuts=123456.789)),

    # US English
    box('=US: {donuts num}', data=dict(donuts=123456.789), locale='en-US'),

    # Germany uses comma as decimal separator and period for thousands
    box('=Germany: {donuts num}', data=dict(donuts=123456.789), locale='de-DE'),

    # Arabic in most Arabic speaking countries uses real Arabic digits
    box('=Egypt: {donuts num}', data=dict(donuts=123456.789), locale='ar-EG'),

    # India uses thousands/lakh/crore separators.
    box('=India: {donuts num}', data=dict(donuts=123456.789), locale='en-IN'),

    # Use an alternate numbering system, e.g. Chinese decimal.
    box('=China: {donuts num}', data=dict(donuts=123456.789), locale='zh-Hans-CN-u-nu-hanidec'),

    # Use Balinese if available, else fallback to Indonesian.
    box('=Indonesia: {donuts num}', data=dict(donuts=123456.789), locale=('ban', 'id')),


Integer Digits

Set id-* to control the minimum number of integer digits to use.

A value with a smaller number of integer digits than this number will be left-padded with zeros (to the specified length) when formatted.

Possible values are from id-1 to id-21. The num style is implied.

    box('={score id-1}', data=dict(score=1.23456)),
    box('={score id-2}', data=dict(score=1.23456)),
    box('={score id-3}', data=dict(score=1.23456)),


Fraction digits

Set fd-*-* to control the minimum and maximum number of fraction digits to use.

Possible values are from fd-0-0 to fd-20-20. The num style is implied.

To only specify minimum fraction digits, use fd-*. For example, fd-5 to use minimum 5 fraction digits. To only specify maximum fraction digits, use fd--*. For example, fd--5 to use maximum 5 fraction digits.

    box('={score fd-2-2}', data=dict(score=1.2)),
    box('={score fd-2}', data=dict(score=1.2)),
    box('={score fd--2}', data=dict(score=1.2)),
    box('={score fd-2-2}', data=dict(score=1.23456)),
    box('={score fd-2}', data=dict(score=1.23456)),
    box('={score fd--2}', data=dict(score=1.23456)),


Significant digits

Set sd-*-* to control the minimum and maximum number of significant digits to use.

Possible values are from sd-1-1 to sd-21-21. The num style is implied.

To only specify minimum significant digits, use sd-*. For example, sd-5 to use minimum 5 significant digits. To only specify maximum significant digits, use sd--*. For example, sd--5 to use maximum 5 significant digits.

    box('={score sd-2-4}', data=dict(score=0.001234567)),
    box('={score sd-2}', data=dict(score=0.001234567)),
    box('={score sd--2}', data=dict(score=0.00123456567)),



Set the pct style to format numbers as percentages.

    box('=Percent: {donuts pct}', data=dict(donuts=0.6789))



Set the sci style to format numbers using scientific notation.

    box('=Donuts: {donuts sci}', data=dict(donuts=123456.789))



Set the sci style to format numbers using engineering notation.

    box('=Donuts: {donuts eng}', data=dict(donuts=123456.789))



Set the num-s (short) or num-xs (extra short) style to format numbers using a compact notation.

    '## English',
    box('=Normal: {donuts num}', data=dict(donuts=1234567.89)),
    box('=Short: {donuts num-s}', data=dict(donuts=1234567.89)),
    box('=Extra Short: {donuts num-xs}', data=dict(donuts=1234567.89)),
    '## German',
    box('=Normal: {donuts num}', data=dict(donuts=1234567.89), locale='de'),
    box('=Short: {donuts num-s}', data=dict(donuts=1234567.89), locale='de'),
    box('=Extra Short: {donuts num-xs}', data=dict(donuts=1234567.89), locale='de'),



Set the cur-* style to format currencies.

Possible values are the ISO 4217 currency codes, such as cur-USD for the US dollar, cur-EUR for the euro, or cur-CNY for the Chinese RMB — see the Current currency & funds code list.

Add one of cur-l (long), cur-m (medium), cur-s (short), cur-xs (extra short) styles for additional control.

    '## Currencies',
    box('={price cur-USD}', data=dict(price=123456.789)),
    box('={price cur-EUR}', data=dict(price=123456.789)),
    box('={price cur-RMB}', data=dict(price=123456.789)),
    '## Notation',
    box('={price cur-USD cur-l}', data=dict(price=123456.789)),
    box('={price cur-USD cur-m}', data=dict(price=123456.789)),
    box('={price cur-USD cur-s}', data=dict(price=123456.789)),
    box('={price cur-USD cur-xs}', data=dict(price=123456.789)),



Set the acc style to wrap the number with parentheses instead of prefixing a minus sign.

Note that this feature is locale-sensitive, and might not make a difference in many locales.

    box('=Positive: {price cur-USD acc}', data=dict(price=123456.789)),
    box('=Negative: {price cur-USD acc}', data=dict(price=-123456.789)),

    # Makes no difference in Germany:
    box('=Negative: {price cur-EUR acc}', data=dict(price=-123456.789), locale='de'),



Set sign-* to control sign display.

  • sign-auto: sign display for negative numbers only, including negative zero.
  • sign-always: always display sign.
  • sign-except-zero: sign display for positive and negative numbers, but not zero.
  • sign-none: never display sign.
data = [-42, '-0', 0, 42]
    box('=Auto: {0 sign-auto} {1 sign-auto} {2 sign-auto} {3 sign-auto}', data=data),
    box('=Always: {0 sign-always} {1 sign-always} {2 sign-always} {3 sign-always}', data=data),
    box('=Except Zero: {0 sign-except-zero} {1 sign-except-zero} {2 sign-except-zero} {3 sign-except-zero}',
    box('=None: {0 sign-none} {1 sign-none} {2 sign-none} {3 sign-none}', data=data),



Set a unit-* style to show units.

Add one of unit-l (long), unit-s (short), unit-xs (extra short) styles for additional control.

Supported units are:

  • millimeter, centimeter, meter, kilometer, foot, yard, mile, mile-scandinavian
  • milliliter, liter, fluid-ounce, gallon
  • gram, kilogram, ounce, pound, stone
  • acre, hectare
  • year, month, week, day, hour, minute, second, millisecond
  • bit, kilobit, megabit, gigabit, terabit
  • byte, kilobyte, megabyte, gigabyte, terabyte, petabyte
  • celsius, fahrenheit
  • percent
  • degree
    '## Distance',
    box('=Long: {distance unit-mile unit-l}', data=dict(distance=12.3456)),
    box('=Short: {distance unit-mile unit-s}', data=dict(distance=12.3456)),
    box('=Extra short: {distance unit-mile unit-xs}', data=dict(distance=12.3456)),
    '## Size',
    box('=Long: {size unit-megabyte unit-l}', data=dict(size=12.3456)),
    box('=Short: {size unit-megabyte unit-s}', data=dict(size=12.3456)),
    box('=Extra short: {size unit-megabyte unit-xs}', data=dict(size=12.3456)),



Set a numbering-* style to change the numbering system.

Possible values include arab, arabext, bali, beng, deva, fullwide, gujr, guru, hanidec, khmr, knda, laoo, latn, limb, mlym, mong, mymr, orya, tamldec, telu, thai, tibt.

    box('=Arabic: {donuts numbering-arab}', data=dict(donuts=123456.789)),
    box('=Devanagari: {donuts numbering-deva}', data=dict(donuts=123456.789)),
    box('=Gurumukhi: {donuts numbering-guru}', data=dict(donuts=123456.789)),
    box('=Kannada: {donuts numbering-knda}', data=dict(donuts=123456.789)),
    box('=Thai: {donuts numbering-thai}', data=dict(donuts=123456.789)),