functionalscript 0.43.0 → 0.44.0

package/fjs/types/bigint/module.f.js

@@ -1,251 +0,0 @@
-/**
- * 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 { cmp } from '../function/compare/module.f.js';
-import {} from '../list/module.f.js';
-import { fold } from '../../common/monoid/module.f.js';
-/**
- * Adds two `bigint` values.
- *
- * @param a - The first bigint value.
- * @returns A function that takes the second bigint value and returns the sum.
- */
-export const addition = a => b => a + b;
-/**
- * Calculates the sum of a list of `bigint` values.
- *
- * @param input - A list of bigint values.
- * @returns The sum of all values in the list.
- */
-export const sum = fold({ identity: 0n, operation: addition });
-/**
- * Multiplies two `bigint` values.
- *
- * @param a - The first bigint value.
- * @returns A function that takes the second bigint value and returns the product.
- */
-export const multiple = a => b => a * b;
-/**
- * Calculates the product of a list of `bigint` values.
- *
- * @param input - A list of bigint values.
- * @returns The product of all values in the list.
- */
-export const product = fold({ identity: 1n, operation: multiple });
-/**
- * Calculates the absolute value of a `bigint`.
- *
- * @param a - The bigint value.
- * @returns The absolute value of the input bigint.
- */
-export const abs = a => a >= 0 ? a : -a;
-/**
- * Determines the sign of a `bigint`.
- * @param a - The bigint value.
- * @returns `1` if positive, `-1` if negative, and `0` if zero.
- */
-export const sign = (a) => cmp(a)(0n);
-/**
- * Serializes a `bigint` to a string representation.
- *
- * @param a - The bigint value.
- * @returns A string representation of the bigint (e.g., '123n').
- */
-export const serialize = (a) => `${a}n`;
-const { isFinite } = Number;
-const { log2: mathLog2 } = Math;
-/**
- * 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 v - The input BigInt.
- * @returns 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 const log2 = (v) => {
-    if (v <= 0n) {
-        return -1n;
-    }
-    //
-    // 1. Fast Doubling.
-    //
-    let result = -1n;
-    // `bigints` higher than 2**1023 may lead to `Inf` during conversion to `number`.
-    // For example: `Number((1n << 1024n) - (1n << 970n)) === Inf`.
-    let i = 0x400n;
-    while (true) {
-        const n = v >> i;
-        if (n === 0n) {
-            // overshot
-            break;
-        }
-        v = n;
-        result += i;
-        i <<= 1n;
-    }
-    //
-    // 2. Binary Search.
-    //
-    // 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 1023 before we divide it by 2.
-    while (i !== 0x400n) {
-        i >>= 1n;
-        const n = v >> i;
-        if (n !== 0n) {
-            result += i;
-            v = n;
-        }
-    }
-    //
-    // 3. Remainder Phase.
-    //
-    // We know that `v` is less than `1n << 1024` so we can calculate a remainder using
-    // `Math.log2`.
-    const nl = mathLog2(Number(v));
-    if (isFinite(nl)) {
-        const rem = BigInt(nl | 0);
-        // (v >> rem) is either `0` or `1`, and it's used as a correction for
-        // Math.log2 rounding.
-        return result + rem + (v >> rem);
-    }
-    else {
-        // nl is Inf, it means log2(v) === 0x3FF and we add +1 to compensate for initial
-        // `result = -1n`.
-        return result + 0x400n;
-    }
-};
-/**
- * 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 v - The input BigInt.
- * @returns 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 const bitLength = (v) => log2(abs(v)) + 1n;
-/**
- * Generates a bitmask with the specified number of bits set to 1.
- *
- * @param len - The number of bits to set in the mask. Must be a non-negative integer.
- * @returns A bigint representing the bitmask, where the least significant `len` bits are 1.
- *
- * @example
- *
- * ```js
- * const result = mask(3n) // 7n
- * ```
- */
-export const mask = (len) => {
-    // we compute this way to avoid overflowing in Bun when len === maxLength.
-    const r = len & 1n;
-    const h = len >> 1n;
-    const x = (((1n << h) - 1n) << r) | r;
-    return (x << h) | x;
-};
-export const maxLength = 0x100000n;
-// max + 1n // bun throws an error
-export const max = mask(maxLength);
-/**
- * Calculates the partial factorial `b!/a!`.
- *
- * @param a - The starting bigint value.
- * @returns A function that takes `b` and computes `b!/a!`.
- */
-export const partialFactorial = (a) => (b) => {
-    let result = b;
-    while (true) {
-        --b;
-        if (b <= a) {
-            return result;
-        }
-        result *= b;
-    }
-};
-/**
- * Calculates the factorial of a `bigint`.
- *
- * @param b - The bigint value.
- * @returns The factorial of the input.
- */
-export const factorial = partialFactorial(1n);
-/**
- * Calculates the number of combinations for a list of `bigint` values.
- *
- * @param k - A list of bigint values.
- * @returns The number of combinations.
- */
-export const combination = (...k) => {
-    let s = 0n;
-    let m = 1n;
-    let p = 1n;
-    for (let i of k) {
-        s += i;
-        if (i >= m) {
-            [i, m] = [m, i];
-        }
-        p *= factorial(i);
-    }
-    return partialFactorial(m)(s) / p;
-};
-export const xor = a => b => a ^ b;
-export const divUp = (b) => {
-    const m = b - 1n;
-    return v => (v + m) / b;
-};
-export const roundUp = (b) => {
-    const d = divUp(b);
-    return v => d(v) * b;
-};
-/**
- * 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`.
- */
-export const divUp8 = divUp(8n);
-/**
- * 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.
- */
-export const roundUp8 = roundUp(8n);

package/fjs/types/bigint/proof.f.d.ts

@@ -1,37 +0,0 @@
-export declare const clz32Log2: (v: bigint) => bigint;
-export declare const proof: {
-    example: () => void;
-    benchmark: () => {
-        big: {
-            [k: string]: () => void;
-        };
-        small: {
-            [k: string]: () => void;
-        };
-    };
-    mask: () => void;
-    sum: () => void;
-    abs: (() => void)[];
-    serialize: (() => void)[];
-    log2: (() => void)[];
-    toString2: () => void;
-    minus: () => void;
-    not: () => void;
-    bitLen: {
-        0: () => void;
-        m: () => void;
-        big: () => void;
-        neg: (() => void)[];
-    };
-    factorial: () => void;
-    combination: () => void;
-    combination50x50: () => void;
-    combination3: () => void;
-    divUp: () => void;
-    roundUp: () => void;
-    divUp8: () => void;
-    roundUp8: () => void;
-    xor: () => void;
-    multiple: () => void;
-    product: () => void;
-};

package/fjs/types/bigint/proof.f.js

@@ -1,400 +0,0 @@
-import { sum, abs, serialize, log2, bitLength, mask, combination, factorial, xor, multiple, product, divUp, roundUp, divUp8, roundUp8 } from './module.f.js';
-import { assert, assertEq } from '../../asserts/module.f.js';
-import { min } from '../function/compare/module.f.js';
-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;
-};
-const strBinLog2 = (v) => BigInt(v.toString(2).length) - 1n;
-const strHexLog2 = (v) => {
-    const len = (BigInt(v.toString(16).length) - 1n) << 2n;
-    return len + 31n - BigInt(Math.clz32(Number(v >> len)));
-};
-const str32Log2 = (v) => {
-    const len = (BigInt(v.toString(32).length) - 1n) * 5n;
-    return len + 31n - BigInt(Math.clz32(Number(v >> len)));
-};
-export const clz32Log2 = (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)));
-};
-const m1023log2 = (v) => {
-    if (v <= 0n) {
-        return -1n;
-    }
-    //
-    // 1. Fast Doubling.
-    //
-    let result = -1n;
-    // `bigints` higher than 2**1023 may lead to `Inf` during conversion to `number`.
-    // For example: `Number((1n << 1024n) - (1n << 970n)) === Inf`.
-    let i = 1023n;
-    while (true) {
-        const n = v >> i;
-        if (n === 0n) {
-            // overshot
-            break;
-        }
-        v = n;
-        result += i;
-        i <<= 1n;
-    }
-    //
-    // 2. Binary Search.
-    //
-    // 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 1023 before we divide it by 2.
-    while (i !== 1023n) {
-        i >>= 1n;
-        const n = v >> i;
-        if (n !== 0n) {
-            result += i;
-            v = n;
-        }
-    }
-    //
-    // 3. Remainder Phase.
-    //
-    // We know that `v` is less than `1n << 1023` so we can calculate a remainder using
-    // `Math.log2`.
-    const rem = BigInt(Math.log2(Number(v)) | 0);
-    // (v >> rem) is either `0` or `1`, and it's used as a correction for
-    // Math.log2 rounding.
-    return result + rem + (v >> rem);
-};
-const benchmark = f => () => {
-    let e = 1048575n;
-    let c = 1n << e;
-    for (let i = 0n; i < 1_100; ++i) {
-        {
-            const x = f(c);
-            assertEq(x, e);
-        }
-        {
-            const x = f(c - 1n);
-            assertEq(x, e - 1n, [e, x]);
-        }
-        c >>= 1n;
-        --e;
-    }
-};
-const benchmarkSmall = f => () => {
-    let e = 2000n;
-    let c = 1n << e;
-    do {
-        {
-            const x = f(c);
-            assertEq(x, e, [e, x]);
-        }
-        for (let j = 1n; j < min(c >> 1n)(1000n); ++j) {
-            const x = f(c - j);
-            assertEq(x, e - 1n, [j, e, x]);
-        }
-        c >>= 1n;
-        --e;
-    } while (c !== 0n);
-};
-export const proof = {
-    example: () => {
-        const total = sum([1n, 2n, 3n]); // 6n
-        assertEq(total, 6n);
-        const absoluteValue = abs(-42n); // 42n
-        assertEq(absoluteValue, 42n);
-        const logValue = log2(8n); // 3n
-        assertEq(logValue, 3n);
-        const bitCount = bitLength(255n); // 8n
-        assertEq(bitCount, 8n);
-        const bitmask = mask(5n); // 31n
-        assertEq(bitmask, 31n, benchmark);
-        const m = min(3n)(13n); // 3n
-        assertEq(m, 3n);
-        const c = combination(3n, 2n, 1n); // 60n
-        assertEq(c, 60n);
-    },
-    benchmark: () => {
-        const list = {
-            // strBinLog2,
-            // strHexLog2,
-            str32Log2,
-            // oldLog2,
-            // clz32Log2,
-            // m1023log2,
-            log2,
-        };
-        const transform = (b) => Object.fromEntries(Object.entries(list).map(([k, f]) => [k, b(f)]));
-        return {
-            big: transform(benchmark),
-            small: transform(benchmarkSmall),
-        };
-    },
-    mask: () => {
-        const result = mask(3n); // 7n
-        assertEq(result, 7n);
-    },
-    sum: () => {
-        const result = sum([2n, 3n, 4n, 5n]);
-        assertEq(result, 14n);
-    },
-    abs: [
-        () => {
-            const result = abs(10n);
-            assertEq(result, 10n);
-        },
-        () => {
-            const result = abs(-10n);
-            assertEq(result, 10n);
-        }
-    ],
-    serialize: [
-        () => {
-            const result = serialize(0n);
-            assertEq(result, '0n');
-        },
-        () => {
-            const result = serialize(123456789012345678901234567890n);
-            assertEq(result, '123456789012345678901234567890n');
-        },
-        () => {
-            const result = serialize(-55555n);
-            assertEq(result, '-55555n');
-        },
-    ],
-    log2: [
-        () => {
-            const result = log2(-3n);
-            assertEq(result, -1n);
-        },
-        () => {
-            const result = log2(0n);
-            assertEq(result, -1n);
-        },
-        () => {
-            const result = log2(1n);
-            assertEq(result, 0n);
-        },
-        () => {
-            const result = log2(2n);
-            assertEq(result, 1n);
-        },
-        () => {
-            const result = log2(3n);
-            assertEq(result, 1n);
-        },
-        () => {
-            const result = log2(4n);
-            assertEq(result, 2n);
-        },
-        () => {
-            const result = log2(7n);
-            assertEq(result, 2n);
-        },
-        () => {
-            const result = log2(8n);
-            assertEq(result, 3n);
-        },
-        () => {
-            const result = log2(15n);
-            assertEq(result, 3n);
-        },
-        () => {
-            const result = log2(16n);
-            assertEq(result, 4n);
-        },
-        () => {
-            // max for Bun (131_072 Bytes)
-            const v = 1048575n;
-            const result = log2(1n << v);
-            assertEq(result, v);
-        },
-        () => {
-            const v = 0x18945n;
-            const result = log2(v);
-            assertEq(result, 16n);
-        }
-    ],
-    toString2: () => {
-        // max for Bun (131_072 Bytes)
-        const v = 1048575n;
-        const result = (1n << v).toString(2).length - 1;
-        assertEq(result, 1_048_575);
-    },
-    minus: () => {
-        let i = 0n;
-        while (i < 1048575n) {
-            const s = -i;
-            assertEq(i, -s, [i, s]);
-            i += 1n;
-        }
-    },
-    not: () => {
-        let i = 0n;
-        while (i < 1048575n) {
-            const s = ~i;
-            assertEq(i, ~s, [i, s]);
-            i += 1n;
-        }
-    },
-    bitLen: {
-        0: () => {
-            const s = bitLength(0n);
-            assertEq(s, 0n);
-        },
-        m: () => {
-            let i = 0n;
-            while (i < 10000n) {
-                const s = bitLength(1n << i);
-                assertEq(s, i + 1n, [s, i]);
-                i += 1n;
-            }
-        },
-        big: () => {
-            const s = bitLength(1n << 1000000n);
-            assertEq(s, 1000001n);
-        },
-        neg: [
-            () => {
-                const s = bitLength(-1n);
-                assertEq(s, 1n);
-            },
-            () => {
-                const s = bitLength(-2n);
-                assertEq(s, 2n);
-            },
-            () => {
-                const s = bitLength(-3n);
-                assertEq(s, 2n);
-            },
-            () => {
-                const s = bitLength(-4n);
-                assertEq(s, 3n);
-            },
-        ]
-    },
-    factorial: () => {
-        {
-            const r = factorial(3n);
-            assertEq(r, 6n);
-        }
-        {
-            const r = factorial(5n);
-            assertEq(r, 120n);
-        }
-    },
-    combination: () => {
-        const r = combination(2n, 3n);
-        assert(r == 120n / (2n * 6n), r);
-    },
-    combination50x50: () => {
-        {
-            const r = combination(1n, 1n);
-            assertEq(r, 2n);
-        }
-        {
-            const r = combination(2n, 2n);
-            assertEq(r, 6n);
-        }
-        {
-            const r = combination(3n, 3n);
-            assertEq(r, 20n);
-        }
-        {
-            const r = combination(4n, 4n);
-            assertEq(r, 70n);
-        }
-    },
-    combination3: () => {
-        const r = combination(2n, 3n, 4n, 2n);
-        // 2! * 3! * 4! * 2! : 2! * 2! * 3!
-        // 2+3+4+2 = 5*6*7*8*9*10*11
-        // e = 5 * 6 * 7 * 8 * 9 * 10 * 11 / (2n * 2n * 6n) =
-        // e = 5     * 7 * 2 * 9 * 10 * 11 = 69300
-        assertEq(r, 69300n);
-    },
-    divUp: () => {
-        assertEq(divUp(8n)(8n), 1n);
-        assertEq(divUp(8n)(15n), 2n);
-    },
-    roundUp: () => {
-        assertEq(roundUp(8n)(8n), 8n);
-        assertEq(roundUp(8n)(15n), 16n);
-        assertEq(roundUp(8n)(3n), 8n);
-    },
-    divUp8: () => {
-        assertEq(divUp8(0n), 0n);
-        assertEq(divUp8(1n), 1n);
-        assertEq(divUp8(8n), 1n);
-        assertEq(divUp8(8n), 1n);
-        assertEq(divUp8(9n), 2n);
-        assertEq(divUp8(15n), 2n);
-    },
-    roundUp8: () => {
-        assertEq(roundUp8(0n), 0n);
-        assertEq(roundUp8(1n), 8n);
-        assertEq(roundUp8(3n), 8n);
-        assertEq(roundUp8(8n), 8n);
-        assertEq(roundUp8(8n), 8n);
-        assertEq(roundUp8(9n), 16n);
-        assertEq(roundUp8(15n), 16n);
-    },
-    xor: () => {
-        assertEq(xor(5n)(3n), 6n);
-        assertEq(xor(0n)(15n), 15n);
-        assertEq(xor(0xffn)(0xf0n), 0x0fn);
-    },
-    multiple: () => {
-        assertEq(multiple(3n)(4n), 12n);
-        assertEq(multiple(0n)(100n), 0n);
-    },
-    product: () => {
-        assertEq(product([1n, 2n, 3n, 4n]), 24n);
-        assertEq(product([5n, 6n]), 30n);
-    },
-};