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

BigInt.ts 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: fromPrimitiveOrThrow, fromPrimitive
  • Predicates: isEven, isOdd
  • Destructors: log10, unsafeLog10

Quickstart

Example (Safe construction and parity)

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

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

Exports Grouped by Category

Constructors

fromPrimitive

Same as 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.fromPrimitive("123")) // Some(123n)
console.log(MBigInt.fromPrimitive("abc")) // None

Signature

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

Source

fromPrimitiveOrThrow

Builds a bigint from a string, number, or boolean. Number values must be integers (throws otherwise). Boolean value true becomes 1n, and false becomes 0n. String values must represent valid integer literals, cannot be an empty string and cannot have leading and trailing whitespaces (throws otherwise). However, string values can be prefixed with 0b, 0o, or 0x.

  • Use when an exception on invalid input is acceptable (e.g. trusted constants).
  • For untrusted input, prefer fromPrimitive.

Example (Throwing constructor)

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

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

See

  • fromPrimitive — non-throwing variant

Signature

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

Source

Destructors

log10

Safe variant of 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

See

  • unsafeLog10 — unchecked variant

Signature

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

Source

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

See

  • log10 — safe variant returning Option

Signature

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

Source

Models

Type (type alias)

Type on which this module’s functions operate.

Signature

type Type = bigint

Source

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

declare const isEven: Predicate.Predicate<bigint>

Source

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

declare const isOdd: Predicate.Predicate<bigint>

Source