Decimal

source

Decimal type which stores its value as a BigInt and a number of decimal places. The type parameter N can be a literal number, in which case the number of decimal places is static, or it can be the type number in which case the number of decimal places is not known until runtime. Internally, the BigInt value is stored normalised to the maximum number of decimal places in order to simplify arithmetic.

Constructors

new Decimal<N extends number = number>(intValue: bigint, numDecimals: N): Decimalsource

Properties

readonly#numDecimals: Nsource

The prescribed number of decimals, if given.

readonlyintValue: bigintsource

readonlystaticmaxDecimals: 23source

readonlystaticscale: bigintsource

readonlystaticzero: Decimalsource

Methods

Static methods

staticadd(lhs: Decimal, rhs: number | Decimal<number>): Decimalsource

Adds two decimal values, returning a result that has at least the greater number of decimals of the left and right hand operands.

staticapplyBinaryOp(op: Function): Functionsource

staticcheckedDiv(lhs: Decimal, rhs: number | Decimal<number>): undefined | Decimal<number>source

Divides two decimal values, returning a result that has at least the greater number of decimals of the left and right hand operands. If the RHS is zero, returns undefined.

staticfromFloat<N extends number>(float: number, numDecimals: N): Decimalsource

Constructs a Decimal from a floating-point number, using the specified number of decimal places.

staticfromFloat(float: number, numDecimals: number): Decimalsource

Constructs a Decimal from a floating-point number, using the number of significant decimals in the input number.

staticfromInt(intValue: number): Decimalsource

Constructs a Decimal from an integer.

staticfromInt<N extends number>(intValue: number, numDecimals: N): Decimalsource

Constructs a Decimal from a fixed-point integer, using the specified number of decimal places.

staticfromString(input: LiteralDecimal): Decimalsource

Constructs a Decimal from a string literal, using the number of decimal places given in the string.

staticfromString(input: string, tracer: ParserTracer): undefined | Decimal<number>source

Constructs a Decimal from its string representation, using the number of decimal places given in the string.

staticfromString<N extends number>(input: LiteralDecimal, numDecimals: N): undefined | Decimal<N>source

Constructs a Decimal from a string literal, using the specified number of decimal places.

staticfromString<N extends number>(input: string, numDecimals: N, tracer: ParserTracer): undefined | Decimal<N>source

Constructs a Decimal from its string representation, using the specified number of decimal places.

staticfromStringOrFloat<N extends number>(input: string | number, numDecimals: N, tracer: ParserTracer): undefined | Decimal<N>source

Constructs a Decimal from either a string or a floating-point number, using the specified number of decimal places.

staticisNonZero(value: Decimal): value is Decimal<number>source

staticisZeroOrUndefined(value: Decimal): booleansource

staticmax(values: Iterable<Decimal<number>>): undefined | Decimal<number>source

Returns the maximum from a collection of decimals, using the number of decimal places of the first Decimal instance that has the maximum value. If an empty collection is given, returns undefined.

staticmin(values: Iterable<Decimal<number>>): undefined | Decimal<number>source

Returns the minimum from a collection of decimals, using the number of decimal places of the first Decimal instance that has the minimum value. If an empty collection is given, returns undefined.

staticmul(lhs: Decimal, rhs: number | Decimal<number>): Decimalsource

Multiplies two decimal values, returning a result that has at least the greater number of decimals of the left and right hand operands.

staticreduce<T>(values: Iterable<Decimal<number>>, reducer: Function, initialValue: T): Tsource

staticsub(lhs: Decimal, rhs: number | Decimal<number>): Decimalsource

Subtracts two decimal values, returning a result that has at least the greater number of decimals of the left and right hand operands.

staticsum(values: Iterable<Decimal<number>>): Decimalsource

Returns the sum of a collection of decimals.

Instance methods

compare(rhs: Decimal): numbersource

Performs a three-way comparison against the rhs value, returning -1 if this value should be ordered first, 1 if this value should be ordered last, and zero if the values are equal.

decimals(): numbersource

Returns the number of decimal places (either the fixed number, or the number of significant decimals).

dividedBy(rhs: number | Decimal<number>): undefined | Decimal<number>source

Returns the value divided by the RHS, using the greater number of decimal places, rounded towards zero. If the RHS is zero, returns undefined.

eq(rhs: number | Decimal<number>): booleansource

Whether this value is equal to another.

fix<N extends number>(numDecimals: N): Decimalsource

Alias for truncateTo.

gt(rhs: number | Decimal<number>): booleansource

Whether this value is greater than another.

gte(rhs: number | Decimal<number>): booleansource

Whether this value is greater than or equal to another.

lt(rhs: number | Decimal<number>): booleansource

Whether this value is less than another.

lte(rhs: number | Decimal<number>): booleansource

Whether this value is less than or equal to another.

minus(rhs: number | Decimal<number>): Decimalsource

Returns the value minus the RHS, using the greater number of decimal places.

ne(rhs: number | Decimal<number>): booleansource

Whether this value is not equal to another.

plus(rhs: number | Decimal<number>): Decimalsource

Returns the value plus the RHS, using the greater number of decimal places.

roundDownTo<N extends number>(decimalPlaces: N): Decimalsource

Returns the value rounded down to the requested number of decimal places.

roundTo<N extends number>(decimalPlaces: N, tieBreakMethod: Round = Round.HalfAwayFromZero): Decimalsource

Returns the value rounded to the requested number of places.

roundUpTo<N extends number>(decimalPlaces: N): Decimalsource

Returns the value rounded up to the requested number of decimal places.

significantDecimals(): numbersource

Calculates the number of significant decimals in the value.

times(rhs: number | Decimal<number>): Decimalsource

Returns the value multiplied by the RHS, using as many decimal places as required to represent the result, excepting when that is more than the global maximum number of decimals, in which case the result is rounded towards zero.

toFixedPoint(decimals: number): numbersource

Returns the decimal fixed-point value as a number. For example, if the decimal value is 12.3450, the value returned is 123450.

toFloat(): numbersource

Returns the value as a floating-point number.

toIntMaybe(): string | numbersource

Returns the integer value of the Decimal as a number. Returns an error if the decimal has decimal places (numDecimals !== 0) or the underlying intValue is too big to represent safely as a Number.

toJSON(): stringsource

Returns the JSON representation of this decimal value.

toLocaleString(locales: LocalesArgument, options: DecimalLocaleStringOptions): stringsource

Returns a localised string representation of this decimal value.

toParts(): [isNegative: boolean, integer: bigint, fractional: bigint]source

Returns the sign, integer, and fractional parts of this decimal value.

toString(): stringsource

Returns a string representation of this decimal value.

truncateTo<N extends number>(decimalPlaces: N): Decimalsource

Returns the value truncated (rounded towards zero) to the requested number of decimal places.