big-amount
    Preparing search index...

    Class BigAmount

    import { q, BigAmount } from "big-amount";

    let f = q("1/2")           // Same as `BigAmount.create("1/2")`
      .neg()                   // Unary `-`
      .inv()                   // Inverse (`1 / f`)
      .add(q("34.5"))          // `+`
      .sub(q(".67"))           // `-`
      .mul(q(-8n, 9n))         // `*`
      .div(q(10))              // `/`
      .abs()                   // To absolute value
      .reduce();               // To irreducible form

    console.log(f.toJSON());   // "1061/375"
    console.log(f.toFixed(6)); // "2.829333"

    let s = BigAmount.sum([
      "2200811.81",
      "5954398.62",
      "-6217732.25",
      "-9336803.50",
    ]).toFixed(2, {
      groupSeparator: ",",
      templates: ["${}", "$({})"],
    });
    console.log(s); // "$(7,399,325.32)"
    Index

    Arithmetic Operation

    abs add div inv mul neg reduce sub

    Comparison

    cmp eq ge gt le lt ne

    Conversion

    quantize round roundToInt toExponential toFixed toJSON toNumber toString tryQuantize

    Instance Creation

    clone create fromNumber sum

    Optimized Arithmetic Operation

    batchAdd fixedAdd fixedDiv fixedMul fixedSub quantDiv quantMul

    Other

    constructor den num isInteger isZero sign

    Arithmetic Operation

    • Returns the irreducible form of this with a positive denominator.

      Returns BigAmount

      This method has to be called explicitly to obtain the canonical form of a fraction because the methods in this class by design do not return the irreducible form of the result.

    Comparison

    • Returns -1, 0, and 1 if this is less than, equal to, and greater than other, respectively.

      Parameters

      Returns number

    • Returns true if this is an equivalent fraction to other.

      Parameters

      Returns boolean

    • Returns true if this is not an equivalent fraction to other.

      Parameters

      Returns boolean

    Conversion

    • Returns a fractional approximate of this that has the specified denominator. This method rounds the numerator using the specified rounding mode if it is not divisible by the new denominator.

      Parameters

      Returns BigAmount

      let f = BigAmount.create("1/3"); // 1/3 = 0.333333...
      f.quantize(100n);                // 33/100 = 0.33

      Note that the RoundingMode applies to the resulting numerator; the outcome of "toward positive / negative" is determined by the sign of numerator, which could be counterintuitive when the new denominator is negative.

    • Returns a fractional approximate of this that is rounded to the multiple of 1 / (10 ** ndigits), just like Python's built-in round(). This method rounds ties to even by default.

      Parameters

      • ndigits: number = 0

        Number of digits after the decimal separator.

      • roundingMode: RoundingMode = "HALF_EVEN"

        See RoundingMode for rounding mode options.

      Returns BigAmount

    • Returns an integral approximate of this, rounding ties to even by default.

      Parameters

      Returns bigint

    • Formats a BigAmount using decimal exponential notation just like Number#toExponential. Unlike Number#toExponential, this method always requires the first argument.

      Parameters

      • ndigits: number

        Number of digits to appear after the decimal separator.

      Returns string

    • Formats a BigAmount using decimal fixed-point notation just like Number#toFixed. In addition, this method takes format options to customize the output. See FormatOptions for options and examples.

      Parameters

      • ndigits: number = 0

        Number of digits to appear after the decimal separator.

      • OptionalformatOptions: FormatOptions

      Returns string

    • Returns this as a number.

      Returns number

    Instance Creation

    • Creates a BigAmount from various arguments. For convenience, this method is also exported as q and is callable as q(x) and q(x, y).

      Parameters

      • x: BigAmountLike

        bigint | number | string | { num: bigint | number | string; den: bigint | number | string }

      • Optionaly: BigAmountLike

        bigint | number | string | { num: bigint | number | string; den: bigint | number | string }

      Returns BigAmount

      q(123n);        // 123/1
      q(123);         // 123/1
      q("123");       // 123/1
      q("123.45");    // 12345/100
      q("123.45e-6"); // 12345/100000000

      q("123/45");    // 123/45
      q("12.3/-4.5"); // 1230/-450

      Note that non-integral number values have to be passed as string.

      q(123.45);   // ERROR!
      q(123 / 45); // ERROR!

      q(123n, 45n);    // 123/45
      q(123, 45);      // 123/45

      q(123, 45n);     // 123/45
      q(123n, "4.5");  // 1230/45

      q("1/2", "3/4"); // 4/6
      q("1/2", "3.4"); // 10/68

      This method accepts the following BigAmount-like arguments:

      • bigint - Any bigint value.
      • number - Integer only. This is because it is often imprecise and expensive to find a rational approximate of a non-integral number. Pass the number as a string (e.g. "1/3", "1.23") to create an exact value or use BigAmount.fromNumber to find an approximate.
      • string - Fraction ("1/23"), integer ("123", "0xFF"), decimal ("-1.23", ".123"), or scientific ("1.23e-4", "-12e+3"). The fractional notation q("num/den") is equivalent to q("num", "den").
      • object - Any object (including any BigAmount value) that has two BigAmount-like scalar fields named num and den. q({ num: x, den: y }) is equivalent to q(x, y), except that the fields do not accept an object.

    • Creates a BigAmount instance of the sum of list items.

      Parameters

      Returns BigAmount

      BigAmount.sum(["123/100", "-456/100", "789/100"]); // 456/100

    Optimized Arithmetic Operation

    • Divides this by other, resetting the denominator to newDen. This method is equivalent to f.div(other).quantize(newDen, roundingMode) and is typically useful to divide a dollar amount by quantity to calculate the unit price at a specific precision.

      Parameters

      Returns BigAmount

    • Multiplies this by other, resetting the denominator to newDen. This method is equivalent to f.mul(other).quantize(newDen, roundingMode) and is typically useful to multiply a quantity by unit price to calculate the dollar amount at a specific precision.

      Parameters

      Returns BigAmount

    Other

    • Creates a BigAmount from a pair of integers.

      Parameters

      • numerator: bigint
      • denominator: bigint

      Returns BigAmount

    den: bigint

    Raw denominator.

    num: bigint

    Raw numerator.

    • Returns true if this is an integer.

      Returns boolean

    • Returns true if this is zero.

      Returns boolean

    • Returns the sign of this.

      Returns bigint

      1n if positive, -1n if negative, 0n if zero.

    Settings

    Member Visibility

    On This Page

    Arithmetic Operation
    Comparison
    Conversion
    Instance Creation
    Optimized Arithmetic Operation
    Other