Standard Library: Formatting functions
num-fmt
[%num-fmt: options?; depth?]
→ map | empty
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
options ← map (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.
depth ← int (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
| Name | Type | Default | Description |
|---|---|---|---|
system | string | west-arabic | Numeral system to render numbers in (See associated table) |
alt | bool | false | Enables alternate formatting for the selected system |
precision | int | -1 | Number of decimal places to pad/truncate to; set to -1 to disable |
padding | int | 0 | Minimum number of digits to pad the integral component to |
upper | bool | false | Enables current system's uppercase form |
endian | string | big | Byte order for power-of-two bases (hex, binary...). (See associated table) |
sign | string | negative-only | Sign formatting style (See associated table) |
infinity | string | keyword | Infinity formatting style (See associated table) |
group-sep | string | "" | Digit group separator |
decimal-sep | string | "" | 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-system
[%num-fmt-system: system?; depth?]
→ string | empty
Gets or sets the number formatter's numeral system.
Shorthand for the system option in [num-fmt].
Parameters
system ← string (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.
depth ← int (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
| Value | Description | Example (1234) |
|---|---|---|
default | (Set-only) Same as west-arabic | 1234 |
west-arabic | Western Arabic numerals (default) | 1234 |
east-arabic | Eastern Arabic numerals | ١٢٣٤ |
persian | Persian numerals | ۱۲۳۴ |
babylonian | Babylonian cuneiform numerals. Truncates decimals. | 𒌋𒌋 𒌍𒐘 |
roman | Roman numerals. Truncates decimals. | mccxxxiv |
hex | Hexadecimal (base 16); Floats use IEEE 754 double-precision format. | 4d2 |
octal | Octal (base 8); Floats use IEEE 754 double-precision format. | 2322 |
binary | Binary (base 2); Floats use IEEE 754 double-precision format. | 10011010010 |
alpha | Latin alphabetical ordinals; identical to Excel column numbers | aul |
num-fmt-alt
[%num-fmt-alt: flag?; depth?]
→ bool | empty
Gets or sets the number formatter's alternate format flag.
Shorthand for the alt option in [num-fmt].
Parameters
flag ← bool (optional)
A boolean value indicating whether alternate formatting is enabled.
If omitted, the function prints the current value.
depth ← int (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?]
→ int | empty
Gets or sets the number formatter's decimal precision.
Shorthand for the precision option in [num-fmt].
Parameters
precision ← int (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.
depth ← int (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?]
→ int | empty
Gets or sets the number formatter's digit padding size.
Shorthand for the padding option in [num-fmt].
Parameters
padding ← int (optional)
The padding size to set. If omitted, the function prints the current value.
depth ← int (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?]
→ bool | empty
Gets or sets the number formatter's uppercase formatting flag.
Shorthand for the upper option in [num-fmt].
Parameters
flag ← bool (optional)
A boolean value indicating whether uppercase formatting is enabled.
If omitted, the function prints the current value.
depth ← int (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?]
→ string | empty
Gets or sets the number formatter's sign style.
Shorthand for the sign option in [num-fmt].
Parameters
sign ← string (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.
depth ← int (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
| Value | Description |
|---|---|
default | (Set-only) Same as negative-only |
negative-only | Show a minus on negative numbers; otherwise, nothing. |
explicit | Show a plus on positive numbers (including zero), and a minus on negative numbers. |
explicit-non-zero | Show a plus on positive numbers, nothing on zero, and a minus on negative numbers. |
num-fmt-endian
[%num-fmt-endian: endianness?; depth?]
→ string | empty
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
endianness ← string (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.
depth ← int (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
| Value | Description |
|---|---|
default | (Set-only) Same as big |
big | Specifies big-endian byte order (MSB goes first) (default) |
little | Specifies little-endian byte order (LSB goes first) |
num-fmt-infinity
[%num-fmt-infinity: infinity?; depth?]
→ string | empty
Gets or sets the number formatter's infinity style.
Shorthand for the infinity option in [num-fmt].
Parameters
infinity ← string (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.
depth ← int (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
| Value | Description |
|---|---|
default | (Set-only) Same as keyword |
keyword | Uses -infinity for negative infinity and infinity for positive infinity. |
symbol | Uses -∞ for negative infinity and ∞ for positive infinity. |
num-fmt-group-sep
[%num-fmt-group-sep: group-sep?; depth?]
→ string | empty
Gets or sets the number formatter's digit group separator.
Shorthand for the group-sep option in [num-fmt].
Parameters
group-sep ← string (optional)
The group separator to use. If omitted, the function prints the current value.
depth ← int (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?]
→ string | empty
Gets or sets the number formatter's decimal separator.
Shorthand for the decimal-sep option in [num-fmt].
Parameters
decimal-sep ← string (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.
depth ← int (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).