Number formatter

The number formatter enables you to passively apply custom formatting to numbers (int and float) when printing text.

Functions

Each scope maintains its own separate number format. To change the number format options, you need to use the [num-fmt*] class of functions.

The following functions are available:

FunctionDesctipyion
[num-fmt]Set multiple format options at once or get a map of all format options
[num-fmt-system]Get or set the current numeral system
[num-fmt-alt]Get or set the alternate formatting flag
[num-fmt-precision]Get or set the decimal precision
[num-fmt-padding]Get or set the padding size for the integral part of the number
[num-fmt-upper]Get or set the uppercase formatting flag
[num-fmt-endian]Get or set the endianness for bytewise representations (hex, binary, etc)
[num-fmt-sign]Get or set the sign style
[num-fmt-infinity]Get or set the infinity style
[num-fmt-group-sep]Get or set the group separator
[num-fmt-decimal-sep]Get or set the decimal separator

Options

The below table describes each option available in the number formatter.

NameTypeDefaultDescription
systemstringwest-arabicNumeral system to render numbers in
(See associated table)
altboolfalseEnables alternate formatting for the selected system
precisionint-1Number of decimal places to pad/truncate to; set to -1 to disable
paddingint0Minimum number of digits to pad the integral component to
upperboolfalseEnables current system's uppercase form
endianstringbigByte order for power-of-two bases (hex, binary...).
(See associated table)
signstringnegative-onlySign formatting style
(See associated table)
infinitystringkeywordInfinity formatting style
(See associated table)
group-sepstring""Digit group separator
decimal-sepstring""Decimal group separator; if not specified, defaults to "."

The system option

ValueDescriptionExample (1234)
default(Set-only) Same as west-arabic1234
west-arabicWestern Arabic numerals (default)1234
east-arabicEastern Arabic numerals١٢٣٤
persianPersian numerals۱۲۳۴
babylonianBabylonian cuneiform numerals. Truncates decimals.𒌋𒌋 𒌍𒐘
romanRoman numerals. Truncates decimals.mccxxxiv
hexHexadecimal (base 16); Floats use IEEE 754 double-precision format.4d2
octalOctal (base 8); Floats use IEEE 754 double-precision format.2322
binaryBinary (base 2); Floats use IEEE 754 double-precision format.10011010010
alphaLatin alphabetical ordinals; identical to Excel column numbersaul

The endian option

ValueDescription
default(Set-only) Same as big
bigSpecifies big-endian byte order (MSB goes first) (default)
littleSpecifies little-endian byte order (LSB goes first)

The sign option

ValueDescription
default(Set-only) Same as negative-only
negative-onlyShow a minus on negative numbers; otherwise, nothing.
explicitShow a plus on positive numbers (including zero), and a minus on negative numbers.
explicit-non-zeroShow a plus on positive numbers, nothing on zero, and a minus on negative numbers.

The infinity option

ValueDescription
default(Set-only) Same as keyword
keywordUses -infinity for negative infinity and infinity for positive infinity.
symbolUses -∞ for negative infinity and for positive infinity.

Using [num-fmt]

The [num-fmt] function is the simplest way to configure complex formats. It enables you to set multiple options at once, or get a map of all current option values.

Getting current options with [num-fmt]

To get a map of all number format options, just call [num-fmt] and omit the options parameter:

[num-fmt]

This prints a map with the following fields:

@(
    sign = negative-only; 
    infinity = keyword; 
    group-sep = ; 
    endian = big; 
    precision = -1; 
    system = west-arabic; 
    alt = false; 
    padding = 0; 
    upper = false; 
    decimal-sep = ;
)

This can be stored in a variable for later use, or modified and passed back into the function.

Setting options with [num-fmt]

To set options, pass a map to [num-fmt] with the fields you're interested in changing. This will overwrite only the specified options, leaving all others unchanged.

# Format numbers as 64-bit hex with 0x prefix
[num-fmt: @(system = hex; alt = @true; padding = 16)]
1000000000\n

# Change another option
[num-fmt-endian: little] 
1000000000\n

This produces the output:

0x000000003b9aca00
0xca9a3b0000000000