DOCSEARCHbyAlgolia
Submit Docs

decimal.js

repository·master·Indexed 27 days ago

https://github.com/mikemcl/decimal.js

An arbitrary-precision Decimal type for JavaScript (version 10.6.0) designed to handle integers, floats, and various number bases including hex, binary, and octal. It provides a full-featured API with immutable Decimal instances, supporting standard arithmetic, comparison operations, trigonometric functions, logarithmic and exponential calculations, and configurable precision and rounding modes.

Tokens
7.1K
Snippets
6
Records
83
Agent score
88%

What's inside decimal.js

  2. Load decimal.js in the browser

    master

    For browser environments, you can use a standard script tag for the single JavaScript file or an ES module import for the .mjs version.

    <!-- Standard script -->
<script src='path/to/decimal.js'></script>

<!-- ES Module -->
<script type="module">
  import Decimal from './path/to/decimal.mjs';
  ...
</script>

  4. Configure global and custom precision

    master

    All calculations are rounded according to the precision and rounding properties. You can set global configuration using Decimal.set() or create independent constructors using Decimal.clone().

    // Set the precision and rounding of the default Decimal constructor
Decimal.set({ precision: 5, rounding: 4 })

// Create another Decimal constructor with its own configuration
Dec = Decimal.clone({ precision: 9, rounding: 1 })

x = new Decimal(5)
y = new Dec(5)

x.div(3) // '1.6667'
y.div(3) // '1.66666666'

  5. Perform arithmetic with Decimal instances

    master
    Decimal instances are immutable; methods return a new Decimal instance rather than modifying the original. Methods can be chained for complex calculations. Many methods have shorter aliases (e.g., sqrt() for squareRoot(), div() for dividedBy(), pow() for toPower(), cmp() for comparedTo(), and mod() for modulo()).

  6. Convert Decimal to a fraction

    master

    The toFraction() method returns an array containing the numerator and denominator as strings. You can optionally provide a maximum denominator argument.

    z = new Decimal(355)
pi = z.dividedBy(113) // '3.1415929204'
pi.toFraction()       // [ '7853982301', '2500000000' ]
pi.toFraction(1000)   // [ '355', '113' ]

  7. Access internal Decimal properties

    master

    A Decimal value is stored in a floating point format. The following properties are available (though they should be treated as read-only):

    • d: digits (base 10000000)
    • e: exponent (base 10)
    • s: sign (-1 or 1)
    x = new Decimal(-12345.67);
x.d // [ 12345, 6700000 ]
x.e // 4
x.s // -1

  8. Format Decimal output

    master

    Use formatting methods to control how the decimal value is represented as a string. Use toFixed() to avoid scientific (exponential) notation.

    x = new Decimal(255.5)
x.toExponential(5) // '2.55500e+2'
x.toFixed(5)       // '255.50000'
x.toPrecision(5)   // '255.50'

// Avoiding exponential notation
x = new Decimal('0.0000001')
x.toString()       // '1e-7'
x.toFixed()        // '0.0000001'

  9. Initialize a Decimal instance

    master

    The Decimal constructor accepts a number, string, or another Decimal instance.

    Important: When working with values that have more than 15 significant digits, pass them as strings to avoid precision loss inherent in JavaScript's native Number type.

  10. Configure Decimal global settings

    master

    Use Decimal.config(obj) to set global configuration for all new Decimal instances. The configuration object can include the following keys:

    • precision: Number of significant digits.
    • rounding: Rounding mode (see Rounding Modes).
    • toExpNeg: Minimum exponent for scientific notation.
    • toExpPos: Maximum exponent for scientific notation.
    • maxE: Maximum exponent.
    • minE: Minimum exponent.
    • modulo: Whether to use modulo for certain operations.
    • crypto: Whether to use a cryptographically strong random number generator for Decimal.random().

  11. Configure Decimal default settings

    master

    You can modify the global configuration of the Decimal library using Decimal.config(). This affects all subsequent calculations. The following configuration keys are available:

    • precision: The maximum number of significant digits (1 to MAX_DIGITS, default 20).
    • rounding: The rounding mode used (0 to 8, default 4 which is ROUND_HALF_UP).
    • modulo: The modulo mode used for a mod n (0 to 9, default 1).
    • toExpNeg: The exponent value at and beneath which toString returns exponential notation (default -7).
    • toExpPos: The exponent value at and above which toString returns exponential notation (default 21).
    • minE: The minimum exponent value, beneath which underflow to zero occurs (default -EXP_LIMIT).
    • maxE: The maximum exponent value, above which overflow to Infinity occurs (default EXP_LIMIT).
    • crypto: Whether to use cryptographically-secure random number generation (default false).

  12. Convert to decimal places with toDecimalPlaces() or toDP()

    master

    Return a new Decimal whose value is the value of this Decimal rounded to a maximum of dp decimal places using rounding mode rm or rounding if rm is omitted.

    Arguments:

    • dp {number}: Decimal places. Integer, 0 to MAX_DIGITS inclusive.
    • rm {number}: Rounding mode. Integer, 0 to 8 inclusive.