mathjs/docs/reference/functions/format.md

Math.js is an extensive math library for JavaScript and Node.js. It features a flexible expression parser with support for symbolic computation, comes with a large set of built-in functions and constants, and offers an integrated solution to work with dif

<!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

# Function format

Format a value of any type into a string.


## Syntax

```js
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`
     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.
- `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 &#124; Function &#124; number | Formatting options

### Returns

Type | Description
---- | -----------
string | The formatted value


## Examples

```js
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](print.md)