Docs
chromia.com

Interface

Amount

On this page

An amount consists of a value and number of decimals. It wraps a bigint value, and thus has the same limitations as a bigint in terms of size and precision.

The Amount interface also has methods to perform arithmetic operations on the amount with preserved precision.

interface Amount {
    compare: (other: SupportedNumber) => number;
    decimals: number;
    dividedBy: (other: SupportedNumber, decimals?: number | "max") => Amount;
    encodeGtv: () => RawGtv;
    eq: (other: SupportedNumber) => boolean;
    equals: (other: SupportedNumber) => boolean;
    gt: (other: SupportedNumber) => boolean;
    gte: (other: SupportedNumber) => boolean;
    lt: (other: SupportedNumber) => boolean;
    lte: (other: SupportedNumber) => boolean;
    minus: (other: SupportedNumber) => Amount;
    plus: (other: SupportedNumber) => Amount;
    times: (other: SupportedNumber, decimals?: number | "max") => Amount;
    toString: (removeTrailingZeroes?: boolean) => string;
    value: bigint;
    format(
        which: scientific,
        digits: number,
        removeTrailingZeroes?: boolean,
    ): string;
    format(
        which: fixedDecimals | mixed,
        digits: number,
        removeTrailingZeroes?: boolean,
        groupDigits?: boolean,
    ): string;
}

Properties

compare

compare: (other: SupportedNumber) => number

Can be used as compareFn with Array.sort().

Type Declaration

    • (other: SupportedNumber): number

    • Parameters

      Returns number

      0 if other is equal to this 1 if other should come before this when sorted -1 if other should come after this when sorted

decimals

decimals: number

dividedBy

dividedBy: (other: SupportedNumber, decimals?: number | "max") => Amount

Produces a new amount which is the quotient of this amount and the specified value (divisor), optionally specifying the number of decimals the end result should have.

Type Declaration

    • (other: SupportedNumber, decimals?: number | "max"): Amount

    • Parameters

      • other: SupportedNumber

        the value to divide this amount with

      • Optionaldecimals: number | "max"

        the number of decimals the end result should have, or "max" for the highest value between this.decimals and other.decimals, that is Math.max(this.decimals, other.decimals). Defaults to this.decimals

      Returns Amount

      new amount with the value "this amount" / "other amount"

encodeGtv

encodeGtv: () => RawGtv

Serializes this amount to its gtv representation to be used when submitting it to the blockchain

eq

eq: (other: SupportedNumber) => boolean

Compares this amount with another value and returns true if this amount is equal to the other value

Type Declaration

equals

equals: (other: SupportedNumber) => boolean

Compares this amount with another value and returns true if this amount is equal to the other value

Type Declaration

gt

gt: (other: SupportedNumber) => boolean

Compares this amount with another value and returns true if this amount is greater than the other value

Type Declaration

gte

gte: (other: SupportedNumber) => boolean

Compares this amount with another value and returns true if this amount is greater than or equal to the other value

Type Declaration

lt

lt: (other: SupportedNumber) => boolean

Compares this amount with another value and returns true if this amount is lesser than the other value

Type Declaration

lte

lte: (other: SupportedNumber) => boolean

Compares this amount with another value and returns true if this amount is lesser than or equal to the other value

Type Declaration

minus

minus: (other: SupportedNumber) => Amount

Produces a new amount which is the difference of this amount and the specified value

Type Declaration

plus

plus: (other: SupportedNumber) => Amount

Produces a new amount which is the sum of this amount and the specified value

Type Declaration

times

times: (other: SupportedNumber, decimals?: number | "max") => Amount

Produces a new amount which is the product of this amount and the specified value, optionally specifying the number of decimals the end result should have.

Type Declaration

    • (other: SupportedNumber, decimals?: number | "max"): Amount

    • Parameters

      • other: SupportedNumber

        the value to multiply this amount with

      • Optionaldecimals: number | "max"

        the number of decimals the end result should have, or "max" for the highest value between this.decimals and other.decimals, that is Math.max(this.decimals, other.decimals). Defaults to this.decimals

      Returns Amount

      new amount with the value "this amount" * "other amount"

toString

toString: (removeTrailingZeroes?: boolean) => string

To be used if you want the precise value, down to the last digit. It must return a string, as a Number could still be overflowed and floating point numbers aren't precise in JS.

Type Declaration

    • (removeTrailingZeroes?: boolean): string

    • Parameters

      • OptionalremoveTrailingZeroes: boolean

        if true, trailing zeroes will be removed (0.800 -> 0.8). Defaults to true.

      Returns string

value

value: bigint

Methods

format

  • format(
    which: scientific,
    digits: number,
    removeTrailingZeroes?: boolean,
): string

    Returns the amount formatted as a readable string

    Parameters

    • which: scientific

      the DecimalFormat to use

    • digits: number

      the number of digits to display

    • OptionalremoveTrailingZeroes: boolean

      if true, trailing zeroes will be removed (0.800 -> 0.8)

    Returns string

    The formatted string. WILL LOSE LOWER DIGIT PRECISION

    Example

    TypeScript
    scientific, 3-digits: 1.00e+18, 2.47e+3, 5.70e+0, 2.30e-4
fixed decimals, 3-digits: 13.750, 1987352342.435, 0.000, 12
mixed, 3-digits: 1.00e+18, 1.23e+3, 345, 12.0, 1.45e-1, 1.15e-2 !!NOT 0.01!!
  • format(
    which: fixedDecimals | mixed,
    digits: number,
    removeTrailingZeroes?: boolean,
    groupDigits?: boolean,
): string

    returns the amount formatted as a readable string

    Parameters

    • which: fixedDecimals | mixed

      the DecimalFormat to use

    • digits: number

      the number of digits to display

    • OptionalremoveTrailingZeroes: boolean

      if true, trailing zeroes will be removed (0.800 -> 0.8)

    • OptionalgroupDigits: boolean

      if true, when the format is not scientific, digits will be grouped by three (1234.5678 -> 1 234.567 8)

    Returns string

    The formatted string. WILL LOSE LOWER DIGIT PRECISION

    Example

    TypeScript
    scientific, 3-digits: 1.00e+18, 2.47e+3, 5.70e+0, 2.30e-4
fixed decimals, 3-digits: 13.750, 1987352342.435, 0.000, 12
mixed, 3-digits: 1.00e+18, 1.23e+3, 345, 12.0, 1.45e-1, 1.15e-2 !!NOT 0.01!!