Format a value of any type into a string.
Syntax #
math.format(value)
math.format(value, options)
math.format(value, precision)
math.format(value, callback)
Where #
value: *
The value to be formatted
options: Object
An object with formatting options. Available options:
notation: string
Number notation. Choose from:
- ‘fixed’
Always use regular number notation.
For example ‘123.40’ and ‘14000000’
- ‘exponential’
Always use exponential notation.
For example ‘1.234e+2’ and ‘1.4e+7’
- ‘engineering’
Always use engineering notation: always have exponential notation,
and select the exponent to be a multiple of 3.
For example ‘123.4e+0’ and ‘14.0e+6’
- ‘auto’ (default)
Regular number notation for numbers having an absolute value between
lower
and upper
bounds, and uses exponential notation elsewhere.
Lower bound is included, upper bound is excluded.
For example ‘123.4’ and ‘1.4e7’.
- ‘bin’, ‘oct, or ‘hex’
Format the number using binary, octal, or hexadecimal notation.
For example ‘0b1101’ and ‘0x10fe’.
wordSize: number
The word size in bits to use for formatting in binary, octal, or
hexadecimal notation. To be used only with ‘bin’, ‘oct’, or ‘hex’
values for ‘notation’ option. When this option is defined the value
is formatted as a signed twos complement integer of the given word
size and the size suffix is appended to the output.
For example format(-1, {notation: ‘hex’, wordSize: 8}) === ‘0xffi8’.
Default value is undefined.
precision: number
A number between 0 and 16 to round the digits of the number. In case
of notations ‘exponential’, ‘engineering’, and ‘auto’, precision
defines the total number of significant digits returned.
In case of notation ‘fixed’, precision
defines the number of
significant digits after the decimal point.
precision
is undefined by default.
lowerExp: number
Exponent determining the lower boundary for formatting a value with
an exponent when notation='auto
. Default value is -3
.
upperExp: number
Exponent determining the upper boundary for formatting a value with
an exponent when notation='auto
. Default value is 5
.
fraction: string
. Available values: ‘ratio’ (default) or ‘decimal’.
For example format(fraction(1, 3))
will output ‘1/3’ when ‘ratio’ is
configured, and will output 0.(3)
when ‘decimal’ is configured.
callback: function
A custom formatting function, invoked for all numeric elements in value
,
for example all elements of a matrix, or the real and imaginary
parts of a complex number. This callback can be used to override the
built-in numeric notation with any type of formatting. Function callback
is called with value
as parameter and must return a string.
Parameters #
Parameter |
Type |
Description |
value |
* |
Value to be stringified |
options |
Object | Function | number |
Formatting options |
Returns #
Type |
Description |
string |
The formatted value |
Examples #
math.format(6.4) // returns '6.4'
math.format(1240000) // returns '1.24e6'
math.format(1/3) // returns '0.3333333333333333'
math.format(1/3, 3) // returns '0.333'
math.format(21385, 2) // returns '21000'
math.format(12e8, {notation: 'fixed'}) // returns '1200000000'
math.format(2.3, {notation: 'fixed', precision: 4}) // returns '2.3000'
math.format(52.8, {notation: 'exponential'}) // returns '5.28e+1'
math.format(12400,{notation: 'engineering'}) // returns '12.400e+3'
math.format(2000, {lowerExp: -2, upperExp: 2}) // returns '2e+3'
function formatCurrency(value) {
// return currency notation with two digits:
return '$' + value.toFixed(2)
// you could also use math.format inside the callback:
// return '$' + math.format(value, {notation: 'fixed', precision: 2})
}
math.format([2.1, 3, 0.016], formatCurrency} // returns '[$2.10, $3.00, $0.02]'
See also #
print