BigNum

const BigNum: object

Defined in: Data/BigNum.ts:17

Safe conversion and arithmetic utilities for arbitrary-precision integers (bigint). All functions are pure and data-last to compose cleanly with pipe.

Type Declaration

abs

abs: (value) => bigint

Returns absolute value of a bigint.

Parameters

value

bigint

Returns

bigint

Example

BigNum.abs(-42n); // 42n

add

add: (amount) => (value) => bigint

Adds amount to value. Data-last curried signature: add(amount)(value) = value + amount.

Parameters

amount

bigint

Returns

(value) => bigint

See

BigNum.subtract to subtract an amount from a bigint.

Example

pipe(10n, BigNum.add(5n)); // 15n

between

between: (min, max) => (value) => boolean

Returns true when the bigint is between min and max (both inclusive).

Parameters

min

bigint

max

bigint

Returns

(value) => boolean

See

BigNum.inRange for half-open range checking [start, end).

Example

pipe(5n, BigNum.between(1n, 10n)); // true
pipe(0n, BigNum.between(1n, 10n)); // false

clamp

clamp: (min, max) => (value) => bigint

Clamps value between min and max (inclusive).

Parameters

min

bigint

max

bigint

Returns

(value) => bigint

Example

pipe(150n, BigNum.clamp(0n, 100n)); // 100n

divide

divide: (divisor) => (dividend) => Maybe<bigint>

Divides dividend by divisor. Returns None if divisor is 0n.

Parameters

divisor

bigint

Returns

(dividend) => Maybe<bigint>

See

• BigNum.multiply to multiply a bigint by a factor.
• BigNum.remainder to compute the division remainder.

Example

pipe(20n, BigNum.divide(4n)); // Some(5n)
pipe(5n, BigNum.divide(0n));  // None

from

from: object

Safe constructors and converters from raw primitives to BigInt.

from.number

number: (value) => Maybe<bigint>

Safely converts a number into a bigint. Returns None for floats, NaN, or non-safe integers.

Parameters

value

number

Returns

Maybe<bigint>

Example

BigNum.from.number(42);   // Some(42n)
BigNum.from.number(3.14); // None

from.string

string: (text) => Maybe<bigint>

Safely parses a string into a bigint. Returns None if parsing fails.

Parameters

text

string

Returns

Maybe<bigint>

Example

BigNum.from.string("123"); // Some(123n)
BigNum.from.string("abc"); // None

inRange

inRange: (start, end) => (value) => boolean

Returns true if value is in the range [start, end) (inclusive start, exclusive end).

Parameters

start

bigint

end

bigint

Returns

(value) => boolean

See

BigNum.between for fully closed range checking [min, max].

Example

pipe(5n, BigNum.inRange(1n, 10n)); // true

is

is: object

Predicates and type guards for BigInt values.

is.even

even: (value) => boolean

Returns true when the bigint is an even integer.

Parameters

value

bigint

Returns

boolean

See

BigNum.is.odd to check if a bigint is odd.

Example

BigNum.is.even(4n); // true
BigNum.is.even(3n); // false

is.negative

negative: (value) => boolean

Returns true when the bigint is strictly less than zero (0n).

Parameters

value

bigint

Returns

boolean

See

BigNum.is.positive to check if a bigint is greater than zero.

Example

BigNum.is.negative(-5n); // true
BigNum.is.negative(0n);  // false
BigNum.is.negative(5n);  // false

is.odd

odd: (value) => boolean

Returns true when the bigint is an odd integer.

Parameters

value

bigint

Returns

boolean

See

BigNum.is.even to check if a bigint is even.

Example

BigNum.is.odd(3n); // true
BigNum.is.odd(4n); // false

is.positive

positive: (value) => boolean

Returns true when the bigint is strictly greater than zero (0n).

Parameters

value

bigint

Returns

boolean

See

BigNum.is.negative to check if a bigint is less than zero.

Example

BigNum.is.positive(5n);  // true
BigNum.is.positive(0n);  // false
BigNum.is.positive(-5n); // false

is.zero

zero: (value) => boolean

Returns true when the bigint is equal to zero (0n).

Parameters

value

bigint

Returns

boolean

Example

BigNum.is.zero(0n); // true
BigNum.is.zero(5n); // false

max

max: (values) => Maybe<bigint>

Computes the maximum of a list of bigints. Returns None if the list is empty.

Parameters

values

readonly bigint[]

Returns

Maybe<bigint>

See

BigNum.min to compute the minimum value.

Example

BigNum.max([1n, 5n, 3n]); // Some(5n)
BigNum.max([]);           // None

min

min: (values) => Maybe<bigint>

Computes the minimum of a list of bigints. Returns None if the list is empty.

Parameters

values

readonly bigint[]

Returns

Maybe<bigint>

See

BigNum.max to compute the maximum value.

Example

BigNum.min([5n, 1n, 3n]); // Some(1n)
BigNum.min([]);           // None

multiply

multiply: (factor) => (value) => bigint

Multiplies value by factor. Data-last curried signature: multiply(factor)(value) = value * factor.

Parameters

factor

bigint

Returns

(value) => bigint

See

BigNum.divide to divide a bigint by a divisor.

Example

pipe(6n, BigNum.multiply(7n)); // 42n

remainder

remainder: (divisor) => (dividend) => Maybe<bigint>

Computes remainder of dividend / divisor. Returns None if divisor is 0n.

Parameters

divisor

bigint

Returns

(dividend) => Maybe<bigint>

See

BigNum.divide for full division.

Example

pipe(10n, BigNum.remainder(3n)); // Some(1n)
pipe(5n, BigNum.remainder(0n));  // None

subtract

subtract: (amount) => (from) => bigint

Subtracts amount from from. Data-last curried signature: subtract(amount)(from) = from - amount.

Parameters

amount

bigint

Returns

(from) => bigint

See

BigNum.add to add an amount to a bigint.

Example

pipe(10n, BigNum.subtract(3n)); // 7n

sum

sum: (values) => bigint

Computes the sum of a list of bigints. Returns 0n if the list is empty.

Parameters

values

readonly bigint[]

Returns

bigint

Example

BigNum.sum([1n, 2n, 3n]); // 6n
BigNum.sum([]);           // 0n

to

to: object

Converters from BigInt to native types.

to.number

number: (value) => Maybe<number>

Safely converts a bigint to a number. Returns None if the value is outside JavaScript’s safe integer range.

Parameters

value

bigint

Returns

Maybe<number>

Example

BigNum.to.number(42n);                    // Some(42)
BigNum.to.number(9007199254740993n);      // None

Example

import { BigNum, pipe } from "@pplnd/core";

const result = pipe(
  BigNum.from.string("100"),
  Maybe.map(BigNum.add(50n))
); // Some(150n)