functionalscript 0.8.0 → 0.8.2

package/types/bit_vec/module.f.d.ts

@@ -1,8 +1,10 @@
-import { type List, type Thunk } from '../list/module.f.ts';
+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 `bigint`.
+ * A vector of bits represented as a signed `bigint`.
  */
-export type Vec = bigint;
+export type Vec = Nominal<'bit_vec', '1a23a4336197e6158b6936cad34e90d146cd84b9b40ff7ab75a17c6d79e31d89', bigint>;
 /**
  * An empty vector of bits.
  */
@@ -10,34 +12,50 @@ export declare const empty: Vec;
 /**
  * Calculates the length of the given vector of bits.
  */
-export declare const length: (v: bigint) => bigint;
+export declare const length: (v: Vec) => bigint;
 /**
- * Creates a vector of bits of the given `len` and the given unsigned integer.
+ * Creates a vector of bits of the given `len` and the provided unsigned integer.
  *
  * @example
  *
  * ```js
  * const vec4 = vec(4n)
- * const v0 = vec4(5n)     // 0x15n = 0b1_0101
- * const v1 = vec4(0x5FEn) // 0x1En = 0b1_1110
+ * 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.
+ * Creates an 8-bit vector from an unsigned integer.
  */
-export declare const vec8: (u: bigint) => Vec;
+export declare const vec8: (ui: bigint) => Vec;
 /**
- * Returns the unsigned integer of the given vector by removing a stop bit.
+ * Returns the unsigned integer representation of the vector by clearing the stop bit.
  *
  * @example
  *
  * ```js
- * const vector = vec(8n)(0x5n) // 0x105n
+ * 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.
  *
@@ -53,13 +71,13 @@ export type BitOrder = {
      * @example
      *
      * ```js
-     * const vector = vec(8n)(0xF5n) // 0x1F5n
+     * const vector = vec(8n)(0xF5n)
      *
-     * const resultL0 = lsb.front(4n)(vector)  // resultL0 is 5n
-     * const resultL1 = lsb.front(16n)(vector) // resultL1 is 0xF5n
+     * const resultL0 = lsb.front(4n)(vector)  // 5n
+     * const resultL1 = lsb.front(16n)(vector) // 0xF5n
      *
-     * const resultM0 = msb.front(4n)(vector)  // resultM0 is 0xFn
-     * const resultM1 = msb.front(16n)(vector) // resultM1 is 0xF500n
+     * const resultM0 = msb.front(4n)(vector)  // 0xFn
+     * const resultM1 = msb.front(16n)(vector) // 0xF500n
      * ```
      */
     readonly front: (len: bigint) => (v: Vec) => bigint;
@@ -72,13 +90,13 @@ export type BitOrder = {
      * @example
      *
      * ```js
-     * const v = vec(16n)(0x3456n) // 0x13456n
+     * const v = vec(16n)(0x3456n)
      *
-     * const rL0 = lsb.removeFront(4n)(v)  // 0x1345n
-     * const rL1 = lsb.removeFront(24n)(v) // 0x1n
+     * const rL0 = lsb.removeFront(4n)(v)  // uint(rL0) is 0x345n
+     * const rL1 = lsb.removeFront(24n)(v) // rL1 === empty
      *
-     * const rM0 = msb.removeFront(4n)(v)  // 0x1456n
-     * const rM1 = msb.removeFront(24n)(v) // 0x1n
+     * 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;
@@ -90,35 +108,42 @@ export type BitOrder = {
      * @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) // 0x1F5n
+     * const vector = vec(8n)(0xF5n)
      *
-     * const [uL0, rL0] = lsb.popFront(4n)(vector)  // [5n, 0x1Fn]
-     * const [uL1, rL1] = lsb.popFront(16n)(vector) // [0xF5n, 1n]
+     * 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, 0x15n]
-     * const [uM1, rM1] = msb.popFront(16n)(vector) // [0xF500n, 1n]
+     * 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.
      *
-     * @param a - The first vector.
      * @returns A function that takes a second vector and returns the concatenated vector.
      *
      * @example
      *
      * ```js
      * const u8 = vec(8n)
-     * const a = u8(0x45n) // 0x145n
-     * const b = u8(0x89n) // 0x189n
+     * const a = u8(0x45n)
+     * const b = u8(0x89n)
      *
-     * const abL = lsb.concat(a)(b) // 0x18945n
-     * const abM = msb.concat(a)(b) // 0x14589n
+     * const abL = lsb.concat(a)(b) // uint(abL) is 0x8945n
+     * const abM = msb.concat(a)(b) // uint(abM) is 0x4589n
      * ```
      */
-    readonly concat: (a: Vec) => (b: Vec) => Vec;
+    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.
@@ -137,7 +162,7 @@ export declare const lsb: BitOrder;
  */
 export declare const msb: BitOrder;
 /**
- * Converts a list of unsigned 8-bit integers to a bit vector.
+ * 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.
@@ -152,4 +177,11 @@ export declare const u8ListToVec: (bo: BitOrder) => (list: List<number>) => Vec;
  * @returns A thunk that produces a list of unsigned 8-bit integers.
  */
 export declare const u8List: ({ popFront }: BitOrder) => (v: Vec) => Thunk<number>;
-export declare const listToVec: (bo: BitOrder) => (list: List<Vec>) => Vec;
+/**
+ * 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>;

package/types/bit_vec/module.f.js

@@ -1,61 +1,113 @@
 /**
+ * Bit vectors that normalize the most-significant bit using signed `bigint` values.
+ *
+ * A value whose top bit is already set remains positive, while other values are
+ * negated after toggling the leading bit so the stop bit is always `1`. The sign bit
+ * therefore acts as the stop bit that encodes the logical length of the vector.
+ *
  * MSb is most-significant bit first.
+ *
  * ```
  * - byte: 0x53 = 0b0101_0011
  * -                0123_4567
  * ```
+ *
  * LSb is least-significant bit first.
+ *
  * ```
  * - byte: 0x53 = 0b0101_0011
  * -                7654_3210
  * ```
+ *
  * @module
  */
-import { log2, mask } from "../bigint/module.f.js";
+import { abs, bitLength, mask, max, xor } from "../bigint/module.f.js";
 import { flip } from "../function/module.f.js";
 import { fold } from "../list/module.f.js";
+import { asBase, asNominal } from "../nominal/module.f.js";
+import { repeat as mRepeat } from "../monoid/module.f.js";
 /**
  * An empty vector of bits.
  */
-export const empty = 1n;
+export const empty = asNominal(0n);
 /**
  * Calculates the length of the given vector of bits.
  */
-export const length = log2;
+export const length = (v) => bitLength(asBase(v));
+const lazyEmpty = () => empty;
 /**
- * Creates a vector of bits of the given `len` and the given unsigned integer.
+ * Creates a vector of bits of the given `len` and the provided unsigned integer.
  *
  * @example
  *
  * ```js
  * const vec4 = vec(4n)
- * const v0 = vec4(5n)     // 0x15n = 0b1_0101
- * const v1 = vec4(0x5FEn) // 0x1En = 0b1_1110
+ * const v0 = vec4(5n)     // -0xDn = -0b1101
+ * const v1 = vec4(0x5FEn) //  0xEn =  0b1110
  * ```
  */
 export const vec = (len) => {
     if (len <= 0n) {
-        return () => empty;
+        return lazyEmpty;
     }
-    const stop = 1n << len;
-    const mask = stop - 1n;
-    return data => stop | (data & mask);
+    const m = mask(len);
+    const last = len - 1n;
+    const lastBit = 1n << last;
+    return ui => {
+        // normalize `u`
+        const u = m & abs(ui);
+        //
+        const sign = u >> last;
+        const x = sign !== 0n ? u : -(u ^ lastBit);
+        return asNominal(x);
+    };
 };
 /**
- * Creates an 8 bit vector from an unsigned integer.
+ * Creates an 8-bit vector from an unsigned integer.
  */
 export const vec8 = vec(8n);
 /**
- * Returns the unsigned integer of the given vector by removing a stop bit.
+ * Returns the unsigned integer representation of the vector by clearing the stop bit.
  *
  * @example
  *
  * ```js
- * const vector = vec(8n)(0x5n) // 0x105n
+ * const vector = vec(8n)(0x5n) // -0x85n
  * const result = uint(vector); // result is 0x5n
  * ```
  */
-export const uint = (v) => v ^ (1n << length(v));
+export const uint = (v) => {
+    const b = asBase(v);
+    if (b >= 0n) {
+        return b;
+    }
+    const u = -b;
+    const len = bitLength(u);
+    return u ^ (1n << (len - 1n));
+};
+/**
+ * Extracts the logical length and unsigned integer from the vector.
+ */
+export const unpack = (v) => ({
+    length: length(v),
+    uint: uint(v),
+});
+/**
+ * Packs an unpacked representation back into a vector.
+ */
+export const pack = ({ length, uint }) => vec(length)(uint);
+const lsbNorm = ({ length: al, uint: a }) => ({ length: bl, uint: b }) => (len) => ({ a, b });
+const msbNorm = ({ length: al, uint: a }) => ({ length: bl, uint: b }) => (len) => ({ a: a << (len - al), b: b << (len - bl) });
+/**
+ * Normalizes two vectors to the same length before applying a bigint reducer.
+ */
+const op = (norm) => (op) => ap => bp => {
+    const au = unpack(ap);
+    const bu = unpack(bp);
+    const len = max(au.length)(bu.length);
+    const { a, b } = norm(au)(bu)(len);
+    return vec(len)(op(a)(b));
+};
 /**
  * Implements operations for handling vectors in a least-significant-bit (LSb) first order.
  *
@@ -66,27 +118,25 @@ export const uint = (v) => v ^ (1n << length(v));
 export const lsb = {
     front: len => {
         const m = mask(len);
-        return v => {
-            const result = v & m;
-            return result === v ? uint(v) : result;
-        };
+        return v => uint(v) & m;
     },
     removeFront: len => v => {
-        const r = v >> len;
-        return r === 0n ? empty : r;
+        const { length, uint } = unpack(v);
+        return vec(length - len)(uint >> len);
     },
     popFront: len => {
         const m = mask(len);
         return v => {
-            const result = v & m;
-            return result === v ? [uint(v), empty] : [result, v >> len];
+            const { length, uint } = unpack(v);
+            return [uint & m, vec(length - len)(uint >> len)];
         };
     },
-    concat: a => {
-        const aLen = length(a);
-        const m = mask(aLen);
-        return b => (b << aLen) | (a & m);
+    concat: (a) => (b) => {
+        const { length: al, uint: au } = unpack(a);
+        const { length: bl, uint: bu } = unpack(b);
+        return vec(al + bl)((bu << al) | au);
     },
+    xor: op(lsbNorm)(xor)
 };
 /**
  * Implements operations for handling vectors in a most-significant-bit (MSb) first order.
@@ -98,21 +148,29 @@ export const lsb = {
 export const msb = {
     front: len => {
         const m = mask(len);
-        return v => (v >> (length(v) - len)) & m;
+        return v => {
+            const { length, uint } = unpack(v);
+            return (uint >> (length - len)) & m;
+        };
+    },
+    removeFront: len => v => {
+        const { length, uint } = unpack(v);
+        return vec(length - len)(uint);
     },
-    removeFront: len => v => vec(length(v) - len)(v),
     popFront: len => {
         const m = mask(len);
         return v => {
-            const d = length(v) - len;
-            return [(v >> d) & m, vec(d)(v)];
+            const { length, uint } = unpack(v);
+            const d = length - len;
+            return [(uint >> d) & m, vec(d)(uint)];
         };
     },
     concat: flip(lsb.concat),
+    xor: op(msbNorm)(xor)
 };
 const appendU8 = ({ concat }) => (u8) => (a) => concat(a)(vec8(BigInt(u8)));
 /**
- * Converts a list of unsigned 8-bit integers to a bit vector.
+ * 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.
@@ -136,4 +194,11 @@ export const u8List = ({ popFront }) => {
     };
     return f;
 };
-export const listToVec = (bo) => fold(bo.concat)(empty);
+/**
+ * Concatenates a list of vectors using the provided bit order.
+ */
+export const listToVec = ({ concat }) => fold(flip(concat))(empty);
+/**
+ * Repeats a vector to create a padded block of the desired length.
+ */
+export const repeat = mRepeat({ identity: empty, operation: lsb.concat });

package/types/bit_vec/test.f.d.ts

@@ -30,5 +30,12 @@ declare const _default: {
     bitset: () => void;
     appendBack: () => void;
     removeBack: () => void;
+    uint: (() => void)[];
+    vec: (() => void)[];
+    both: () => (() => void)[];
+    concat2: () => void;
+    lsbXor: () => void;
+    msbXor: () => void;
+    repeat: () => void;
 };
 export default _default;