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

module:BigDecimal for more similar operations on BigDecimal types
module: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>;

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

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

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;

decrement

Added in v2.0.0 Source

Decrements a number by 1n.

Signature

declare function decrement(n: bigint): bigint;

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;

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;

sign

Added in v2.0.0 Source

Determines the sign of a given bigint.

Signature

declare function sign(n: bigint): Ordering;

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

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;

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;

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)