functionalscript
Version:
FunctionalScript is a purely functional subset of JavaScript
188 lines (187 loc) • 6.22 kB
TypeScript
import type { Fold, Reduce as OpReduce } from "../function/operator/module.f.ts";
import { type List, type Thunk } from "../list/module.f.ts";
import { type Nominal } from "../nominal/module.f.ts";
/**
* A vector of bits represented as a signed `bigint`.
*/
export type Vec = Nominal<'bit_vec', '1a23a4336197e6158b6936cad34e90d146cd84b9b40ff7ab75a17c6d79e31d89', bigint>;
/**
* An empty vector of bits.
*/
export declare const empty: Vec;
/**
* Calculates the length of the given vector of bits.
*/
export declare const length: (v: Vec) => bigint;
/**
* Creates a vector of bits of the given `len` and the provided unsigned integer.
*
* @example
*
* ```js
* const vec4 = vec(4n)
* const v0 = vec4(5n) // -0xDn = -0b1101
* const v1 = vec4(0x5FEn) // 0xEn = 0b1110
* ```
*/
export declare const vec: (len: bigint) => (ui: bigint) => Vec;
/**
* Creates an 8-bit vector from an unsigned integer.
*/
export declare const vec8: (ui: bigint) => Vec;
/**
* Returns the unsigned integer representation of the vector by clearing the stop bit.
*
* @example
*
* ```js
* const vector = vec(8n)(0x5n) // -0x85n
* const result = uint(vector); // result is 0x5n
* ```
*/
export declare const uint: (v: Vec) => bigint;
/**
* Structure describing the unpacked view of a vector.
*/
export type Unpacked = {
readonly length: bigint;
readonly uint: bigint;
};
/**
* Extracts the logical length and unsigned integer from the vector.
*/
export declare const unpack: (v: Vec) => Unpacked;
/**
* Packs an unpacked representation back into a vector.
*/
export declare const pack: ({ length, uint }: Unpacked) => Vec;
export type Reduce = OpReduce<Vec>;
/**
* Represents operations for handling bit vectors with a specific bit order.
*
* https://en.wikipedia.org/wiki/Bit_numbering
*/
export type BitOrder = {
/**
* Retrieves the first unsigned integer of the specified length from the given vector.
*
* @param len - The number of bits to read from the start of the vector.
* @returns A function that takes a vector and returns the extracted unsigned integer.
*
* @example
*
* ```js
* const vector = vec(8n)(0xF5n)
*
* const resultL0 = lsb.front(4n)(vector) // 5n
* const resultL1 = lsb.front(16n)(vector) // 0xF5n
*
* const resultM0 = msb.front(4n)(vector) // 0xFn
* const resultM1 = msb.front(16n)(vector) // 0xF500n
* ```
*/
readonly front: (len: bigint) => (v: Vec) => bigint;
/**
* Removes a specified number of bits from the start of the given vector.
*
* @param len - The number of bits to remove from the vector.
* @returns A function that takes a vector and returns the remaining vector.
*
* @example
*
* ```js
* const v = vec(16n)(0x3456n)
*
* const rL0 = lsb.removeFront(4n)(v) // uint(rL0) is 0x345n
* const rL1 = lsb.removeFront(24n)(v) // rL1 === empty
*
* const rM0 = msb.removeFront(4n)(v) // uint(rM0) is 0x456n
* const rM1 = msb.removeFront(24n)(v) // rM1 === empty
* ```
*/
readonly removeFront: (len: bigint) => (v: Vec) => Vec;
/**
* Removes a specified number of bits from the start of the vector and returns
* the removed bits and the remaining vector.
*
* @param len - The number of bits to remove from the vector.
* @returns A function that takes a vector and returns
* a tuple containing the removed bits as an unsigned integer and the remaining vector.
*
* @example
*
* ```js
* const vector = vec(8n)(0xF5n)
*
* const [uL0, rL0] = lsb.popFront(4n)(vector) // [5n, uint(rL0) is 0xFn]
* const [uL1, rL1] = lsb.popFront(16n)(vector) // [0xF5n, rL1 === empty]
*
* const [uM0, rM0] = msb.popFront(4n)(vector) // [0xFn, uint(rM0) is 0x5n]
* const [uM1, rM1] = msb.popFront(16n)(vector) // [0xF500n, rM1 === empty]
* ```
*/
readonly popFront: (len: bigint) => (v: Vec) => readonly [bigint, Vec];
/**
* Concatenates two vectors.
*
* @returns A function that takes a second vector and returns the concatenated vector.
*
* @example
*
* ```js
* const u8 = vec(8n)
* const a = u8(0x45n)
* const b = u8(0x89n)
*
* const abL = lsb.concat(a)(b) // uint(abL) is 0x8945n
* const abM = msb.concat(a)(b) // uint(abM) is 0x4589n
* ```
*/
readonly concat: Reduce;
/**
* Computes the bitwise exclusive OR of two vectors after normalizing their lengths.
*
* @returns A function that takes a second vector and returns the XOR result.
*/
readonly xor: Reduce;
};
/**
* Implements operations for handling vectors in a least-significant-bit (LSb) first order.
*
* https://en.wikipedia.org/wiki/Bit_numbering#LSb_0_bit_numbering
*
* Usually associated with Little-Endian (LE) byte order.
*/
export declare const lsb: BitOrder;
/**
* Implements operations for handling vectors in a most-significant-bit (MSb) first order.
*
* https://en.wikipedia.org/wiki/Bit_numbering#MSb_0_bit_numbering
*
* Usually associated with Big-Endian (BE) byte order.
*/
export declare const msb: BitOrder;
/**
* Converts a list of unsigned 8-bit integers to a bit vector using the provided bit order.
*
* @param bo The bit order for the conversion
* @param list The list of unsigned 8-bit integers to be converted.
* @returns The resulting vector based on the provided bit order.
*/
export declare const u8ListToVec: (bo: BitOrder) => (list: List<number>) => Vec;
/**
* Converts a bit vector to a list of unsigned 8-bit integers based on the provided bit order.
*
* @param bitOrder The bit order for the conversion.
* @param v The vector to be converted.
* @returns A thunk that produces a list of unsigned 8-bit integers.
*/
export declare const u8List: ({ popFront }: BitOrder) => (v: Vec) => Thunk<number>;
/**
* Concatenates a list of vectors using the provided bit order.
*/
export declare const listToVec: ({ concat }: BitOrder) => (list: List<Vec>) => Vec;
/**
* Repeats a vector to create a padded block of the desired length.
*/
export declare const repeat: Fold<bigint, Vec>;