<!-- 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.
       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'.
   - `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 &#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)