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

BigInt overview

Extension to the Effect BigInt module providing safe constructors from primitives, parity predicates, and a base-10 logarithm.

Mental model

  • bigint is JavaScript’s built-in arbitrary-precision integer.
  • This module focuses on safe construction (fromPrimitive*), parity predicates, and a linear-time base-10 logarithm computed from the decimal representation.

Common tasks

  • Construct: {@link fromPrimitiveOrThrow}, {@link fromPrimitiveOption}
  • Predicates: {@link isEven}, {@link isOdd}
  • Destructors: {@link log10}, {@link unsafeLog10}

Quickstart

Example (Safe construction and parity)

import * as MBigInt from "@parischap/effect-lib/MBigInt"

console.log(MBigInt.fromPrimitiveOption("123")) // Some(123n)
console.log(MBigInt.fromPrimitiveOption("abc")) // None
console.log(MBigInt.isEven(4n)) // true
console.log(MBigInt.log10(100n)) // Some(2)

Table of contents

Constructors

fromPrimitiveOption

Same as {@link fromPrimitiveOrThrow} but returns Option.none instead of throwing on invalid input.

  • Use to build a bigint from untrusted input.

Example (Safe construction)

import * as MBigInt from "@parischap/effect-lib/MBigInt"

console.log(MBigInt.fromPrimitiveOption("123")) // Some(123n)
console.log(MBigInt.fromPrimitiveOption("abc")) // None

Signature

export declare const fromPrimitiveOption: MTypes.OneArgFunction<string | number | boolean, Option.Option<bigint>>

fromPrimitiveOrThrow

Builds a bigint from a string, number, or boolean. Throws when the input cannot be converted (e.g. NaN, non-integer numbers, malformed strings).

  • Use when an exception on invalid input is acceptable (e.g. trusted constants).
  • For untrusted input, prefer {@link fromPrimitiveOption}.

Example (Throwing constructor)

import * as MBigInt from "@parischap/effect-lib/MBigInt"

console.log(MBigInt.fromPrimitiveOrThrow("123")) // 123n
console.log(MBigInt.fromPrimitiveOrThrow(true)) // 1n

Signature

export declare const fromPrimitiveOrThrow: MTypes.OneArgFunction<string | number | boolean, bigint>

Destructors

log10

Safe variant of {@link unsafeLog10}: returns Option.some(floor(log10(self))) for strictly positive self, otherwise Option.none.

  • Returns Option.none for 0n and for strictly negative values.

Example (Safe base-10 logarithm)

import * as MBigInt from "@parischap/effect-lib/MBigInt"

console.log(MBigInt.log10(100n)) // Some(2)
console.log(MBigInt.log10(0n)) // None
console.log(MBigInt.log10(-5n)) // None

Signature

export declare const log10: MTypes.OneArgFunction<bigint, Option.Option<number>>

unsafeLog10

Returns floor(log10(self)) (i.e. one less than the number of decimal digits) without input validation.

  • Use when self is statically known to be strictly positive.
  • Computed from the length of the decimal representation of self.
  • For non-positive input the result is meaningless: unsafeLog10(0n) returns 0, and for negative values the leading '-' sign is counted as a digit.

Example (Unchecked base-10 logarithm)

import * as MBigInt from "@parischap/effect-lib/MBigInt"

console.log(MBigInt.unsafeLog10(100n)) // 2
console.log(MBigInt.unsafeLog10(10n)) // 1

Signature

export declare const unsafeLog10: (self: Type) => number

Models

Type (type alias)

Type on which this module’s functions operate.

Signature

export type Type = bigint

Predicates

isEven

Returns true when self is even.

Example (Even check)

import * as MBigInt from "@parischap/effect-lib/MBigInt"

console.log(MBigInt.isEven(4n)) // true
console.log(MBigInt.isEven(5n)) // false

Signature

export declare const isEven: Predicate.Predicate<bigint>

isOdd

Returns true when self is odd.

Example (Odd check)

import * as MBigInt from "@parischap/effect-lib/MBigInt"

console.log(MBigInt.isOdd(5n)) // true
console.log(MBigInt.isOdd(4n)) // false

Signature

export declare const isOdd: Predicate.Predicate<bigint>