BigInt

This module provides utility functions and type class instances for working with the bigint type in TypeScript. It includes functions for basic arithmetic operations, as well as type class instances for Equivalence and Order.

See

:BigDecimal for more similar operations on BigDecimal types
:Number for more similar operations on number types

29 exports Since v2.0.0 Source

Conversions

fromNumber

Since v2.4.12

Takes a number and returns an Option of bigint.

If the number is outside the safe integer range for JavaScript (Number.MAX_SAFE_INTEGER and Number.MIN_SAFE_INTEGER), it returns Option.none(). Otherwise, it attempts to convert the number to a bigint and returns Option.some(bigint).

Signature

declare function fromNumber(n: number): Option<bigint>

Example

import * as assert from "node:assert"
import { BigInt as BI, Option } from "effect"

assert.deepStrictEqual(BI.fromNumber(42), Option.some(BigInt(42)))
assert.deepStrictEqual(BI.fromNumber(Number.MAX_SAFE_INTEGER + 1), Option.none())
assert.deepStrictEqual(BI.fromNumber(Number.MIN_SAFE_INTEGER - 1), Option.none())

fromString

Since v2.4.12

Takes a string and returns an Option of bigint.

If the string is empty or contains characters that cannot be converted into a bigint, it returns Option.none(), otherwise, it returns Option.some(bigint).

Signature

declare function fromString(s: string): Option<bigint>

Example

import * as assert from "node:assert"
import { BigInt as BI, Option } from "effect"

assert.deepStrictEqual(BI.fromString("42"), Option.some(BigInt(42)))
assert.deepStrictEqual(BI.fromString(" "), Option.none())
assert.deepStrictEqual(BI.fromString("a"), Option.none())

toNumber

Since v2.0.0

Takes a bigint and returns an Option of number.

If the bigint is outside the safe integer range for JavaScript (Number.MAX_SAFE_INTEGER and Number.MIN_SAFE_INTEGER), it returns Option.none(). Otherwise, it converts the bigint to a number and returns Option.some(number).

Signature

declare function toNumber(b: bigint): Option<number>

Example

import * as assert from "node:assert"
import { BigInt as BI, Option } from "effect"

assert.deepStrictEqual(BI.toNumber(BigInt(42)), Option.some(42))
assert.deepStrictEqual(BI.toNumber(BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1)), Option.none())
assert.deepStrictEqual(BI.toNumber(BigInt(Number.MIN_SAFE_INTEGER) - BigInt(1)), Option.none())

Guards

isBigInt

Since v2.0.0

Tests if a value is a bigint.

Signature

declare const isBigInt: (u: unknown) => u is bigint

Example

import * as assert from "node:assert"
import { isBigInt } from "effect/BigInt"

assert.deepStrictEqual(isBigInt(1n), true)
assert.deepStrictEqual(isBigInt(1), false)

Instances

Equivalence

Since v2.0.0

Signature

declare const Equivalence: equivalence.Equivalence<bigint>

Order

Since v2.0.0

Signature

declare const Order: order.Order<bigint>

Math

abs

Since v2.0.0

Determines the absolute value of a given bigint.

Signature

declare function abs(n: bigint): bigint

Example

import * as assert from "node:assert"
import { abs } from "effect/BigInt"

assert.deepStrictEqual(abs(-5n), 5n)
assert.deepStrictEqual(abs(0n), 0n)
assert.deepStrictEqual(abs(5n), 5n)

decrement

Since v2.0.0

Decrements a number by 1n.

Signature

declare function decrement(n: bigint): bigint

Example

import * as assert from "node:assert"
import { decrement } from "effect/BigInt"

assert.deepStrictEqual(decrement(3n), 2n)

divide

Since v2.0.0

Provides a division operation on bigints.

If the dividend is not a multiple of the divisor the result will be a bigint value which represents the integer division rounded down to the nearest integer.

Returns None if the divisor is 0n.

Signature

declare const divide: {
  (that: bigint): (self: bigint) => Option<bigint>;
  (self: bigint, that: bigint): Option<bigint>;
}

Example

import * as assert from "node:assert"
import { BigInt, Option } from "effect"

assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())

gcd

Since v2.0.0

Determines the greatest common divisor of two bigints.

Signature

declare const gcd: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

Example

import * as assert from "node:assert"
import { gcd } from "effect/BigInt"

assert.deepStrictEqual(gcd(2n, 3n), 1n)
assert.deepStrictEqual(gcd(2n, 4n), 2n)
assert.deepStrictEqual(gcd(16n, 24n), 8n)

increment

Since v2.0.0

Returns the result of adding 1n to a given number.

Signature

declare function increment(n: bigint): bigint

Example

import * as assert from "node:assert"
import { increment } from "effect/BigInt"

assert.deepStrictEqual(increment(2n), 3n)

lcm

Since v2.0.0

Determines the least common multiple of two bigints.

Signature

declare const lcm: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

Example

import * as assert from "node:assert"
import { lcm } from "effect/BigInt"

assert.deepStrictEqual(lcm(2n, 3n), 6n)
assert.deepStrictEqual(lcm(2n, 4n), 4n)
assert.deepStrictEqual(lcm(16n, 24n), 48n)

multiply

Since v2.0.0

Provides a multiplication operation on bigints.

Signature

declare const multiply: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

Example

import * as assert from "node:assert"
import { multiply } from "effect/BigInt"

assert.deepStrictEqual(multiply(2n, 3n), 6n)

multiplyAll

Since v2.0.0

Takes an Iterable of bigints and returns their multiplication as a single number.

Signature

declare function multiplyAll(collection: Iterable<bigint>): bigint

Example

import * as assert from "node:assert"
import { multiplyAll } from "effect/BigInt"

assert.deepStrictEqual(multiplyAll([2n, 3n, 4n]), 24n)

sign

Since v2.0.0

Determines the sign of a given bigint.

Signature

declare function sign(n: bigint): Ordering

Example

import * as assert from "node:assert"
import { sign } from "effect/BigInt"

assert.deepStrictEqual(sign(-5n), -1)
assert.deepStrictEqual(sign(0n), 0)
assert.deepStrictEqual(sign(5n), 1)

sqrt

Since v2.0.0

Determines the square root of a given bigint safely. Returns none if the given bigint is negative.

Signature

declare function sqrt(n: bigint): Option<bigint>

Example

import * as assert from "node:assert"
import { BigInt, Option } from "effect"

assert.deepStrictEqual(BigInt.sqrt(4n), Option.some(2n))
assert.deepStrictEqual(BigInt.sqrt(9n), Option.some(3n))
assert.deepStrictEqual(BigInt.sqrt(16n), Option.some(4n))
assert.deepStrictEqual(BigInt.sqrt(-1n), Option.none())

subtract

Since v2.0.0

Provides a subtraction operation on bigints.

Signature

declare const subtract: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

Example

import * as assert from "node:assert"
import { subtract } from "effect/BigInt"

assert.deepStrictEqual(subtract(2n, 3n), -1n)

sum

Since v2.0.0

Provides an addition operation on bigints.

Signature

declare const sum: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

Example

import * as assert from "node:assert"
import { sum } from "effect/BigInt"

assert.deepStrictEqual(sum(2n, 3n), 5n)

sumAll

Since v2.0.0

Takes an Iterable of bigints and returns their sum as a single `bigint

Signature

declare function sumAll(collection: Iterable<bigint>): bigint

Example

import * as assert from "node:assert"
import { sumAll } from "effect/BigInt"

assert.deepStrictEqual(sumAll([2n, 3n, 4n]), 9n)

unsafeDivide

Since v2.0.0

Provides a division operation on bigints.

If the dividend is not a multiple of the divisor the result will be a bigint value which represents the integer division rounded down to the nearest integer.

Throws a RangeError if the divisor is 0n.

Signature

declare const unsafeDivide: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

Example

import * as assert from "node:assert"
import { unsafeDivide } from "effect/BigInt"

assert.deepStrictEqual(unsafeDivide(6n, 3n), 2n)
assert.deepStrictEqual(unsafeDivide(6n, 4n), 1n)

unsafeSqrt

Since v2.0.0

Determines the square root of a given bigint unsafely. Throws if the given bigint is negative.

Signature

declare function unsafeSqrt(n: bigint): bigint

Example

import * as assert from "node:assert"
import { unsafeSqrt } from "effect/BigInt"

assert.deepStrictEqual(unsafeSqrt(4n), 2n)
assert.deepStrictEqual(unsafeSqrt(9n), 3n)
assert.deepStrictEqual(unsafeSqrt(16n), 4n)

Other

clamp

Since v2.0.0

Restricts the given bigint to be within the range specified by the minimum and maximum values.

If the bigint is less than the minimum value, the function returns the minimum value.
If the bigint is greater than the maximum value, the function returns the maximum value.
Otherwise, it returns the original bigint.

Signature

declare const clamp: {
  (options: {
    maximum: bigint;
    minimum: bigint;
  }): (self: bigint) => bigint;
  (self: bigint, options: {
    maximum: bigint;
    minimum: bigint;
  }): bigint;
}

Example

import * as assert from "node:assert"
import { BigInt } from "effect"

const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })

assert.equal(clamp(3n), 3n)
assert.equal(clamp(0n), 1n)
assert.equal(clamp(6n), 5n)

max

Since v2.0.0

Returns the maximum between two bigints.

Signature

declare const max: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

Example

import * as assert from "node:assert"
import { max } from "effect/BigInt"

assert.deepStrictEqual(max(2n, 3n), 3n)

min

Since v2.0.0

Returns the minimum between two bigints.

Signature

declare const min: {
  (that: bigint): (self: bigint) => bigint;
  (self: bigint, that: bigint): bigint;
}

Example

import * as assert from "node:assert"
import { min } from "effect/BigInt"

assert.deepStrictEqual(min(2n, 3n), 2n)

Predicates

between

Since v2.0.0

Checks if a bigint is between a minimum and maximum value (inclusive).

Signature

declare const between: {
  (options: {
    maximum: bigint;
    minimum: bigint;
  }): (self: bigint) => boolean;
  (self: bigint, options: {
    maximum: bigint;
    minimum: bigint;
  }): boolean;
}

Example

import * as assert from "node:assert"
import { BigInt } from "effect"

const between = BigInt.between({ minimum: 0n, maximum: 5n })

assert.deepStrictEqual(between(3n), true)
assert.deepStrictEqual(between(-1n), false)
assert.deepStrictEqual(between(6n), false)

greaterThan

Since v2.0.0

Returns true if the first argument is greater than the second, otherwise false.

Signature

declare const greaterThan: {
  (that: bigint): (self: bigint) => boolean;
  (self: bigint, that: bigint): boolean;
}

Example

import * as assert from "node:assert"
import { greaterThan } from "effect/BigInt"

assert.deepStrictEqual(greaterThan(2n, 3n), false)
assert.deepStrictEqual(greaterThan(3n, 3n), false)
assert.deepStrictEqual(greaterThan(4n, 3n), true)

greaterThanOrEqualTo

Since v2.0.0

Returns a function that checks if a given bigint is greater than or equal to the provided one.

Signature

declare const greaterThanOrEqualTo: {
  (that: bigint): (self: bigint) => boolean;
  (self: bigint, that: bigint): boolean;
}

Example

import * as assert from "node:assert"
import { greaterThanOrEqualTo } from "effect/BigInt"

assert.deepStrictEqual(greaterThanOrEqualTo(2n, 3n), false)
assert.deepStrictEqual(greaterThanOrEqualTo(3n, 3n), true)
assert.deepStrictEqual(greaterThanOrEqualTo(4n, 3n), true)

lessThan

Since v2.0.0

Returns true if the first argument is less than the second, otherwise false.

Signature

declare const lessThan: {
  (that: bigint): (self: bigint) => boolean;
  (self: bigint, that: bigint): boolean;
}

Example

import * as assert from "node:assert"
import { lessThan } from "effect/BigInt"

assert.deepStrictEqual(lessThan(2n, 3n), true)
assert.deepStrictEqual(lessThan(3n, 3n), false)
assert.deepStrictEqual(lessThan(4n, 3n), false)

lessThanOrEqualTo

Since v2.0.0

Returns a function that checks if a given bigint is less than or equal to the provided one.

Signature

declare const lessThanOrEqualTo: {
  (that: bigint): (self: bigint) => boolean;
  (self: bigint, that: bigint): boolean;
}

Example

import * as assert from "node:assert"
import { lessThanOrEqualTo } from "effect/BigInt"

assert.deepStrictEqual(lessThanOrEqualTo(2n, 3n), true)
assert.deepStrictEqual(lessThanOrEqualTo(3n, 3n), true)
assert.deepStrictEqual(lessThanOrEqualTo(4n, 3n), false)