| 1 |
|
| 2 |
|
| 3 | # Function format
|
| 4 |
|
| 5 | Format a value of any type into a string.
|
| 6 |
|
| 7 |
|
| 8 | ## Syntax
|
| 9 |
|
| 10 | ```js
|
| 11 | math.format(value)
|
| 12 | math.format(value, options)
|
| 13 | math.format(value, precision)
|
| 14 | math.format(value, callback)
|
| 15 | ```
|
| 16 |
|
| 17 | ### Where
|
| 18 |
|
| 19 | - `value: *`
|
| 20 | The value to be formatted
|
| 21 | - `options: Object`
|
| 22 | An object with formatting options. Available options:
|
| 23 | - `notation: string`
|
| 24 | Number notation. Choose from:
|
| 25 | - 'fixed'
|
| 26 | Always use regular number notation.
|
| 27 | For example '123.40' and '14000000'
|
| 28 | - 'exponential'
|
| 29 | Always use exponential notation.
|
| 30 | For example '1.234e+2' and '1.4e+7'
|
| 31 | - 'engineering'
|
| 32 | Always use engineering notation: always have exponential notation,
|
| 33 | and select the exponent to be a multiple of 3.
|
| 34 | For example '123.4e+0' and '14.0e+6'
|
| 35 | - 'auto' (default)
|
| 36 | Regular number notation for numbers having an absolute value between
|
| 37 | `lower` and `upper` bounds, and uses exponential notation elsewhere.
|
| 38 | Lower bound is included, upper bound is excluded.
|
| 39 | For example '123.4' and '1.4e7'.
|
| 40 | - 'bin', 'oct, or 'hex'
|
| 41 | Format the number using binary, octal, or hexadecimal notation.
|
| 42 | For example '0b1101' and '0x10fe'.
|
| 43 | - `wordSize: number`
|
| 44 | The word size in bits to use for formatting in binary, octal, or
|
| 45 | hexadecimal notation. To be used only with 'bin', 'oct', or 'hex'
|
| 46 | values for 'notation' option. When this option is defined the value
|
| 47 | is formatted as a signed twos complement integer of the given word
|
| 48 | size and the size suffix is appended to the output.
|
| 49 | For example format(-1, {notation: 'hex', wordSize: 8}) === '0xffi8'.
|
| 50 | Default value is undefined.
|
| 51 | - `precision: number`
|
| 52 | A number between 0 and 16 to round the digits of the number. In case
|
| 53 | of notations 'exponential', 'engineering', and 'auto', `precision`
|
| 54 | defines the total number of significant digits returned.
|
| 55 | In case of notation 'fixed', `precision` defines the number of
|
| 56 | significant digits after the decimal point.
|
| 57 | `precision` is undefined by default.
|
| 58 | - `lowerExp: number`
|
| 59 | Exponent determining the lower boundary for formatting a value with
|
| 60 | an exponent when `notation='auto`. Default value is `-3`.
|
| 61 | - `upperExp: number`
|
| 62 | Exponent determining the upper boundary for formatting a value with
|
| 63 | an exponent when `notation='auto`. Default value is `5`.
|
| 64 | - `fraction: string`. Available values: 'ratio' (default) or 'decimal'.
|
| 65 | For example `format(fraction(1, 3))` will output '1/3' when 'ratio' is
|
| 66 | configured, and will output `0.(3)` when 'decimal' is configured.
|
| 67 | - `callback: function`
|
| 68 | A custom formatting function, invoked for all numeric elements in `value`,
|
| 69 | for example all elements of a matrix, or the real and imaginary
|
| 70 | parts of a complex number. This callback can be used to override the
|
| 71 | built-in numeric notation with any type of formatting. Function `callback`
|
| 72 | is called with `value` as parameter and must return a string.
|
| 73 |
|
| 74 | ### Parameters
|
| 75 |
|
| 76 | Parameter | Type | Description
|
| 77 | --------- | ---- | -----------
|
| 78 | `value` | * | Value to be stringified
|
| 79 | `options` | Object | Function | number | Formatting options
|
| 80 |
|
| 81 | ### Returns
|
| 82 |
|
| 83 | Type | Description
|
| 84 | ---- | -----------
|
| 85 | string | The formatted value
|
| 86 |
|
| 87 |
|
| 88 | ## Examples
|
| 89 |
|
| 90 | ```js
|
| 91 | math.format(6.4) // returns '6.4'
|
| 92 | math.format(1240000) // returns '1.24e6'
|
| 93 | math.format(1/3) // returns '0.3333333333333333'
|
| 94 | math.format(1/3, 3) // returns '0.333'
|
| 95 | math.format(21385, 2) // returns '21000'
|
| 96 | math.format(12e8, {notation: 'fixed'}) // returns '1200000000'
|
| 97 | math.format(2.3, {notation: 'fixed', precision: 4}) // returns '2.3000'
|
| 98 | math.format(52.8, {notation: 'exponential'}) // returns '5.28e+1'
|
| 99 | math.format(12400,{notation: 'engineering'}) // returns '12.400e+3'
|
| 100 | math.format(2000, {lowerExp: -2, upperExp: 2}) // returns '2e+3'
|
| 101 |
|
| 102 | function formatCurrency(value) {
|
| 103 | // return currency notation with two digits:
|
| 104 | return '$' + value.toFixed(2)
|
| 105 |
|
| 106 | // you could also use math.format inside the callback:
|
| 107 | // return '$' + math.format(value, {notation: 'fixed', precision: 2})
|
| 108 | }
|
| 109 | math.format([2.1, 3, 0.016], formatCurrency} // returns '[$2.10, $3.00, $0.02]'
|
| 110 | ```
|
| 111 |
|
| 112 |
|
| 113 | ## See also
|
| 114 |
|
| 115 | [print](print.md)
|