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
guards
- isBigInt
instances
- Equivalence
- Order
math
- abs
- decrement
- divide
- gcd
- increment
- lcm
- multiply
- multiplyAll
- sign
- sqrt
- subtract
- sum
- sumAll
- unsafeDivide
- unsafeSqrt
predicates
utils
- clamp
- max
- min

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>

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>

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>

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

Since v2.0.0

instances

Equivalence

Signature

declare const Equivalence: equivalence.Equivalence<bigint>

Since v2.0.0

Order

Signature

declare const Order: order.Order<bigint>

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

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

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>
}

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 }

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

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 }

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 }

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

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

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>

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 }

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 }

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

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 }

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

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
}

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 }

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 }

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 }

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 }

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
}

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 }

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 }

Since v2.0.0