functionalscript/types/bigint/module.f.d.ts

FunctionalScript is a purely functional subset of JavaScript

/**
 * 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 m = min(3n)(13n) // 3n
 * const c = combination([3n, 2n, 1n]) // 60n
 * ```
 */
import { type Sign } from '../function/compare/module.f.ts';
import type * as Operator from '../function/operator/module.f.ts';
import { type List } from '../list/module.f.ts';
/**
 * Type representing a unary operation on `bigint`.
 */
export type Unary = Operator.Unary<bigint, bigint>;
/**
 * Type representing a reduction operation on `bigint` values.
 */
export type Reduce = Operator.Reduce<bigint>;
/**
 * Adds two `bigint` values.
 *
 * @param a - The first bigint value.
 * @returns A function that takes the second bigint value and returns the sum.
 */
export declare const addition: Reduce;
/**
 * 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 declare const sum: (input: List<bigint>) => bigint;
/**
 * Multiplies two `bigint` values.
 *
 * @param a - The first bigint value.
 * @returns A function that takes the second bigint value and returns the product.
 */
export declare const multiple: Reduce;
/**
 * 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 declare const product: (input: List<bigint>) => bigint;
/**
 * Calculates the absolute value of a `bigint`.
 *
 * @param a - The bigint value.
 * @returns The absolute value of the input bigint.
 */
export declare const abs: Unary;
/**
 * Determines the sign of a `bigint`.
 * @param a - The bigint value.
 * @returns `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 a - The bigint value.
 * @returns 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 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 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 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 declare const bitLength: (v: bigint) => bigint;
/**
 * 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 declare const mask: (len: bigint) => bigint;
/**
 * Returns the smaller of two `bigint` values.
 *
 * @param a - The first bigint.
 * @returns A function that takes the second bigint and returns the smaller value.
 */
export declare const min: (a: bigint) => (b: bigint) => bigint;
/**
 * Returns the larger of two `bigint` values.
 *
 * @param a - The first bigint.
 * @returns A function that takes the second bigint and returns the larger value.
 */
export declare const max: (a: bigint) => (b: bigint) => bigint;
/**
 * Calculates the partial factorial `b!/a!`.
 *
 * @param a - The starting bigint value.
 * @returns A function that takes `b` and computes `b!/a!`.
 */
export declare const partialFactorial: (a: bigint) => (b: bigint) => bigint;
/**
 * Calculates the factorial of a `bigint`.
 *
 * @param b - The bigint value.
 * @returns The factorial of the input.
 */
export declare const factorial: (b: bigint) => bigint;
/**
 * Calculates the number of combinations for a list of `bigint` values.
 *
 * @param k - A list of bigint values.
 * @returns The number of combinations.
 */
export declare const combination: (...k: readonly bigint[]) => bigint;