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 onBigDecimal
typesmodule:Number
for more similar operations onnumber
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>
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 bigint
s.
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 bigint
s.
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 bigint
s.
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 bigint
s.
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 bigint
s 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 bigint
s.
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 bigint
s.
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 bigint
s 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 bigint
s.
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 theminimum
value, the function returns theminimum
value. - If the
bigint
is greater than themaximum
value, the function returns themaximum
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 bigint
s.
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 bigint
s.
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