Function format
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 formattedoptions: 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
Limit the number of digits of the formatted value.
For regular numbers, must be a number between 0 and 16.
For bignumbers, the maximum depends on the configured precision,
see function config().
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.truncate: number. Specifies the maximum allowed length of the
returned string. If it would have been longer, the excess characters
are deleted and replaced with '...'.
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 |
Throws
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
