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 Added in v2.0.0 Source

Conversions

fromNumber

Added in v2.4.12 Source

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

Added in v2.4.12 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

Signature

declare const Equivalence: equivalence.Equivalence<bigint>

Order

Added in v2.0.0 Source

Signature

declare const Order: order.Order<bigint>

Math

abs

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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

Added in v2.0.0 Source

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)