functionalscript 0.43.1 → 0.45.0

package/fjs/types/bigfloat/proof.f.d.mts

@@ -0,0 +1,6 @@
+export declare const proof: {
+    decToBin: (() => void)[];
+    roundingPositive: (() => void)[];
+    roundingNegative: (() => void)[];
+    roundingCarry: (() => void)[];
+};

package/fjs/types/bigfloat/proof.f.mjs

@@ -0,0 +1,264 @@
+import { decToBin } from './module.f.mjs'
+import { assertEq } from '../../asserts/module.f.mjs'
+import { bitLength } from '../bigint/module.f.mjs'
+
+/**
+ * Checks `decToBin`'s postcondition on a non-zero result: the mantissa holds
+ * exactly 53 significant bits, and `m * 2^e` is the value it should be.
+ * `bitLength` measures the magnitude, so a negative mantissa is checked as
+ * strictly as a positive one. The value is recovered with a shift, so every
+ * `dec` passed here must round to a whole number (a non-negative `e`).
+ *
+ * @type {(dec: readonly [bigint, number]) => (value: bigint) => void}
+ */
+const assertRounded = dec => value => {
+    const [m, e] = decToBin(dec)
+    assertEq(bitLength(m), 53n, m.toString(2))
+    assertEq(m << BigInt(e), value, m.toString(2))
+}
+
+export const proof = {
+    decToBin: [
+        () => {
+            const result = decToBin([0n, 0])
+            assertEq(result[0], 0b0_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], 0)
+        },
+        () => {
+            const result = decToBin([0n, 10])
+            assertEq(result[0], 0b0_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], 0)
+        },
+        () => {
+            const result = decToBin([0n, -10])
+            assertEq(result[0], 0b0_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], 0)
+        },
+        () => {
+            const result = decToBin([1n, 0])
+            assertEq(result[0], 0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], -52)
+        },
+        () => {
+            const result = decToBin([1n, 1])
+            assertEq(result[0], 0b1_0100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], -49)
+        },
+        () => {
+            const result = decToBin([1000n, -2])
+            assertEq(result[0], 0b1_0100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], -49)
+        },
+        () => {
+            const result = decToBin([1n, -1])
+            assertEq(result[0], 0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1010n, result[0].toString(2)) //+1
+            assertEq(result[1], -56)
+        },
+        () => {
+            const result = decToBin([-1n, 0])
+            assertEq(result[0], -0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], -52)
+        },
+        () => {
+            const result = decToBin([-1n, 1])
+            assertEq(result[0], -0b1_0100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], -49)
+        },
+        () => {
+            const result = decToBin([-1000n, -2])
+            assertEq(result[0], -0b1_0100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], -49)
+        },
+        () => {
+            const result = decToBin([-1n, -1])
+            assertEq(result[0], -0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1010n, result[0].toString(2)) //+1
+            assertEq(result[1], -56)
+        },
+        () => {
+            const result = decToBin([0b10_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001n, 0]) //54bits (...0.1)
+            assertEq(result[0], 0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], 1)
+        },
+        () => {
+            const result = decToBin([-0b10_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0011n, 0]) //54bits (...1.1)
+            assertEq(result[0], -0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010n, result[0].toString(2))
+            assertEq(result[1], 1)
+        },
+        () => {
+            const result = decToBin([-0b10_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001n, 0]) //54bits (...0.1)
+            assertEq(result[0], -0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], 1)
+        },
+        () => {
+            const result = decToBin([-0b10_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0011n, 0]) //54bits (...1.1)
+            assertEq(result[0], -0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010n, result[0].toString(2))
+            assertEq(result[1], 1)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001n, 0]) //55bits (...0.01)
+            assertEq(result[0], 0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010n, 0]) //55bits (...0.10)
+            assertEq(result[0], 0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0110n, 0]) //55bits (...1.10)
+            assertEq(result[0], 0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0011n, 0]) //55bits (0.11)
+            assertEq(result[0], 0b1_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+    ],
+    roundingPositive: [
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001n, -1])
+            // reminder = 0
+            // m = 11001100110011001100110011001100110011001100110011001.101
+            // rounding up
+            assertEq(result[0], 0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1010n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_0000n, -1])
+            // reminder = 0
+            // m = 11001100110011001100110011001100110011001100110011010.000
+            // rounding down
+            assertEq(result[0], 0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1010n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_0100n, -1])
+            // reminder = 0
+            // m = 11001100110011001100110011001100110011001100110011010.100
+            // rounding down (to even)
+            assertEq(result[0], 0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1010n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_0101n, -1])
+            // reminder = 1
+            // m = 11001100110011001100110011001100110011001100110011010.100
+            // rounding up
+            assertEq(result[0], 0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1011n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_1001n, -1])
+            // reminder = 0
+            // m = 11001100110011001100110011001100110011001100110011010.101
+            // rounding up
+            assertEq(result[0], 0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1011n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0011_1101n, -1])
+            // reminder = 0
+            // m = 11001100110011001100110011001100110011001100110011011.001
+            // rounding down
+            assertEq(result[0], 0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1011n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0100_1100n, -1])
+            // reminder = 0
+            // m = 11001100110011001100110011001100110011001100110011011.100
+            // rounding up (to even)
+            assertEq(result[0], 0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1100n, result[0].toString(2))
+            assertEq(result[1], 2)
+        }
+    ],
+    roundingNegative: [
+        () => {
+            const result = decToBin([-0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001n, -1])
+            // reminder = 0
+            // m = -11001100110011001100110011001100110011001100110011001.101
+            // rounding down
+            assertEq(result[0], -0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1010n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([-0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0001_0000n, -1])
+            // reminder = 0
+            // m = -11001100110011001100110011001100110011001100110011010.000
+            // rounding up
+            assertEq(result[0], -0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1010n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([-0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_0100n, -1])
+            // reminder = 0
+            // m = -11001100110011001100110011001100110011001100110011010.100
+            // rounding up (to even)
+            assertEq(result[0], -0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1010n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([-0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_0101n, -1])
+            // reminder = 1
+            // m = -11001100110011001100110011001100110011001100110011010.100
+            // rounding down
+            assertEq(result[0], -0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1011n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([-0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0010_1001n, -1])
+            // reminder = 0
+            // m = -11001100110011001100110011001100110011001100110011010.101
+            // rounding down
+            assertEq(result[0], -0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1011n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([-0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0011_1101n, -1])
+            // reminder = 0
+            // m = -11001100110011001100110011001100110011001100110011011.001
+            // rounding up
+            assertEq(result[0], -0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1011n, result[0].toString(2))
+            assertEq(result[1], 2)
+        },
+        () => {
+            const result = decToBin([-0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0100_1100n, -1])
+            // reminder = 0
+            // m = -11001100110011001100110011001100110011001100110011011.100
+            // rounding down (to even)
+            assertEq(result[0], -0b1_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1001_1100n, result[0].toString(2))
+            assertEq(result[1], 2)
+        }
+    ],
+    // Rounding up a mantissa of all ones carries into a 54th bit; the result
+    // has to come back as 53 bits without changing the value.
+    roundingCarry: [
+        () => {
+            // 54 ones: an exact tie (nothing below the dropped bit, remainder
+            // 0) whose round-to-even goes up because 2^53 - 1 is odd.
+            assertRounded([0b11_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111n, 0])(
+                0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n) // 2^54
+        },
+        () => {
+            assertRounded([-0b11_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111n, 0])(
+                -0b100_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n) // -2^54
+        },
+        () => {
+            // 55 ones: not a tie — the dropped bits are 11 — so the carry comes
+            // from the plain round-up path instead.
+            assertRounded([0b111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111n, 0])(
+                0b1000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n) // 2^55
+        },
+        () => {
+            assertRounded([-0b111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111n, 0])(
+                -0b1000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000_0000n) // -2^55
+        },
+        () => {
+            // A neighbour that doesn't carry: also a tie, but 2^53 - 2 is even,
+            // so round-to-even goes down and the mantissa stays 53 bits wide.
+            assertRounded([0b11_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1101n, 0])(
+                0b11_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1111_1100n)
+        },
+    ]
+}

package/fjs/types/bigfloat/types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Types for big-floats built from bigint mantissa and exponent parts.
+ *
+ * @module
+ */
+export type BigFloat = readonly [bigint, number];

package/fjs/types/bigint/benchmark.mjs

@@ -0,0 +1,205 @@
+/** @type {(v: bigint) => bigint} */
+const log2 = v => {
+    if (v <= 0n) { return -1n }
+    let result = 31n
+    let i = 32n
+    while (true) {
+        const n = v >> i
+        if (n === 0n) {
+            // overshot
+            break
+        }
+        v = n
+        result += i
+        i <<= 1n
+    }
+    // We know that `v` is not 0 so it doesn't make sense to check `n` when `i` is 0.
+    // Because of this, We check if `i` is greater than 32 before we divide it by 2.
+    while (i !== 32n) {
+        i >>= 1n
+        const n = v >> i
+        if (n !== 0n) {
+            result += i
+            v = n
+        }
+    }
+    return result - BigInt(Math.clz32(Number(v)))
+}
+
+/** @type {(v: bigint) => bigint} */
+const oldLog2 = v => {
+    if (v <= 0n) { return -1n }
+    let result = 0n
+    let i = 1n
+    while (true) {
+        const n = v >> i
+        if (n === 0n) {
+            // overshot
+            break
+        }
+        v = n
+        result += i
+        i <<= 1n // multiple by two
+    }
+    // We know that `v` is not 0 so it doesn't make sense to check `n` when `i` is 0.
+    // Because of this, We check if `i` is greater than 1 before we divide it by 2.
+    while (i !== 1n) {
+        i >>= 1n
+        const n = v >> i
+        if (n !== 0n) {
+            result += i
+            v = n
+        }
+    }
+    return result
+}
+
+/** @type {(v: bigint) => bigint} */
+const stringLog2 = v => BigInt(v.toString(2).length) - 1n
+
+/** @type {(v: bigint) => bigint} */
+const stringHexLog2 = v => {
+    const len = (BigInt(v.toString(16).length) - 1n) << 2n
+    const x = v >> len
+    return len + 31n - BigInt(Math.clz32(Number(x)))
+}
+/** @type {(v: bigint) => bigint} */
+const string32Log2 = n => {
+    const i = (BigInt(n.toString(32).length) - 1n) * 5n
+    return i + 31n - BigInt(Math.clz32(Number(n >> i)))
+}
+
+/** @type {(v: bigint) => bigint} */
+const mathLog2 = v => {
+    if (v <= 0n) { return -1n }
+    let result = -1n
+    let i = 1023n
+    while (true) {
+        const n = v >> i
+        if (n === 0n) {
+            // overshot
+            break
+        }
+        v = n
+        result += i
+        i <<= 1n
+    }
+    // We know that `v` is not 0 so it doesn't make sense to check `n` when `i` is 0.
+    // Because of this, We check if `i` is greater than 32 before we divide it by 2.
+    while (i !== 1023n) {
+        i >>= 1n
+        const n = v >> i
+        if (n !== 0n) {
+            result += i
+            v = n
+        }
+    }
+    const x = BigInt(Math.log2(Number(v)) | 0)
+    return result + x + (v >> x)
+}
+
+const mLog2 = Math.log2
+
+/** @type {(v: bigint) => bigint} */
+const ylog2 = n => {
+    let i = -1n
+    let j = 0x400n
+    while (true) {
+        const m = n >> j
+        if (m === 0n) {
+            // overshot
+            break
+        }
+        n = m
+        i += j
+        j <<= 1n
+    }
+    while (j !== 0x400n) {
+        j >>= 1n
+        const m = n >> j
+        if (m !== 0n) {
+            i += j
+            n = m
+        }
+    }
+    const nl = mLog2(Number(n))
+    if (isFinite(nl)) {
+        const rem = BigInt(nl | 0)
+        i += rem + (n >> rem)
+    } else {
+        i += 0x400n
+    }
+
+    return i
+}
+
+/** @type {HTMLElement} */
+// @ts-ignore
+const log = document.getElementById('log')
+
+/** @type {(v: (_: bigint) => bigint) => void} */
+const big = f => {
+    let e = 1_048_575n
+    let c = 1n << e
+    for (let i = 0n; i < 1_000; ++i) {
+        //
+        {
+            const x = f(c)
+            if (x !== e) { throw [e, x] }
+        }
+        {
+            const x = f(c - 1n)
+            if (x !== e - 1n) { throw [e, x] }
+        }
+        //
+        c >>= 1n
+        --e
+    }
+}
+
+/** @type {(a: bigint) => (b: bigint) => bigint} */
+const min = a => b => a < b ? a : b
+
+/** @type {(f: (_: bigint) => bigint) => void} */
+const small = f => {
+    let e = 2_000n
+    let c = 1n << e
+    do {
+        {
+            const x = f(c)
+            if (x !== e) { throw [e, x] }
+        }
+        for (let j = 1n; j < min(c >> 1n)(1000n); ++j) {
+            const x = f(c - j)
+            if (x !== e - 1n) { throw [j, e, x] }
+        }
+        c >>= 1n
+        --e
+    } while (c !== 0n)
+}
+
+/** @type {(t: (_: (_: bigint) => bigint) => void) => (s: string, f: (_: bigint) => bigint) => void} */
+const benchmark = t => (s, f) => {
+    const start = performance.now()
+    t(f)
+    const end = performance.now()
+    const dif = end - start
+    //
+    log.innerText += `${s}: ${dif}\n`
+}
+
+/** @type {(t: (_: (_: bigint) => bigint) => void) => void} */
+const run = t => {
+    log.innerText += `${t.name}\n`
+    const b = benchmark(t)
+    // b('stringLog2', stringLog2)
+    // b('stringHexLog2', stringHexLog2)
+    b('string32Log2', string32Log2)
+    // b('oldLog2', oldLog2)
+    // b('log2', log2)
+    // b('mathLog2', mathLog2)
+    b('ylog2', ylog2)
+}
+
+run(big)
+run(small)

package/fjs/types/bigint/module.f.d.mts

@@ -0,0 +1,180 @@
+/**
+ * Utility functions for working with `bigint` values.
+ *
+ * @module
+ *
+ * @example
+ *
+ * ```js
+ * import { sum, abs, log2, bitLength, mask } from './module.f.ts'
+ *
+ * const total = sum([1n, 2n, 3n]) // 6n
+ * const absoluteValue = abs(-42n) // 42n
+ * const logValue = log2(8n) // 3n
+ * const bitCount = bitLength(255n) // 8n
+ * const bitmask = mask(5n) // 31n
+ * const c = combination([3n, 2n, 1n]) // 60n
+ * ```
+ *
+ * @import { Sign } from '../function/compare/types.ts'
+ * @import { List } from '../list/types.ts'
+ * @import { Reduce, Unary } from './types.ts'
+ */
+import type { Sign } from '../function/compare/types.ts';
+import type { List } from '../list/types.ts';
+import type { Reduce, Unary } from './types.ts';
+/**
+ * Adds two `bigint` values.
+ * TODO: should be combined with `addition` for `number`.
+ *
+ * @param {bigint} a - The first bigint value.
+ * @returns {Unary} A function that takes the second bigint value and returns the sum.
+ */
+export declare const addition: (a: bigint) => Unary;
+/**
+ * Calculates the sum of a list of `bigint` values.
+ *
+ * @param {List<bigint>} input - A list of bigint values.
+ * @returns {bigint} The sum of all values in the list.
+ */
+export declare const sum: (list: List<bigint>) => bigint;
+/**
+ * Multiplies two `bigint` values.
+ *
+ * @param {bigint} a - The first bigint value.
+ * @returns {Unary} A function that takes the second bigint value and returns the product.
+ */
+export declare const multiple: (a: bigint) => Unary;
+/**
+ * Calculates the product of a list of `bigint` values.
+ *
+ * @param {List<bigint>} input - A list of bigint values.
+ * @returns {bigint} The product of all values in the list.
+ */
+export declare const product: (list: List<bigint>) => bigint;
+/**
+ * Calculates the absolute value of a `bigint`.
+ *
+ * @param {bigint} a - The bigint value.
+ * @returns {bigint} The absolute value of the input bigint.
+ */
+export declare const abs: (a: bigint) => bigint;
+/**
+ * Determines the sign of a `bigint`.
+ * @param {bigint} a - The bigint value.
+ * @returns {Sign} `1` if positive, `-1` if negative, and `0` if zero.
+ */
+export declare const sign: (a: bigint) => Sign;
+/**
+ * Serializes a `bigint` to a string representation.
+ *
+ * @param {bigint} a - The bigint value.
+ * @returns {string} A string representation of the bigint (e.g., '123n').
+ */
+export declare const serialize: (a: bigint) => string;
+/**
+ * Calculates the base-2 logarithm (floor).
+ *
+ * This function returns the integer part of the logarithm. For example:
+ * - `log2(1n)` returns `0n`,
+ * - `log2(2n)` returns `1n`,
+ * - `log2(15n)` returns `3n`.
+ *
+ * @param {bigint} v - The input BigInt.
+ * @returns {bigint} The base-2 logarithm (floor) of the input BigInt, or `-1n` if the input is less than or equal to 0.
+ *
+ * @remarks
+ * The function operates in two phases:
+ * 1. **Fast Doubling Phase:** Uses exponential steps to quickly narrow down the range
+ *    of the most significant bit.
+ * 2. **Binary Search Phase:** Refines the result by halving the step size and incrementally
+ *    determining the exact value of the logarithm.
+ * 3. **Remainder Phase:** Using `Math.log2`.
+ */
+export declare const log2: (v: bigint) => bigint;
+/**
+ * Calculates the bit length of a given BigInt.
+ *
+ * The bit length of a number is the number of bits required to represent its absolute value in binary,
+ * excluding leading zeros. For example:
+ * - `0n` has a bit length of 0 (it has no bits).
+ * - `1n` (binary `1`) has a bit length of 1.
+ * - `255n` (binary `11111111`) has a bit length of 8.
+ * - `-255n` (absolute value `255`, binary `11111111`) also has a bit length of 8.
+ *
+ * The function handles both positive and negative numbers. For negative inputs, the bit length is calculated
+ * based on the absolute value of the number. Zero has a bit length of 0.
+ *
+ * @param {bigint} v - The input BigInt.
+ * @returns {bigint} The bit length of the input BigInt.
+ *
+ * @remark
+ * The function uses the `log2` function to calculate the position of the most significant bit (MSB)
+ * and adds `1n` to account for the MSB itself. For negative numbers, the absolute value is used.
+ */
+export declare const bitLength: (v: bigint) => bigint;
+/**
+ * Generates a bitmask with the specified number of bits set to 1.
+ *
+ * @param {bigint} len - The number of bits to set in the mask. Must be a non-negative integer.
+ * @returns {bigint} A bigint representing the bitmask, where the least significant `len` bits are 1.
+ *
+ * @example
+ *
+ * ```js
+ * const result = mask(3n) // 7n
+ * ```
+ */
+export declare const mask: (len: bigint) => bigint;
+export declare const maxLength = 1048576n;
+export declare const max: bigint;
+/**
+ * Calculates the partial factorial `b!/a!`.
+ *
+ * @param {bigint} a - The starting bigint value.
+ * @returns {Unary} A function that takes `b` and computes `b!/a!`.
+ */
+export declare const partialFactorial: (a: bigint) => Unary;
+/**
+ * Calculates the factorial of a `bigint`.
+ *
+ * @param {bigint} b - The bigint value.
+ * @returns {bigint} The factorial of the input.
+ */
+export declare const factorial: Unary;
+/**
+ * Calculates the number of combinations for a list of `bigint` values.
+ *
+ * @param {readonly bigint[]} k - A list of bigint values.
+ * @returns {bigint} The number of combinations.
+ */
+export declare const combination: (...k: readonly bigint[]) => bigint;
+/**
+ * TODO: It should be combined with `number`.
+ *
+ * @type {Reduce}
+ */
+export declare const xor: Reduce;
+/** @type {Reduce} */
+export declare const divUp: Reduce;
+/** @type {Reduce} */
+export declare const roundUp: Reduce;
+/**
+ * Converts a bit count to a byte count, rounding up — divides by `8`.
+ *
+ * Domain: non-negative inputs (bit/byte counts). On negative inputs `divUp`
+ * truncates toward zero rather than flooring toward −∞, so the rounding
+ * direction is only meaningful for `v >= 0n`.
+ *
+ * @type {Unary}
+ */
+export declare const divUp8: Unary;
+/**
+ * Rounds a bit count up to the nearest whole byte — the nearest multiple of `8`.
+ *
+ * Domain: non-negative inputs (bit/byte counts). See `divUp8` for the
+ * truncate-vs-floor caveat on negative values.
+ *
+ * @type {Unary}
+ */
+export declare const roundUp8: Unary;