simple-squiggle

A restricted subset of Squiggle
Log | Files | Refs | README

format.md (4931B)

      1 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->
      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      Limit the number of digits of the formatted value.
     53      For regular numbers, must be a number between 0 and 16.
     54      For bignumbers, the maximum depends on the configured precision,
     55      see function `config()`.
     56      In case of notations 'exponential', 'engineering', and 'auto', `precision`
     57      defines the total number of significant digits returned.
     58      In case of notation 'fixed', `precision` defines the number of
     59      significant digits after the decimal point.
     60      `precision` is undefined by default.
     61    - `lowerExp: number`
     62      Exponent determining the lower boundary for formatting a value with
     63      an exponent when `notation='auto`. Default value is `-3`.
     64    - `upperExp: number`
     65      Exponent determining the upper boundary for formatting a value with
     66      an exponent when `notation='auto`. Default value is `5`.
     67    - `fraction: string`. Available values: 'ratio' (default) or 'decimal'.
     68      For example `format(fraction(1, 3))` will output '1/3' when 'ratio' is
     69      configured, and will output `0.(3)` when 'decimal' is configured.
     70    - `truncate: number`. Specifies the maximum allowed length of the
     71      returned string. If it would have been longer, the excess characters
     72      are deleted and replaced with `'...'`.
     73 - `callback: function`
     74   A custom formatting function, invoked for all numeric elements in `value`,
     75   for example all elements of a matrix, or the real and imaginary
     76   parts of a complex number. This callback can be used to override the
     77   built-in numeric notation with any type of formatting. Function `callback`
     78   is called with `value` as parameter and must return a string.
     79 
     80 ### Parameters
     81 
     82 Parameter | Type | Description
     83 --------- | ---- | -----------
     84 `value` | * | Value to be stringified
     85 `options` | Object &#124; Function &#124; number | Formatting options
     86 
     87 ### Returns
     88 
     89 Type | Description
     90 ---- | -----------
     91 string | The formatted value
     92 
     93 
     94 ### Throws
     95 
     96 Type | Description
     97 ---- | -----------
     98 
     99 
    100 ## Examples
    101 
    102 ```js
    103 math.format(6.4)                                        // returns '6.4'
    104 math.format(1240000)                                    // returns '1.24e6'
    105 math.format(1/3)                                        // returns '0.3333333333333333'
    106 math.format(1/3, 3)                                     // returns '0.333'
    107 math.format(21385, 2)                                   // returns '21000'
    108 math.format(12e8, {notation: 'fixed'})                  // returns '1200000000'
    109 math.format(2.3,  {notation: 'fixed', precision: 4})    // returns '2.3000'
    110 math.format(52.8, {notation: 'exponential'})            // returns '5.28e+1'
    111 math.format(12400,{notation: 'engineering'})            // returns '12.400e+3'
    112 math.format(2000, {lowerExp: -2, upperExp: 2})          // returns '2e+3'
    113 
    114 function formatCurrency(value) {
    115   // return currency notation with two digits:
    116   return '$' + value.toFixed(2)
    117 
    118   // you could also use math.format inside the callback:
    119   // return '$' + math.format(value, {notation: 'fixed', precision: 2})
    120 }
    121 math.format([2.1, 3, 0.016], formatCurrency)            // returns '[$2.10, $3.00, $0.02]'
    122 ```
    123 
    124 
    125 ## See also
    126 
    127 [print](print.md)