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

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

Added in v2.0.0

Table of contents

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

Signature

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

Example

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

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

Signature

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

Example

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

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

Signature

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

Example

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

Added in v2.0.0

guards

isBigInt

Tests if a value is a bigint.

Signature

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

Example

import { isBigInt } from "effect/BigInt"

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

Added in v2.0.0

instances

Equivalence

Signature

export declare const Equivalence: equivalence.Equivalence<bigint>

Added in v2.0.0

Order

Signature

export declare const Order: order.Order<bigint>

Added in v2.0.0

math

abs

Determines the absolute value of a given bigint.

Signature

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

Example

import { abs } from "effect/BigInt"

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

Added in v2.0.0

decrement

Decrements a number by 1n.

Signature

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

Example

import { decrement } from "effect/BigInt"

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

Added in 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.

Signature

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

Example

import { BigInt, Option } from "effect"

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

Added in v2.0.0

gcd

Determines the greatest common divisor of two bigints.

Signature

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

Example

import { gcd } from "effect/BigInt"

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

Added in v2.0.0

increment

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

Signature

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

Example

import { increment } from "effect/BigInt"

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

Added in v2.0.0

lcm

Determines the least common multiple of two bigints.

Signature

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

Example

import { lcm } from "effect/BigInt"

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

Added in v2.0.0

multiply

Provides a multiplication operation on bigints.

Signature

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

Example

import { multiply } from "effect/BigInt"

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

Added in v2.0.0

multiplyAll

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

Signature

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

Example

import { multiplyAll } from "effect/BigInt"

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

Added in v2.0.0

sign

Determines the sign of a given bigint.

Signature

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

Example

import { sign } from "effect/BigInt"

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

Added in v2.0.0

sqrt

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

Signature

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

Example

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

Added in v2.0.0

subtract

Provides a subtraction operation on bigints.

Signature

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

Example

import { subtract } from "effect/BigInt"

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

Added in v2.0.0

sum

Provides an addition operation on bigints.

Signature

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

Example

import { sum } from "effect/BigInt"

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

Added in v2.0.0

sumAll

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

Signature

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

Example

import { sumAll } from "effect/BigInt"

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

Added in 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.

Signature

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

Example

import { unsafeDivide } from "effect/BigInt"

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

Added in v2.0.0

unsafeSqrt

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

Signature

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

Example

import { unsafeSqrt } from "effect/BigInt"

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

Added in v2.0.0

predicates

between

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

Signature

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

Example

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)

Added in v2.0.0

greaterThan

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

Signature

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

Example

import { greaterThan } from "effect/BigInt"

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

Added in v2.0.0

greaterThanOrEqualTo

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

Signature

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

Example

import { greaterThanOrEqualTo } from "effect/BigInt"

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

Added in v2.0.0

lessThan

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

Signature

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

Example

import { lessThan } from "effect/BigInt"

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

Added in v2.0.0

lessThanOrEqualTo

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

Signature

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

Example

import { lessThanOrEqualTo } from "effect/BigInt"

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

Added in 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.

Signature

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

Example

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)

Added in v2.0.0

max

Returns the maximum between two bigints.

Signature

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

Example

import { max } from "effect/BigInt"

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

Added in v2.0.0

min

Returns the minimum between two bigints.

Signature

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

Example

import { min } from "effect/BigInt"

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

Added in v2.0.0