Skip to main content Link Search Menu Expand Document (external link)

BigInt.ts overview

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

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

Since v2.0.0


Exports Grouped by Category


conversions

fromNumber

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).

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())

Signature

declare const fromNumber: (n: number) => Option.Option<bigint>

Source

Since v2.4.12

fromString

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).

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())

Signature

declare const fromString: (s: string) => Option.Option<bigint>

Source

Since v2.4.12

toNumber

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).

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())

Signature

declare const toNumber: (b: bigint) => Option.Option<number>

Source

Since v2.0.0

guards

isBigInt

Tests if a value is a bigint.

Example

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

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

Signature

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

Source

Since v2.0.0

instances

Equivalence

Signature

declare const Equivalence: equivalence.Equivalence<bigint>

Source

Since v2.0.0

Order

Signature

declare const Order: order.Order<bigint>

Source

Since v2.0.0

math

abs

Determines the absolute value of a given 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)

Signature

declare const abs: (n: bigint) => bigint

Source

Since v2.0.0

decrement

Decrements a number by 1n.

Example

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

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

Signature

declare const decrement: (n: bigint) => bigint

Source

Since v2.0.0

divide

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.

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())

Signature

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

Source

Since v2.0.0

gcd

Determines the greatest common divisor of two bigints.

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)

Signature

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

Source

Since v2.0.0

increment

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

Example

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

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

Signature

declare const increment: (n: bigint) => bigint

Source

Since v2.0.0

lcm

Determines the least common multiple of two bigints.

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)

Signature

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

Source

Since v2.0.0

multiply

Provides a multiplication operation on bigints.

Example

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

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

Signature

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

Source

Since v2.0.0

multiplyAll

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

Example

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

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

Signature

declare const multiplyAll: (collection: Iterable<bigint>) => bigint

Source

Since v2.0.0

sign

Determines the sign of a given bigint.

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)

Signature

declare const sign: (n: bigint) => Ordering

Source

Since v2.0.0

sqrt

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

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())

Signature

declare const sqrt: (n: bigint) => Option.Option<bigint>

Source

Since v2.0.0

subtract

Provides a subtraction operation on bigints.

Example

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

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

Signature

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

Source

Since v2.0.0

sum

Provides an addition operation on bigints.

Example

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

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

Signature

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

Source

Since v2.0.0

sumAll

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

Example

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

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

Signature

declare const sumAll: (collection: Iterable<bigint>) => bigint

Source

Since v2.0.0

unsafeDivide

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.

Example

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

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

Signature

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

Source

Since v2.0.0

unsafeSqrt

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

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)

Signature

declare const unsafeSqrt: (n: bigint) => bigint

Source

Since v2.0.0

predicates

between

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

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)

Signature

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

Source

Since v2.0.0

greaterThan

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

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)

Signature

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

Source

Since v2.0.0

greaterThanOrEqualTo

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

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)

Signature

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

Source

Since v2.0.0

lessThan

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

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)

Signature

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

Source

Since v2.0.0

lessThanOrEqualTo

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

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)

Signature

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

Source

Since v2.0.0

utils

clamp

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.

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)

Signature

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

Source

Since v2.0.0

max

Returns the maximum between two bigints.

Example

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

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

Signature

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

Source

Since v2.0.0

min

Returns the minimum between two bigints.

Example

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

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

Signature

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

Source

Since v2.0.0