Skip to content
@ac-kit

DecimalNum

Defined in: packages/math-numbers/src/num/decimal-num.ts:73

An arbitrary-precision decimal floating-point number.

The contract shell over Decimal. Every operation delegates to the free functions in decimal.ts, which take the DecimalContext as an argument — the same shape as the soft-float kernel, and for the same reason: the result depends on a descriptor, so the descriptor belongs in the call rather than on every value.

Addition, subtraction and multiplication are exact and use no precision bound. Division and square root cannot terminate in general, so they round to Decimal128’s 34 significant digits unless a context is supplied.

Decimal.from("0.1").add(Decimal.from("0.2")).format(); // "0.3", exact
Decimal.from(2).divTo(Decimal.from(3), 10).format(); // "0.6666666667"

Extends

Section titled “Extends”
  • OrderedBase<DecimalNum>

Implements

Section titled “Implements”

Properties

Section titled “Properties”

precisionKind

Section titled “precisionKind”

readonly precisionKind: "arbitrary"

Defined in: packages/math-numbers/src/num/decimal-num.ts:80

Implementation of

Section titled “Implementation of”

IArbitraryPrecision.precisionKind

radix

Section titled “radix”

readonly radix: 10

Defined in: packages/math-numbers/src/num/decimal-num.ts:81

Implementation of

Section titled “Implementation of”

IDecimalEncoded.radix

FORMAT_INFO

Section titled “FORMAT_INFO”

readonly static FORMAT_INFO: object

Defined in: packages/math-numbers/src/num/decimal-num.ts:99

The decimal format is arbitrary-precision, so it has no minimum or maximum exponent. The radix is 10, and the format is not signed or saturated.

maxExponent

Section titled “maxExponent”

readonly maxExponent: number = Infinity

minExponent

Section titled “minExponent”

readonly minExponent: number = -Infinity

radix

Section titled “radix”

readonly radix: 10 = 10

ONE

Section titled “ONE”

readonly static ONE: DecimalNum

Defined in: packages/math-numbers/src/num/decimal-num.ts:84

STRUCTURE

Section titled “STRUCTURE”

readonly static STRUCTURE: AlgebraicStructure = APPROXIMATE_ORDERED_FIELD

Defined in: packages/math-numbers/src/num/decimal-num.ts:93

Decimal floating point rounds on division and square root, so like binary floating point it is not a field. Addition and multiplication are exact, but a structure describes the whole type, not a subset of its operations.

TAG

Section titled “TAG”

readonly static TAG: typeof TAG

Defined in: packages/math-numbers/src/num/decimal-num.ts:78

Unique type tag used by the factory and promotion tables.

TEN

Section titled “TEN”

readonly static TEN: DecimalNum

Defined in: packages/math-numbers/src/num/decimal-num.ts:86

TWO

Section titled “TWO”

readonly static TWO: DecimalNum

Defined in: packages/math-numbers/src/num/decimal-num.ts:85

ZERO

Section titled “ZERO”

readonly static ZERO: DecimalNum

Defined in: packages/math-numbers/src/num/decimal-num.ts:83

Accessors

Section titled “Accessors”

decimalPrecision

Section titled “decimalPrecision”

Get Signature

Section titled “Get Signature”

get decimalPrecision(): number

Defined in: packages/math-numbers/src/num/decimal-num.ts:198

Significant decimal digits, after stripping trailing zeros.

Returns
Section titled “Returns”

number

Total number of significant decimal digits needed to exactly represent this value.

Returns Number.POSITIVE_INFINITY for values with non-terminating decimal expansions (e.g. Fraction(1, 3), √2).

Example

Section titled “Example”
  Integer.from(12345n).decimalPrecision; // → 5
  Decimal.from("3.14").decimalPrecision; // → 3
  Fraction.from(1n, 3n).decimalPrecision; // → Infinity
  ```;


#### Implementation of


[`INum`](../interfaces/INum.md).[`decimalPrecision`](../interfaces/INum.md#decimalprecision)


***


### fractionalPrecision


#### Get Signature


> **get** **fractionalPrecision**(): `number`


Defined in: packages/math-numbers/src/num/decimal-num.ts:208


Decimal digits in the fractional part of `|this|`.


##### Returns


`number`


Number of decimal digits in the fractional part of `|value|`. `0` for exact
integers. Returns `Number.POSITIVE_INFINITY` for non-terminating decimal
expansions.


#### Example


```ts
  Integer.from(42n).fractionalPrecision; // → 0
  Decimal.from("3.14").fractionalPrecision; // → 2
  Fraction.from(1n, 3n).fractionalPrecision; // → Infinity
  ```;


#### Implementation of


[`INum`](../interfaces/INum.md).[`fractionalPrecision`](../interfaces/INum.md#fractionalprecision)


***


### integralPrecision


#### Get Signature


> **get** **integralPrecision**(): `number`


Defined in: packages/math-numbers/src/num/decimal-num.ts:203


Decimal digits in the integer part of `|this|`, at least one.


##### Returns


`number`


Number of decimal digits in the integer (integral) part of `|value|`.
Always at least `1` (the digit `0` for values with `|value| < 1`).


#### Example


```ts
  Integer.from(123n).integralPrecision; // → 3
  Decimal.from("0.5").integralPrecision; // → 1  (the leading '0')
  Decimal.from("3.14").integralPrecision; // → 1
  ```;


#### Implementation of


[`INum`](../interfaces/INum.md).[`integralPrecision`](../interfaces/INum.md#integralprecision)


## Methods


### \[toPrimitive\]()


> **\[toPrimitive\]**(`hint`): `string` \| `number` \| `bigint`


Defined in: packages/math-numbers/src/num/decimal-num.ts:191


Coerces this value to a JS primitive: - `'number'` → same as `valueOf()` -
`'string'` → same as `toString()` - `'default'` → same as `valueOf()`


#### Parameters


##### hint


`"string"` \| `"number"` \| `"default"`


#### Returns


`string` \| `number` \| `bigint`


#### Implementation of


[`INum`](../interfaces/INum.md).[`[toPrimitive]`](../interfaces/INum.md#toprimitive)


***


### abs()


> **abs**(): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:311


`|x|`.


#### Returns


`DecimalNum`


***


### add()


> **add**(`other`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:229


`this + other`, exact.


#### Parameters


##### other


`DecimalNum`


#### Returns


`DecimalNum`


***


### clamp()


> **clamp**(`lower`, `upper`): `DecimalNum`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:69


Restricts the value to `[lower, upper]`.


#### Parameters


##### lower


`DecimalNum`


##### upper


`DecimalNum`


#### Returns


`DecimalNum`


#### Inherited from


`OrderedBase.clamp`


***


### cmp()


> **cmp**(`other`): `Sign`


Defined in: packages/math-numbers/src/num/decimal-num.ts:302


Three-way comparison.


#### Parameters


##### other


`DecimalNum`


#### Returns


`Sign`


#### Overrides


`OrderedBase.cmp`


***


### digitAt()


> **digitAt**(`position`): `number`


Defined in: packages/math-numbers/src/num/decimal-num.ts:353


The decimal digit at `position`: `0` is the ones digit, positive positions
are higher integer digits, negative positions are fractional digits.


#### Parameters


##### position


`number`


#### Returns


`number`


***


### div()


> **div**(`other`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:268


`this / other`, to 34 significant digits. Use [divTo](#divto) for another
precision.


#### Parameters


##### other


`DecimalNum`


#### Returns


`DecimalNum`


#### Throws


When `other` is zero.


***


### divTo()


> **divTo**(`other`, `precision`, `roundingMode?`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:277


`this / other`, to `precision` significant digits.


#### Parameters


##### other


`DecimalNum`


##### precision


`number`


##### roundingMode?


[`RoundingMode`](../type-aliases/RoundingMode.md) = `DEFAULT_ROUNDING_MODE`


#### Returns


`DecimalNum`


#### Throws


When `other` is zero.


***


### eq()


> **eq**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:45


#### Parameters


##### other


`DecimalNum`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.eq`


***


### format()


> **format**(`locales?`, `options?`): `string`


Defined in: packages/math-numbers/src/num/decimal-num.ts:161


This value rendered for a human, by `Intl.NumberFormat`.


The parameters are `new Intl.NumberFormat(locales, options)`'s own,
unchanged — including the default, which is the ambient locale. Ask for
`"en-US"` with `useGrouping: false` when the output has to be
machine-readable.


#### Parameters


##### locales?


`LocalesArgument`


##### options?


`NumberFormatOptions`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`format`](../interfaces/INum.md#format)


***


### gt()


> **gt**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:57


#### Parameters


##### other


`DecimalNum`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.gt`


***


### gte()


> **gte**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:73


#### Parameters


##### other


`DecimalNum`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.gte`


***


### identity()


> **identity**(): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:224


The multiplicative identity `1`.


#### Returns


`DecimalNum`


***


### inv()


> **inv**(): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:258


`1 / this`, to 34 significant digits. Use `DECIMAL_ONE.divTo(this)` for
another precision.


#### Returns


`DecimalNum`


#### Throws


When called on zero.


***


### lt()


> **lt**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:49


#### Parameters


##### other


`DecimalNum`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.lt`


***


### lte()


> **lte**(`other`): `boolean`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:53


#### Parameters


##### other


`DecimalNum`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.lte`


***


### max()


> **max**(`other`): `DecimalNum`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:65


The larger of the two operands under the total order.


#### Parameters


##### other


`DecimalNum`


#### Returns


`DecimalNum`


#### Inherited from


`OrderedBase.max`


***


### min()


> **min**(`other`): `DecimalNum`


Defined in: packages/math-algebra/src/\_ordered-defaults.ts:61


The smaller of the two operands under the total order.


#### Parameters


##### other


`DecimalNum`


#### Returns


`DecimalNum`


#### Inherited from


`OrderedBase.min`


***


### mul()


> **mul**(`other`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:217


`this × other`, exact.


#### Parameters


##### other


`DecimalNum`


#### Returns


`DecimalNum`


***


### neg()


> **neg**(): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:241


`−this`.


#### Returns


`DecimalNum`


***


### roundTo()


> **roundTo**(`precision`, `roundingMode?`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:288


Rounds to `precision` significant digits.


#### Parameters


##### precision


`number`


##### roundingMode?


[`RoundingMode`](../type-aliases/RoundingMode.md) = `DEFAULT_ROUNDING_MODE`


#### Returns


`DecimalNum`


***


### sign()


> **sign**(): `Sign`


Defined in: packages/math-numbers/src/num/decimal-num.ts:318


`-1` for negative, `0` for zero, `1` for positive.


#### Returns


`Sign`


***


### sqrt()


> **sqrt**(): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:327


Principal square root, to 34 significant digits.


#### Returns


`DecimalNum`


#### Throws


When this value is negative.


***


### sqrtTo()


> **sqrtTo**(`precision`, `roundingMode?`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:336


Principal square root, to `precision` significant digits.


#### Parameters


##### precision


`number`


##### roundingMode?


[`RoundingMode`](../type-aliases/RoundingMode.md) = `DEFAULT_ROUNDING_MODE`


#### Returns


`DecimalNum`


#### Throws


When this value is negative.


***


### sub()


> **sub**(`other`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:246


`this − other`, exact.


#### Parameters


##### other


`DecimalNum`


#### Returns


`DecimalNum`


***


### toDecimal()


> **toDecimal**(): [`Decimal`](../type-aliases/Decimal.md)


Defined in: packages/math-numbers/src/num/decimal-num.ts:145


The underlying value, for callers working at the arithmetic layer.


#### Returns


[`Decimal`](../type-aliases/Decimal.md)


***


### toExponential()


> **toExponential**(`fractionDigits?`): `string`


Defined in: packages/math-numbers/src/num/decimal-num.ts:178


Exponential notation, with as many places as asked for.


#### Parameters


##### fractionDigits?


`number`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`toExponential`](../interfaces/INum.md#toexponential)


***


### toFixed()


> **toFixed**(`fractionDigits?`): `string`


Defined in: packages/math-numbers/src/num/decimal-num.ts:173


Fixed-point notation with `fractionDigits` places, padded with zeros.


#### Parameters


##### fractionDigits?


`number` = `0`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`toFixed`](../interfaces/INum.md#tofixed)


***


### toIntegralFractional()


> **toIntegralFractional**(): [`IntegralFractional`](../type-aliases/IntegralFractional.md)


Defined in: packages/math-numbers/src/num/decimal-num.ts:358


Splits into the integral part and the fractional digits.


#### Returns


[`IntegralFractional`](../type-aliases/IntegralFractional.md)


***


### toPrecision()


> **toPrecision**(`precision`): `string`


Defined in: packages/math-numbers/src/num/decimal-num.ts:183


`precision` significant digits, in whichever notation reads better.


#### Parameters


##### precision


`number`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`toPrecision`](../interfaces/INum.md#toprecision)


***


### toString()


> **toString**(`radix?`): `string`


Defined in: packages/math-numbers/src/num/decimal-num.ts:157


The exact numeral in base ten, or `radix` truncated at the same intrinsic
digit limit `Number.prototype.toString` applies.


#### Parameters


##### radix?


`number`


#### Returns


`string`


#### Implementation of


[`INum`](../interfaces/INum.md).[`toString`](../interfaces/INum.md#tostring)


***


### valueOf()


> **valueOf**(): `number`


Defined in: packages/math-numbers/src/num/decimal-num.ts:188


The nearest binary64 approximation.


#### Returns


`number`


#### Implementation of


[`INum`](../interfaces/INum.md).[`valueOf`](../interfaces/INum.md#valueof)


***


### zero()


> **zero**(): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:236


The additive identity `0`.


#### Returns


`DecimalNum`


***


### from()


> `static` **from**(`value`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:118


Creates a `Decimal` from a `bigint`, `number` or decimal string.


#### Parameters


##### value


`string` \| `number` \| `bigint`


#### Returns


`DecimalNum`


#### Throws


When given NaN or an infinity.


#### Throws


When a string is not a valid decimal number.


***


### fromDecimal()


> `static` **fromDecimal**(`value`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:140


Wraps an already-canonical [Decimal](../type-aliases/Decimal.md).


#### Parameters


##### value


[`Decimal`](../type-aliases/Decimal.md)


#### Returns


`DecimalNum`


***


### parse()


> `static` **parse**(`text`): `DecimalNum`


Defined in: packages/math-numbers/src/num/decimal-num.ts:135


Parses a decimal string such as `"3.14"`, `"-0.001"` or `"1.23e-5"`.


#### Parameters


##### text


`string`


#### Returns


`DecimalNum`


#### Throws


When the string is not a valid decimal number.