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
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-inherit
[%num-fmt-inherit: depth ? 1]
Copies a parent scope's number format and applies it to the calling scope.
Parameters
depth
← int
(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
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 ? 0]
→ bool | nothing
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 ? 0]
→ int | nothing
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 ? 0]
→ int | nothing
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 ? 0]
→ bool | nothing
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 ? 0]
→ string | nothing
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 ? 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
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 ? 0]
→ string | nothing
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 ? 0]
→ string | nothing
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 ? 0]
→ string | nothing
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).