Standard Library: Formatting functions

num-fmt


[%num-fmt: options?; depth ? 0]

map | nothing

Gets or sets the number formatting options for the calling scope.

If options is not set, prints a map with all current number format options.

Parameters

optionsmap (optional)
The options to set. Only overwrites options specified; all others are left unchanged.
If omitted, the function prints a map containing all current number format options.
See section below for available options.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

Supported keys for options

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 "."

Examples

Getting the current number format

# Print current number format
[num-fmt]
## -> 
(::
    sign = negative-only; 
    infinity = keyword; 
    group-sep = ; 
    endian = big; 
    precision = -1; 
    system = west-arabic; 
    alt = false; 
    padding = 0; 
    upper = false; 
    decimal-sep = ;
)
##

Setting the current number format

# Set format to big-endian 64-bit uppercase hex with prefix
[num-fmt: (:: system = hex; upper = @true; alt = @true; padding = 16)]

1000000000\n

# -> 0x000000003B9ACA00

num-fmt-inherit


[%num-fmt-inherit: depth ? 1]

Copies a parent scope's number format and applies it to the calling scope.

Parameters

depthint (optional)
The offset of the scope whose number format settings to inherit. Defaults to 1 (the parent scope of the caller).

num-fmt-system


[%num-fmt-system: system?; depth ? 0]

string | nothing

Gets or sets the number formatter's numeral system.

Shorthand for the system option in [num-fmt].

Parameters

systemstring (optional)
The case-insensitive name of the numeral system to use. If omitted, the function prints the current value.
See section below for available options.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

Options for system

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

num-fmt-alt


[%num-fmt-alt: flag?; depth ? 0]

bool | nothing

Gets or sets the number formatter's alternate format flag.

Shorthand for the alt option in [num-fmt].

Parameters

flagbool (optional)
A boolean value indicating whether alternate formatting is enabled. If omitted, the function prints the current value.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

num-fmt-precision


[%num-fmt-precision: precision?; depth ? 0]

int | nothing

Gets or sets the number formatter's decimal precision.

Shorthand for the precision option in [num-fmt].

Parameters

precisionint (optional)
The number of decimal places to pad or truncate numbers to. If omitted, the function prints the current value. Set to -1 to allow unbounded precision.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

num-fmt-padding


[%num-fmt-padding: padding?; depth ? 0]

int | nothing

Gets or sets the number formatter's digit padding size.

Shorthand for the padding option in [num-fmt].

Parameters

paddingint (optional)
The padding size to set. If omitted, the function prints the current value.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

num-fmt-upper


[%num-fmt-upper: flag?; depth ? 0]

bool | nothing

Gets or sets the number formatter's uppercase formatting flag.

Shorthand for the upper option in [num-fmt].

Parameters

flagbool (optional)
A boolean value indicating whether uppercase formatting is enabled. If omitted, the function prints the current value.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

num-fmt-sign


[%num-fmt-sign: sign?; depth ? 0]

string | nothing

Gets or sets the number formatter's sign style.

Shorthand for the sign option in [num-fmt].

Parameters

signstring (optional)
The case-insensitive name of the sign style to use. If omitted, the function prints the current value.
See section below for available options.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

Options for sign

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.

num-fmt-endian


[%num-fmt-endian: endianness?; depth ? 0]

string | nothing

Gets or sets the number format's endianness. This affects the byte order of power-of-two base formats such as binary and hex.

Shorthand for the endian option in [num-fmt].

Parameters

endiannessstring (optional)
The case-insensitive name of the endianness type to use. If omitted, the function prints the current value.
See section below for available options.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

Options for endianness

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

num-fmt-infinity


[%num-fmt-infinity: infinity?; depth ? 0]

string | nothing

Gets or sets the number formatter's infinity style.

Shorthand for the infinity option in [num-fmt].

Parameters

infinitystring (optional)
The case-insensitive name of the infinity style to use. If omitted, the function prints the current value.
See section below for available options.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

Options for infinity

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.

num-fmt-group-sep


[%num-fmt-group-sep: group-sep?; depth ? 0]

string | nothing

Gets or sets the number formatter's digit group separator.

Shorthand for the group-sep option in [num-fmt].

Parameters

group-sepstring (optional)
The group separator to use. If omitted, the function prints the current value.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).

num-fmt-decimal-sep


[%num-fmt-decimal-sep: decimal-sep?; depth ? 0]

string | nothing

Gets or sets the number formatter's decimal separator.

Shorthand for the decimal-sep option in [num-fmt].

Parameters

decimal-sepstring (optional)
The decimal separator to use. If the supplied value is a blank string, the formatter falls back to ".". If omitted, the function prints the current value.

depthint (optional)
The depth of the scope whose number format to access. Value must be positive. Saturates to main program scope.
Defaults to 0 (the calling scope).