Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Decimal

This class provides the additional semantics necessary for decimal values.

Unlike IEEE-754 floating point representation, Decimal values can represent numeric values without loss of precision. Each number is stored as a pair of integers, a "coefficient" and an "exponent", which can be combined to calculate the original value using the following formula:

value = coefficient * (10 ^ exponent)

Here are some examples:

 coefficient     exponent        value
        0           0                0
       37          -5                0.00037
      314          -2                3.14
      -76           0              -76
       11           1              110
        5           6        5,000,000

Presently, the supported range of an exponent is limited to +/- 15 digits.

Hierarchy

  • Decimal

Index

Constructors

Properties

Methods

Constructors

constructor

  • new Decimal(decimalText: string): Decimal
  • new Decimal(coefficient: number, exponent: number): Decimal
  • new Decimal(coefficient: bigint, exponent: number, isNegative?: boolean): Decimal

  • Creates a new Decimal value by parsing the provided text.

    Parameters

    • decimalText: string

      An Ion-encoded decimal value.

    Returns Decimal

  • Creates a new Decimal value using the provided coefficient and exponent values.

    Parameters

    • coefficient: number

      See the class-level Decimal documentation for details.

    • exponent: number

      See the class-level Decimal documentation for details.

    Returns Decimal

  • Creates a new Decimal value using the provided coefficient and exponent values. Because the BigInt data type cannot represent -0, a third parameter called isNegative may be supplied to explicitly set the sign of the Decimal following construction. If this flag is not specified, the provided coefficient's sign will be used. If isNegative is specified but is not in agreement with the coefficient's sign, the value of isNegative takes precedence.

    Parameters

    • coefficient: bigint

      See the class-level Decimal documentation for details.

    • exponent: number

      See the class-level Decimal documentation for details.

    • Optional isNegative: boolean

      Must be set to 'true' when constructing -0. May be omitted otherwise.

    Returns Decimal

Properties

Static Readonly ONE

ONE: Decimal = ...

Static Readonly ZERO

ZERO: Decimal = ...

Methods

compareTo

  • Compares this Decimal with another and returns -1, 0, or 1 if this Decimal is less than, equal to, or greater than the other Decimal.

    Note that a return value of 0 doesn't guarantee that equals() would return true, as compareTo() doesn't require the values to have the same precision to be considered equal, whereas equals() does. Additionally, compareTo() treats 0. and -0. as equal, but equals() does not.

    Parameters

    Returns number

equals

  • Compares this Decimal with another and returns true if they are equivalent in value and precision; otherwise returns false. Note that this differs from compareTo(), which doesn't require precision to match when returning 0.

    Parameters

    Returns boolean

getCoefficient

  • getCoefficient(): bigint

  • Returns a BigInt representing the coefficient of this Decimal value.

    Note that the BigInt data type is unable to represent -0 natively. If you wish to check for a -0 coefficient, test whether the coefficient is zero and then call isNegative.

    Returns bigint

getExponent

  • getExponent(): number

  • Returns a number representing the exponent of this Decimal value.

    Returns number

intValue

  • intValue(): number

  • Returns a number representing the integer portion of this Decimal. Any fractional portion of this Decimal is truncated.

    Returns number

isNegative

  • isNegative(): boolean

  • Returns true if this Decimal is negative; otherwise false.

    Returns boolean

numberValue

  • numberValue(): number

  • Returns a number representing the value of this Decimal. Note that some Decimal (base-10) values cannot be precisely expressed in JavaScript's base-2 number type.

    Returns number

toJSON

  • toJSON(): number

  • Converts this Decimal value to a JSON number when being serialized via JSON.stringify().

    Returns number

toString

  • toString(): string

  • Returns a string representation of this Decimal, using exponential notation when appropriate.

    Returns string

Static parse

  • parse(str: string): null | Decimal

  • Given a string containing the Ion text representation of a decimal value, returns a new Decimal object corresponding to the value. If a string such as '5' is provided, a 'd0' suffix is assumed.

    Parameters

    • str: string

    Returns null | Decimal