Skip to content
@ac-kit

Integer

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

An arbitrary-precision integer, wrapping the native bigint primitive.

Full integer arithmetic, Euclidean division, bitwise operations, GCD/LCM and primality testing. Its algebraic structure is stated as evidence: Integer.ring and Integer.euclideanDomain.

const a = Integer.from(12n);
const b = Integer.from(8n);
a.add(b).format(); // "20"
a.gcd(b).format(); // "4"
a.inv().format(); // "1/12"  (returns a Fraction)
Integer.from(7n).isPrime(); // true

Extends

Section titled “Extends”
  • OrderedBase<Integer>

Implements

Section titled “Implements”

Properties

Section titled “Properties”

precisionKind

Section titled “precisionKind”

readonly precisionKind: "arbitrary"

Defined in: packages/math-numbers/src/num/integer-num.ts:87

Implementation of

Section titled “Implementation of”

IArbitraryPrecision.precisionKind

radix

Section titled “radix”

readonly radix: 10

Defined in: packages/math-numbers/src/num/integer-num.ts:88

Implementation of

Section titled “Implementation of”

IDecimalEncoded.radix

euclideanDomain

Section titled “euclideanDomain”

readonly static euclideanDomain: EuclideanDomain<Integer>

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

Evidence that Integer forms a Euclidean domain.

Pass to generic algorithms such as gcd() or lcm() that accept any Euclidean domain. Because every Euclidean domain is also a ring, this object also satisfies Ring<Integer> — see ring.

FORMAT_INFO

Section titled “FORMAT_INFO”

readonly static FORMAT_INFO: ArbitraryPrecisionInfo

Defined in: packages/math-numbers/src/num/integer-num.ts:119

Format descriptor for arbitrary-precision decimal integers. Radix 10; exponent range is [0, +∞) (integers have no fractional part).

ONE

Section titled “ONE”

readonly static ONE: Integer

Defined in: packages/math-numbers/src/num/integer-num.ts:103

Multiplicative identity 1.

ring

Section titled “ring”

readonly static ring: Ring<Integer> = Integer.euclideanDomain

Defined in: packages/math-numbers/src/num/integer-num.ts:156

Evidence that Integer forms a ring.

Identical to euclideanDomain — Integer satisfies all ring laws. Provided as a convenience alias when only ring operations are needed by the receiving algorithm.

STRUCTURE

Section titled “STRUCTURE”

readonly static STRUCTURE: AlgebraicStructure = INTEGRAL_DOMAIN

Defined in: packages/math-numbers/src/num/integer-num.ts:113

ℤ is an integral domain, not a field — only ±1 are invertible.

TAG

Section titled “TAG”

readonly static TAG: typeof TAG

Defined in: packages/math-numbers/src/num/integer-num.ts:110

Unique type tag used by NumFactory and NumPromote.

TEN

Section titled “TEN”

readonly static TEN: Integer

Defined in: packages/math-numbers/src/num/integer-num.ts:107

The integer 10.

TWO

Section titled “TWO”

readonly static TWO: Integer

Defined in: packages/math-numbers/src/num/integer-num.ts:105

The integer 2.

ZERO

Section titled “ZERO”

readonly static ZERO: Integer

Defined in: packages/math-numbers/src/num/integer-num.ts:101

Additive identity 0.

Accessors

Section titled “Accessors”

decimalPrecision

Section titled “decimalPrecision”

Get Signature

Section titled “Get Signature”

get decimalPrecision(): number

Defined in: packages/math-numbers/src/num/integer-num.ts:253

Number of significant decimal digits in |this|. Minimum 1 (for zero).

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/integer-num.ts:266


Integers have no fractional digits — always `0`.


##### 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/integer-num.ts:261


Number of decimal digits in the integer part of `|this|`. Equal to
`decimalPrecision` for all integers (no fractional part).


##### 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/integer-num.ts:241


Coerces to a JS primitive. Returns `bigint` for numeric hints, string for
string hint.


#### Parameters


##### hint


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


#### Returns


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


#### Implementation of


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


***


### abs()


> **abs**(): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:430


Absolute value `|this|`.


Reference: https://en.wikipedia.org/wiki/Absolute_value


#### Returns


`Integer`


***


### add()


> **add**(`other`, `_mode?`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:301


Returns `this + other`.


`mode` is accepted for interface compatibility with fixed-width integer
types but is ignored — `Integer` is arbitrary-precision and never
overflows.


#### Parameters


##### other


`Integer`


##### \_mode?


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


#### Returns


`Integer`


***


### bitLength()


> **bitLength**(): `number`


Defined in: packages/math-numbers/src/num/integer-num.ts:413


Number of bits required to represent the magnitude, excluding the sign.


#### Returns


`number`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`bitLength`](../interfaces/IBitwise.md#bitlength)


***


### bitwiseAnd()


> **bitwiseAnd**(`other`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:374


Returns `this & other` (bitwise AND).


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`bitwiseAnd`](../interfaces/IBitwise.md#bitwiseand)


***


### bitwiseNot()


> **bitwiseNot**(): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:389


Returns `~this` (bitwise NOT). In two's complement: `~n = −n − 1`.


#### Returns


`Integer`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`bitwiseNot`](../interfaces/IBitwise.md#bitwisenot)


***


### bitwiseOr()


> **bitwiseOr**(`other`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:379


Returns `this | other` (bitwise OR).


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`bitwiseOr`](../interfaces/IBitwise.md#bitwiseor)


***


### bitwiseXor()


> **bitwiseXor**(`other`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:384


Returns `this ^ other` (bitwise XOR).


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`bitwiseXor`](../interfaces/IBitwise.md#bitwisexor)


***


### clamp()


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


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


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


#### Parameters


##### lower


`Integer`


##### upper


`Integer`


#### Returns


`Integer`


#### Inherited from


`OrderedBase.clamp`


***


### cmp()


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


Defined in: packages/math-numbers/src/num/integer-num.ts:340


Three-way comparison.


#### Parameters


##### other


`Integer`


#### Returns


`Sign`


`-1` if `this < other`, `0` if equal, `+1` if `this > other`.


#### Overrides


`OrderedBase.cmp`


***


### digitAt()


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


Defined in: packages/math-numbers/src/num/integer-num.ts:541


Returns the decimal digit at the given `position`. Position `0` is the ones
digit, `1` is tens, `2` is hundreds, etc. Negative positions (fractional
digits) always return `0` for integers.


#### Parameters


##### position


`number`


#### Returns


`number`


#### Example


```ts
  Integer.from(1234n).digitAt(0); // → 4
  Integer.from(1234n).digitAt(3); // → 1
  Integer.from(1234n).digitAt(4); // → 0
  Integer.from(1234n).digitAt(-1); // → 0
  ```;


***


### div()


> **div**(`other`): [`Fraction`](Fraction.md)


Defined in: packages/math-numbers/src/num/integer-num.ts:477


Returns `this / other` as an exact [Fraction](Fraction.md) in ℚ. For the truncating
integer quotient, use [intdiv](#intdiv).


#### Parameters


##### other


`Integer`


#### Returns


[`Fraction`](Fraction.md)


#### Throws


When `other` is zero.


***


### divmod()


> **divmod**(`other`): `QuotientRemainder`\<`Integer`, `Integer`\>


Defined in: packages/math-numbers/src/num/integer-num.ts:553


Returns the floored quotient and non-negative remainder of `this ÷ other`
as a QuotientRemainder pair.


Invariant: `other × q + r = this` and `0 ≤ r < |other|`.


#### Parameters


##### other


`Integer`


#### Returns


`QuotientRemainder`\<`Integer`, `Integer`\>


#### Throws


When `other` is zero.


***


### eq()


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


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


#### Parameters


##### other


`Integer`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.eq`


***


### format()


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


Defined in: packages/math-numbers/src/num/integer-num.ts:207


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)


***


### gcd()


> **gcd**(`other`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:504


Returns `gcd(this, other)` — the largest integer that divides both. Always
non-negative. `gcd(0, 0) = 0`.


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


***


### gt()


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


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


#### Parameters


##### other


`Integer`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.gt`


***


### gte()


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


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


#### Parameters


##### other


`Integer`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.gte`


***


### intdiv()


> **intdiv**(`other`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:355


Floored integer quotient `⌊this / other⌋`. For positive arguments this
equals truncated division. For negative arguments, floors toward −∞ so that
`mod` is always non-negative.


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


#### Throws


When `other` is zero.


***


### inv()


> **inv**(): [`Fraction`](Fraction.md)


Defined in: packages/math-numbers/src/num/integer-num.ts:466


Returns `1 / this` as an exact [Fraction](Fraction.md) in ℚ.


#### Returns


[`Fraction`](Fraction.md)


#### Throws


When called on zero.


***


### isPrime()


> **isPrime**(): `boolean`


Defined in: packages/math-numbers/src/num/integer-num.ts:520


Returns `true` if this integer is a prime number (positive, greater than 1,
divisible only by 1 and itself). Uses a deterministic Miller–Rabin test.


#### Returns


`boolean`


***


### lcm()


> **lcm**(`other`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:512


Returns `lcm(this, other)` — the smallest positive integer divisible by
both. Returns `0` when either operand is zero.


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


***


### lt()


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


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


#### Parameters


##### other


`Integer`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.lt`


***


### lte()


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


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


#### Parameters


##### other


`Integer`


#### Returns


`boolean`


#### Inherited from


`OrderedBase.lte`


***


### max()


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


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


The larger of the two operands under the total order.


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


#### Inherited from


`OrderedBase.max`


***


### min()


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


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


The smaller of the two operands under the total order.


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


#### Inherited from


`OrderedBase.min`


***


### mod()


> **mod**(`other`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:365


Non-negative Euclidean remainder: `this − other × intdiv(this, other)`.
Satisfies `0 ≤ mod(a, b) < |b|` for all `a` and nonzero `b`.


#### Parameters


##### other


`Integer`


#### Returns


`Integer`


#### Throws


When `other` is zero.


***


### mul()


> **mul**(`other`, `_mode?`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:281


Returns `this × other`.


`mode` is accepted for interface compatibility with fixed-width integer
types but is ignored — `Integer` is arbitrary-precision and never
overflows.


#### Parameters


##### other


`Integer`


##### \_mode?


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


#### Returns


`Integer`


***


### neg()


> **neg**(`_mode?`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:317


Returns `−this`.


`mode` is accepted for interface compatibility with fixed-width integer
types but is ignored — `Integer` is arbitrary-precision and never
overflows.


#### Parameters


##### \_mode?


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


#### Returns


`Integer`


***


### one()


> **one**(): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:286


Returns the multiplicative identity `1`.


#### Returns


`Integer`


***


### popCount()


> **popCount**(): `number`


Defined in: packages/math-numbers/src/num/integer-num.ts:417


Count of set bits in the magnitude.


#### Returns


`number`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`popCount`](../interfaces/IBitwise.md#popcount)


***


### shiftLeft()


> **shiftLeft**(`n`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:394


Returns `this << n`. Equivalent to multiplying by `2ⁿ`.


#### Parameters


##### n


`number`


#### Returns


`Integer`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`shiftLeft`](../interfaces/IBitwise.md#shiftleft)


***


### shiftRight()


> **shiftRight**(`n`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:400


Returns `this >> n` (arithmetic right shift — sign bit preserved).


#### Parameters


##### n


`number`


#### Returns


`Integer`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`shiftRight`](../interfaces/IBitwise.md#shiftright)


***


### sign()


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


Defined in: packages/math-numbers/src/num/integer-num.ts:440


Sign of this integer.


#### Returns


`Sign`


`-1`, `0`, or `+1`. Reference:
  https://en.wikipedia.org/wiki/Sign_(mathematics)


***


### sqrt()


> **sqrt**(): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:453


Integer floor square root `⌊√this⌋`.


#### Returns


`Integer`


#### Throws


When `this < 0` (square root of a negative integer is
  not a real number — use a complex type instead). Reference:
  https://en.wikipedia.org/wiki/Integer_square_root


***


### sub()


> **sub**(`other`, `_mode?`): `Integer`


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


Returns `this − other`.


`mode` is accepted for interface compatibility with fixed-width integer
types but is ignored.


#### Parameters


##### other


`Integer`


##### \_mode?


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


#### Returns


`Integer`


***


### toBigInt()


> **toBigInt**(): `bigint`


Defined in: packages/math-numbers/src/num/integer-num.ts:194


Returns the underlying `bigint` value.


#### Returns


`bigint`


***


### toExponential()


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


Defined in: packages/math-numbers/src/num/integer-num.ts:220


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/integer-num.ts:215


Fixed-point notation with `fractionDigits` places, all of them zeros.


#### Parameters


##### fractionDigits?


`number` = `0`


#### Returns


`string`


#### Implementation of


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


***


### toFraction()


> **toFraction**(): [`Fraction`](Fraction.md)


Defined in: packages/math-numbers/src/num/integer-num.ts:483


Returns this integer as the fraction `this / 1`.


#### Returns


[`Fraction`](Fraction.md)


***


### toIntegralFractional()


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


Defined in: packages/math-numbers/src/num/integer-num.ts:566


Returns this integer as an [IntegralFractional](../type-aliases/IntegralFractional.md). The fractional part
`f` is always `0n` because integers have no fraction.


#### Returns


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


***


### toPrecision()


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


Defined in: packages/math-numbers/src/num/integer-num.ts:225


`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/integer-num.ts:203


The exact numeral, in `radix` when given — every base from 2 to 36.


#### Parameters


##### radix?


`number`


#### Returns


`string`


#### Implementation of


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


***


### unsignedShiftRight()


> **unsignedShiftRight**(`n`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:409


Logical (unsigned) right shift `this >>> n`, treating the value as a 64-bit
unsigned integer. Fills with zero bits on the left.


#### Parameters


##### n


`number`


#### Returns


`Integer`


#### Implementation of


[`IBitwise`](../interfaces/IBitwise.md).[`unsignedShiftRight`](../interfaces/IBitwise.md#unsignedshiftright)


***


### valueOf()


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


Defined in: packages/math-numbers/src/num/integer-num.ts:233


Returns the nearest IEEE 754 double-precision approximation. Lossy for
large values.


#### Returns


`number`


#### Implementation of


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


***


### zero()


> **zero**(): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:306


Returns the additive identity `0`.


#### Returns


`Integer`


***


### from()


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


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


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


#### Parameters


##### value


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


#### Returns


`Integer`


***


### parse()


> `static` **parse**(`s`, `radix?`): `Integer`


Defined in: packages/math-numbers/src/num/integer-num.ts:185


Parses a string in any radix from 2 to 36.


#### Parameters


##### s


`string`


##### radix?


`number` = `10`


#### Returns


`Integer`


#### Throws


When the string is not a valid integer in the given
  radix.