functionalscript 0.2.5 → 0.2.6

package/CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 0.2.6
+
+- Refactoring of a vector of bits [PR #328](https://github.com/functionalscript/functionalscript/pull/328)
+
 ## 0.2.5
 
 - new [crypto/] directory [PR #327](https://github.com/functionalscript/functionalscript/pull/327).

package/html/README.md

@@ -4,7 +4,8 @@
 |--------------------------------------------|-------------------------------------------------|
 |`<br>`                                      |`['br']`                                         |
 |`<img src="https://example.com/image.jpg">` |`['img',{src:'https://example.com/image.jpg'}]`  |
-|`<a href="https://example.com/">Example</a>`|`['a',{href:'https://example.com/'},['Example']]`|
+|`<a href="https://example.com/">Example</a>`|`['a',{href:'https://example.com/'}, 'Example']` |
+|`<ul><li>Apple</li><li>Tomato</li></ul>`    |`['ul',['li','Apple'],['li','Tomato']]`          |
 
 ## Example
 
@@ -20,12 +21,12 @@
 ```
 
 ```js
-['html', [
-    ['head', [
-        ['title', ['Page']]
-    ]]
-    ['body', [
-        ['a', { href: 'https://example.com/' }, ['Example']]
-    ]]
-]]
+['html',
+    ['head',
+        ['title', 'Page']
+    ]
+    ['body',
+        ['a', { href: 'https://example.com/' }, 'Example']
+    ]
+]
 ```

package/issues/README.md

@@ -33,6 +33,9 @@
 24. [ ] create `./module.mjs` that supports the same behavior like current NaNVM Rust implementation:
     - [ ] run `node ./module.mjs input.f.mjs output.f.mjs`
     - [ ] run `deno ./module.mjs input.f.mjs output.f.mjs`
+25. [ ] Switch to Deno an `.ts`?
+    1. Deno TypeScript and Microsoft TypeScript are different https://bsky.app/profile/macwright.com/post/3lbrwioa5zs27
+    2. One day we may switch back to `.js` extension if [Type Annotation Proposal](https://github.com/tc39/proposal-type-annotations) is included into ECMAScript. BTW, we should only use JS with type annotations instead of full TypeScript.
 
 ## Language Specification
 

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@functionalscript/functionalscript",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "license": "AGPL-3.0-only",
   "exports": {
     "./com/cpp": "./out/com/cpp/module.f.mjs",

package/out/types/bit_vec/module.f.d.mts

@@ -10,62 +10,148 @@ export const empty: 1n;
 /**
  * Calculates the length of the given vector of bits.
  */
-export const len: (v: bigint) => bigint;
+export const length: (v: bigint) => bigint;
 /**
- * Extract an unsigned integer of the given `uintLen` from the given vector.
+ * Creates a vector of bits of the given `len` and the given unsigned integer.
+ *
+ * @type {(len: bigint) => (ui: bigint) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const vec4 = vec(4n)
+ * const v0 = vec4(5n)     // 0x15n
+ * const v1 = vec4(0x5FEn) // 0x1En
+ * ```
+ */
+export const vec: (len: bigint) => (ui: bigint) => Vec;
+/**
+ * Returns the unsigned integer of the given vector by removing a stop bit.
+ *
+ * @type {(len: Vec) => bigint}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0x5n) // 0x105n
+ * const result = uint(vector); // result is 0x5n
+ * ```
+ */
+export const uint: (len: Vec) => bigint;
+/**
+ * Extract the least significant unsigned integer from the given vector.
  *
  * @type {(uintLen: bigint) => (v: Vec) => bigint}
  *
  * @example
  *
  * ```js
- * const vector = 0b110101n;
- * const extract3Bits = uint(3n);
- * const result = extract3Bits(vector); // result is 0b101n (5n)
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const result = uintLsb(4n)(vector); // result is 5n
+ * const result2 = uintLsb(16n)(vector); // result2 is 0xF5n
  * ```
  */
-export const uint: (uintLen: bigint) => (v: Vec) => bigint;
+export const uintLsb: (uintLen: bigint) => (v: Vec) => bigint;
 /**
- * Creates a vector of bits of the given `vecLen` from the given unsigned integer.
+ * Removes the first `len` least significant bits from the given vector.
  *
- * @type {(vecLen: bigint) => (ui: bigint) => Vec}
+ * @type {(len: bigint) => (v: Vec) => Vec}
  *
  * @example
  *
  * ```js
- * const createVector = vec(4n);
- * const vector = createVector(5n); // vector is 0b10101n
+ * const v = vec(16n)(0x3456n) // 0x13456n
+ * const r = removeLsb(4n)(v) // 0x1345n
+ * const r2 = removeLsb(24n)(v) // 0x1n
  * ```
  */
-export const vec: (vecLen: bigint) => (ui: bigint) => Vec;
+export const removeLsb: (len: bigint) => (v: Vec) => Vec;
 /**
- * Appends the vector `b` to the back of the vector `a`.
+ * Extracts the least significant unsigned integer and removes it from the vector.
  *
- * @type {(a: Vec) => (b: Vec) => Vec}
+ * @type {(len: bigint) => (v: Vec) => [bigint, Vec]}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const [result, rest] = popUintLsb(4n)(vector); // result is 5n, rest is 0x1Fn
+ * const [result2, rest2] = popUintLsb(16n)(vector); // result2 is 0xF5n, rest2 is 1n
+ * ```
+ */
+export const popUintLsb: (len: bigint) => (v: Vec) => [bigint, Vec];
+/**
+ * Extract the most significant unsigned integer of the given `len` from the given vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => bigint}
  *
  * @example
  *
  * ```js
- * const vec8 = vec(8n)
- * const a = vec8(0x345n)
- * const b = vec8(0x789n)
- * const ab = appendBack(a)(b) // 0x18945n
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const result = uintMsb(4n)(vector); // result is 0xFn
+ * const result2 = uintMsb(16n)(vector); // result2 is 0xF500n
  * ```
  */
-export const appendBack: (a: Vec) => (b: Vec) => Vec;
+export const uintMsb: (len: bigint) => (v: Vec) => bigint;
 /**
- * Removes the first `len` bits from the given vector.
+ * Removes the first `len` most significant bits from the given vector.
  *
  * @type {(len: bigint) => (v: Vec) => Vec}
  *
  * @example
  *
  * ```js
- * const v = vec(17n)(0x12345n) // v = 0x32345n
- * const r = removeFront(9n)(v) // r = 0x191n
+ * const v = vec(16n)(0x3456n) // 0x13456n
+ * const r = removeMsb(4n)(v) // 0x1456n
+ * const r2 = removeMsb(24n)(v) // 0x1n
+ * ```
+ */
+export const removeMsb: (len: bigint) => (v: Vec) => Vec;
+/**
+ * Extracts the most significant unsigned integer and removes it from the vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => [bigint, Vec]}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const [result, rest] = popUintMsb(4n)(vector); // [0xFn, 0x15n]
+ * const [result2, rest2] = popUintMsb(16n)(vector); // [0xF500n, 1n]
+ * ```
+ */
+export const popUintMsb: (len: bigint) => (v: Vec) => [bigint, Vec];
+/**
+ * Concat the given vectors of bits. The first vector is the least significant.
+ *
+ * @type {(a: Vec) => (b: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const u8 = vec(8n)
+ * const a = u8(0x45n) // 0x145n
+ * const b = u8(0x89n) // 0x189n
+ * const ab = concatLsb(a)(b) // 0x18945n
+ * ```
+ */
+export const concatLsb: (a: Vec) => (b: Vec) => Vec;
+/**
+ * Concat the given vectors of bits. The first vector is the most significant.
+ *
+ * @type {(b: Vec) => (a: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const u8 = vec(8n)
+ * const a = u8(0x45n) // 0x145n
+ * const b = u8(0x89n) // 0x189n
+ * const ab = concatMsb(a)(b) // 0x14589n
  * ```
  */
-export const removeFront: (len: bigint) => (v: Vec) => Vec;
+export const concatMsb: (b: Vec) => (a: Vec) => Vec;
 /**
  * A vector of bits represented as a `bigint`.
  */

package/out/types/bit_vec/module.f.mjs

@@ -1,5 +1,6 @@
 // @ts-self-types="./module.f.d.mts"
 import { log2 } from '../bigint/module.f.mjs';
+import { flip } from '../function/module.f.mjs';
 /**
  * A vector of bits represented as a `bigint`.
  *
@@ -12,72 +13,182 @@ export const empty = 1n;
 /**
  * Calculates the length of the given vector of bits.
  */
-export const len = log2;
+export const length = log2;
 /**
- * Extract an unsigned integer of the given `uintLen` from the given vector.
+ * Creates a vector of bits of the given `len` and the given unsigned integer.
  *
- * @type {(uintLen: bigint) => (v: Vec) => bigint}
+ * @type {(len: bigint) => (ui: bigint) => Vec}
  *
  * @example
  *
  * ```js
- * const vector = 0b110101n;
- * const extract3Bits = uint(3n);
- * const result = extract3Bits(vector); // result is 0b101n (5n)
+ * const vec4 = vec(4n)
+ * const v0 = vec4(5n)     // 0x15n
+ * const v1 = vec4(0x5FEn) // 0x1En
  * ```
  */
-export const uint = uintLen => {
-    const mask = (1n << uintLen) - 1n;
-    return data => data & mask;
+export const vec = len => {
+    if (len <= 0n) {
+        return () => empty;
+    }
+    const stop = 1n << len;
+    const mask = stop - 1n;
+    return data => stop | (data & mask);
 };
+/** @type {(len: bigint) => bigint} */
+const mask = len => (1n << len) - 1n;
 /**
- * Creates a vector of bits of the given `vecLen` from the given unsigned integer.
+ * Returns the unsigned integer of the given vector by removing a stop bit.
  *
- * @type {(vecLen: bigint) => (ui: bigint) => Vec}
+ * @type {(len: Vec) => bigint}
  *
  * @example
  *
  * ```js
- * const createVector = vec(4n);
- * const vector = createVector(5n); // vector is 0b10101n
+ * const vector = vec(8n)(0x5n) // 0x105n
+ * const result = uint(vector); // result is 0x5n
  * ```
  */
-export const vec = vecLen => {
-    const stop = 1n << vecLen;
-    const mask = stop - 1n;
-    return data => (data & mask) | stop;
-};
+export const uint = v => v ^ (1n << length(v));
 /**
- * Appends the vector `b` to the back of the vector `a`.
+ * Extract the least significant unsigned integer from the given vector.
  *
- * @type {(a: Vec) => (b: Vec) => Vec}
+ * @type {(uintLen: bigint) => (v: Vec) => bigint}
  *
  * @example
  *
  * ```js
- * const vec8 = vec(8n)
- * const a = vec8(0x345n)
- * const b = vec8(0x789n)
- * const ab = appendBack(a)(b) // 0x18945n
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const result = uintLsb(4n)(vector); // result is 5n
+ * const result2 = uintLsb(16n)(vector); // result2 is 0xF5n
  * ```
  */
-export const appendBack = a => {
-    const aLen = len(a);
-    return b => a | (b << aLen);
+export const uintLsb = len => {
+    const m = mask(len);
+    return v => {
+        const result = v & m;
+        return result === v ? uint(v) : result;
+    };
 };
 /**
- * Removes the first `len` bits from the given vector.
+ * Removes the first `len` least significant bits from the given vector.
  *
  * @type {(len: bigint) => (v: Vec) => Vec}
  *
  * @example
  *
  * ```js
- * const v = vec(17n)(0x12345n) // v = 0x32345n
- * const r = removeFront(9n)(v) // r = 0x191n
+ * const v = vec(16n)(0x3456n) // 0x13456n
+ * const r = removeLsb(4n)(v) // 0x1345n
+ * const r2 = removeLsb(24n)(v) // 0x1n
  * ```
  */
-export const removeFront = len => v => {
+export const removeLsb = len => v => {
     const r = v >> len;
     return r === 0n ? empty : r;
 };
+/**
+ * Extracts the least significant unsigned integer and removes it from the vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => [bigint, Vec]}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const [result, rest] = popUintLsb(4n)(vector); // result is 5n, rest is 0x1Fn
+ * const [result2, rest2] = popUintLsb(16n)(vector); // result2 is 0xF5n, rest2 is 1n
+ * ```
+ */
+export const popUintLsb = len => {
+    const m = mask(len);
+    return v => {
+        const result = v & m;
+        return result === v ? [uint(v), empty] : [result, v >> len];
+    };
+};
+/**
+ * Extract the most significant unsigned integer of the given `len` from the given vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => bigint}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const result = uintMsb(4n)(vector); // result is 0xFn
+ * const result2 = uintMsb(16n)(vector); // result2 is 0xF500n
+ * ```
+ */
+export const uintMsb = len => {
+    const m = mask(len);
+    return v => (v >> (length(v) - len)) & m;
+};
+/**
+ * Removes the first `len` most significant bits from the given vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const v = vec(16n)(0x3456n) // 0x13456n
+ * const r = removeMsb(4n)(v) // 0x1456n
+ * const r2 = removeMsb(24n)(v) // 0x1n
+ * ```
+ */
+export const removeMsb = len => v => vec(length(v) - len)(v);
+/**
+ * Extracts the most significant unsigned integer and removes it from the vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => [bigint, Vec]}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const [result, rest] = popUintMsb(4n)(vector); // [0xFn, 0x15n]
+ * const [result2, rest2] = popUintMsb(16n)(vector); // [0xF500n, 1n]
+ * ```
+ */
+export const popUintMsb = len => {
+    const m = mask(len);
+    return v => {
+        const d = length(v) - len;
+        return [(v >> d) & m, vec(d)(v)];
+    };
+};
+/**
+ * Concat the given vectors of bits. The first vector is the least significant.
+ *
+ * @type {(a: Vec) => (b: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const u8 = vec(8n)
+ * const a = u8(0x45n) // 0x145n
+ * const b = u8(0x89n) // 0x189n
+ * const ab = concatLsb(a)(b) // 0x18945n
+ * ```
+ */
+export const concatLsb = a => {
+    const aLen = length(a);
+    const m = mask(aLen);
+    return b => (b << aLen) | (a & m);
+};
+/**
+ * Concat the given vectors of bits. The first vector is the most significant.
+ *
+ * @type {(b: Vec) => (a: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const u8 = vec(8n)
+ * const a = u8(0x45n) // 0x145n
+ * const b = u8(0x89n) // 0x189n
+ * const ab = concatMsb(a)(b) // 0x14589n
+ * ```
+ */
+export const concatMsb = flip(concatLsb);

package/out/types/bit_vec/test.f.d.mts

@@ -1,9 +1,23 @@
 declare namespace _default {
-    function uintExample(): void;
-    function vecExample(): void;
-    function length(): void;
-    function bitset(): void;
-    function appendBack(): void;
-    function removeBack(): void;
+    export namespace examples {
+        function vec(): void;
+        function uint(): void;
+        function uintLsb(): void;
+        function uintMsb(): void;
+        function popUintLsb(): void;
+        function popUintMsb(): void;
+        function concatLsb(): void;
+        function concatMsb(): void;
+        function removeLsb(): void;
+        function removeMsb(): void;
+    }
+    export function uintLsb_1(): void;
+    export { uintLsb_1 as uintLsb };
+    export function uintSmall(): void;
+    export function vecExample(): void;
+    export function length(): void;
+    export function bitset(): void;
+    export function appendBack(): void;
+    export function removeBack(): void;
 }
 export default _default;

package/out/types/bit_vec/test.f.mjs

@@ -1,13 +1,163 @@
-import { empty, len, appendBack, vec, uint, removeFront } from './module.f.mjs';
+import { empty, vec, length, concatLsb, uintLsb, uintMsb, removeLsb, concatMsb, removeMsb, uint, popUintLsb, popUintMsb } from './module.f.mjs';
 export default {
-    uintExample: () => {
-        const vector = 53n;
-        const extract3Bits = uint(3n);
+    examples: {
+        vec: () => {
+            const vec4 = vec(4n);
+            const v0 = vec4(5n); // 0x15n
+            if (v0 !== 0x15n) {
+                throw v0;
+            }
+            const v1 = vec4(0x5fen); // 0x1En
+            if (v1 !== 0x1en) {
+                throw v1;
+            }
+        },
+        uint: () => {
+            const vector = vec(8n)(0x5n); // 0x105n
+            if (vector !== 0x105n) {
+                throw vector;
+            }
+            const result = uint(vector); // result is 0x5n
+            if (result !== 0x5n) {
+                throw result;
+            }
+        },
+        uintLsb: () => {
+            const vector = vec(8n)(0xf5n); // 0x1F5n
+            if (vector !== 0x1f5n) {
+                throw vector;
+            }
+            const result = uintLsb(4n)(vector); // result is 5n
+            if (result !== 5n) {
+                throw result;
+            }
+            const result2 = uintLsb(16n)(vector); // result2 is 0xF5n
+            if (result2 !== 0xf5n) {
+                throw result2;
+            }
+        },
+        uintMsb: () => {
+            const vector = vec(8n)(0xf5n); // 0x1F5n
+            if (vector !== 0x1f5n) {
+                throw vector;
+            }
+            const result = uintMsb(4n)(vector); // result is 0xFn
+            if (result !== 0xfn) {
+                throw result;
+            }
+            const result2 = uintMsb(16n)(vector); // result2 is 0xF500n
+            if (result2 !== 0xf500n) {
+                throw result2;
+            }
+        },
+        popUintLsb: () => {
+            const vector = vec(8n)(0xf5n); // 0x1F5n
+            const [result, rest] = popUintLsb(4n)(vector); // result is 5n, rest is 0x1Fn
+            if (result !== 5n) {
+                throw result;
+            }
+            if (rest !== 0x1fn) {
+                throw rest;
+            }
+            const [result2, rest2] = popUintLsb(16n)(vector); // result2 is 0xF5n, rest2 is 1n
+            if (result2 !== 0xf5n) {
+                throw result2;
+            }
+            if (rest2 !== 1n) {
+                throw rest2;
+            }
+        },
+        popUintMsb: () => {
+            const vector = vec(8n)(0xf5n); // 0x1F5n
+            const [result, rest] = popUintMsb(4n)(vector); // [0xFn, 0x15n]
+            if (result !== 0xfn) {
+                throw result;
+            }
+            if (rest !== 0x15n) {
+                throw rest;
+            }
+            const [result2, rest2] = popUintMsb(16n)(vector); // [0xF500n, 1n]
+            if (result2 !== 0xf500n) {
+                throw result2;
+            }
+            if (rest2 !== 1n) {
+                throw rest2;
+            }
+        },
+        concatLsb: () => {
+            const u8 = vec(8n);
+            const a = u8(0x45n); // 0x145n
+            if (a !== 0x145n) {
+                throw a;
+            }
+            const b = u8(0x89n); // 0x189n
+            if (b !== 0x189n) {
+                throw b;
+            }
+            const ab = concatLsb(a)(b); // 0x18945n
+            if (ab !== 0x18945n) {
+                throw ab;
+            }
+        },
+        concatMsb: () => {
+            const u8 = vec(8n);
+            const a = u8(0x45n); // 0x145n
+            if (a !== 0x145n) {
+                throw a;
+            }
+            const b = u8(0x89n); // 0x189n
+            if (b !== 0x189n) {
+                throw b;
+            }
+            const ab = concatMsb(a)(b); // 0x14589n
+            if (ab !== 0x14589n) {
+                throw ab;
+            }
+        },
+        removeLsb: () => {
+            const v = vec(16n)(0x3456n); // 0x13456n
+            if (v !== 0x13456n) {
+                throw v;
+            }
+            const r = removeLsb(4n)(v); // 0x1345n
+            if (r !== 0x1345n) {
+                throw r;
+            }
+            const r2 = removeLsb(24n)(v); // 0x1n
+            if (r2 !== 0x1n) {
+                throw r2;
+            }
+        },
+        removeMsb: () => {
+            const v = vec(16n)(0x3456n); // 0x13456n
+            if (v !== 0x13456n) {
+                throw v;
+            }
+            const r = removeMsb(4n)(v); // 0x1456n
+            if (r !== 0x1456n) {
+                throw r;
+            }
+            const r2 = removeMsb(24n)(v); // 0x1n
+            if (r2 !== 0x1n) {
+                throw r2;
+            }
+        }
+    },
+    uintLsb: () => {
+        const vector = 117n;
+        const extract3Bits = uintLsb(3n);
         const result = extract3Bits(vector); // result is 0b101n (5n)
         if (result !== 5n) {
             throw result;
         }
     },
+    uintSmall: () => {
+        const vector = 3n;
+        const extract3Bits = uintLsb(3n)(vector);
+        if (extract3Bits !== 1n) {
+            throw extract3Bits;
+        }
+    },
     vecExample: () => {
         const createVector = vec(4n);
         const vector = createVector(5n); // vector is 0b10101n
@@ -16,7 +166,7 @@ export default {
         }
     },
     length: () => {
-        const i = len(empty);
+        const i = length(empty);
         if (i !== 0n) {
             throw i;
         }
@@ -26,10 +176,10 @@ export default {
         if (v !== 0x1fen) {
             throw v;
         }
-        if (len(v) !== 8n) {
+        if (length(v) !== 8n) {
             throw 'len';
         }
-        const u = uint(8n)(v);
+        const u = uintLsb(8n)(v);
         if (u !== 0xfen) {
             throw v;
         }
@@ -38,11 +188,11 @@ export default {
         const vec8 = vec(8n);
         const a = vec8(0x345n);
         const b = vec8(0x789n);
-        const ab = appendBack(a)(b);
+        const ab = concatLsb(a)(b);
         if (ab !== 0x18945n) {
             throw ab;
         }
-        const s = len(ab);
+        const s = length(ab);
         if (s !== 16n) {
             throw `appendBack: ${s}`;
         }
@@ -52,7 +202,7 @@ export default {
         if (v !== 0x32345n) {
             throw v.toString(16);
         }
-        const r = removeFront(9n)(v);
+        const r = removeLsb(9n)(v);
         if (r !== 0x191n) {
             throw r.toString(16);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "type": "module",
   "description": "FunctionalScript is a functional subset of JavaScript",
   "scripts": {

package/types/bit_vec/README.md

@@ -0,0 +1,18 @@
+# Vector of Bits
+
+A **vector of bits** is represented as a `bigint`. The value is always positive, and an **empty vector** is denoted by `1n`.
+
+## Key Characteristics
+
+- The **most significant bit** with a value of `1` is called the **`stop bit`**.
+- The **`stop bit`** marks the boundary of the vector.
+- The **`length`** of a vector represents the number of meaningful bits (excluding the **`stop bit`**).
+- An **empty vector** is represented by `1n`, with the implicit **`stop bit`** as the only bit.
+
+## Example
+
+| Vector        | Binary Representation | `length` | Vector Items |
+|---------------|-----------------------|----------|--------------|
+| `0b1001n`     | `0b1001n`             | 3        | `001`        |
+| `0x1FF`       | `0b111111111`         | 8        | `11111111`   |
+| `1n` (empty)  | `0b1`                 | 0        | (none)       |

package/types/bit_vec/module.f.mjs

@@ -1,5 +1,6 @@
 // @ts-self-types="./module.f.d.mts"
 import { log2 } from '../bigint/module.f.mjs'
+import { flip } from '../function/module.f.mjs'
 
 /**
  * A vector of bits represented as a `bigint`.
@@ -15,76 +16,191 @@ export const empty = 1n
 /**
  * Calculates the length of the given vector of bits.
  */
-export const len = log2
+export const length = log2
 
 /**
- * Extract an unsigned integer of the given `uintLen` from the given vector.
+ * Creates a vector of bits of the given `len` and the given unsigned integer.
  *
- * @type {(uintLen: bigint) => (v: Vec) => bigint}
+ * @type {(len: bigint) => (ui: bigint) => Vec}
  *
  * @example
  *
  * ```js
- * const vector = 0b110101n;
- * const extract3Bits = uint(3n);
- * const result = extract3Bits(vector); // result is 0b101n (5n)
+ * const vec4 = vec(4n)
+ * const v0 = vec4(5n)     // 0x15n
+ * const v1 = vec4(0x5FEn) // 0x1En
  * ```
  */
-export const uint = uintLen => {
-    const mask = (1n << uintLen) - 1n
-    return data => data & mask
+export const vec = len => {
+    if (len <= 0n) { return () => empty }
+    const stop = 1n << len
+    const mask = stop - 1n
+    return data => stop | (data & mask)
 }
 
+/** @type {(len: bigint) => bigint} */
+const mask = len => (1n << len) - 1n
+
 /**
- * Creates a vector of bits of the given `vecLen` from the given unsigned integer.
+ * Returns the unsigned integer of the given vector by removing a stop bit.
  *
- * @type {(vecLen: bigint) => (ui: bigint) => Vec}
+ * @type {(len: Vec) => bigint}
  *
  * @example
  *
  * ```js
- * const createVector = vec(4n);
- * const vector = createVector(5n); // vector is 0b10101n
+ * const vector = vec(8n)(0x5n) // 0x105n
+ * const result = uint(vector); // result is 0x5n
  * ```
  */
-export const vec = vecLen => {
-    const stop = 1n << vecLen
-    const mask = stop - 1n
-    return data => (data & mask) | stop
-}
+export const uint = v => v ^ (1n << length(v))
 
 /**
- * Appends the vector `b` to the back of the vector `a`.
+ * Extract the least significant unsigned integer from the given vector.
  *
- * @type {(a: Vec) => (b: Vec) => Vec}
+ * @type {(uintLen: bigint) => (v: Vec) => bigint}
  *
  * @example
  *
  * ```js
- * const vec8 = vec(8n)
- * const a = vec8(0x345n)
- * const b = vec8(0x789n)
- * const ab = appendBack(a)(b) // 0x18945n
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const result = uintLsb(4n)(vector); // result is 5n
+ * const result2 = uintLsb(16n)(vector); // result2 is 0xF5n
  * ```
  */
-export const appendBack = a => {
-    const aLen = len(a)
-    return b => a | (b << aLen)
+export const uintLsb = len => {
+    const m = mask(len)
+    return v => {
+        const result = v & m
+        return result === v ? uint(v) : result
+    }
 }
 
 /**
- * Removes the first `len` bits from the given vector.
+ * Removes the first `len` least significant bits from the given vector.
  *
  * @type {(len: bigint) => (v: Vec) => Vec}
  *
  * @example
  *
  * ```js
- * const v = vec(17n)(0x12345n) // v = 0x32345n
- * const r = removeFront(9n)(v) // r = 0x191n
+ * const v = vec(16n)(0x3456n) // 0x13456n
+ * const r = removeLsb(4n)(v) // 0x1345n
+ * const r2 = removeLsb(24n)(v) // 0x1n
  * ```
  */
-export const removeFront = len => v => {
+export const removeLsb = len => v => {
     const r = v >> len
     return r === 0n ? empty : r
 }
+
+/**
+ * Extracts the least significant unsigned integer and removes it from the vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => [bigint, Vec]}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const [result, rest] = popUintLsb(4n)(vector); // result is 5n, rest is 0x1Fn
+ * const [result2, rest2] = popUintLsb(16n)(vector); // result2 is 0xF5n, rest2 is 1n
+ * ```
+ */
+export const popUintLsb = len => {
+    const m = mask(len)
+    return v => {
+        const result = v & m
+        return result === v ? [uint(v), empty] : [result, v >> len]
+    }
+}
+
+/**
+ * Extract the most significant unsigned integer of the given `len` from the given vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => bigint}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const result = uintMsb(4n)(vector); // result is 0xFn
+ * const result2 = uintMsb(16n)(vector); // result2 is 0xF500n
+ * ```
+ */
+export const uintMsb = len => {
+    const m = mask(len)
+    return v => (v >> (length(v) - len)) & m
+}
+
+/**
+ * Removes the first `len` most significant bits from the given vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const v = vec(16n)(0x3456n) // 0x13456n
+ * const r = removeMsb(4n)(v) // 0x1456n
+ * const r2 = removeMsb(24n)(v) // 0x1n
+ * ```
+ */
+export const removeMsb = len => v => vec(length(v) - len)(v)
+
+/**
+ * Extracts the most significant unsigned integer and removes it from the vector.
+ *
+ * @type {(len: bigint) => (v: Vec) => [bigint, Vec]}
+ *
+ * @example
+ *
+ * ```js
+ * const vector = vec(8n)(0xF5n) // 0x1F5n
+ * const [result, rest] = popUintMsb(4n)(vector); // [0xFn, 0x15n]
+ * const [result2, rest2] = popUintMsb(16n)(vector); // [0xF500n, 1n]
+ * ```
+ */
+export const popUintMsb = len => {
+    const m = mask(len)
+    return v => {
+        const d = length(v) - len
+        return [(v >> d) & m, vec(d)(v)]
+    }
+}
+
+/**
+ * Concat the given vectors of bits. The first vector is the least significant.
+ *
+ * @type {(a: Vec) => (b: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const u8 = vec(8n)
+ * const a = u8(0x45n) // 0x145n
+ * const b = u8(0x89n) // 0x189n
+ * const ab = concatLsb(a)(b) // 0x18945n
+ * ```
+ */
+export const concatLsb = a => {
+    const aLen = length(a)
+    const m = mask(aLen)
+    return b => (b << aLen) | (a & m)
+}
+
+/**
+ * Concat the given vectors of bits. The first vector is the most significant.
+ *
+ * @type {(b: Vec) => (a: Vec) => Vec}
+ *
+ * @example
+ *
+ * ```js
+ * const u8 = vec(8n)
+ * const a = u8(0x45n) // 0x145n
+ * const b = u8(0x89n) // 0x189n
+ * const ab = concatMsb(a)(b) // 0x14589n
+ * ```
+ */
+export const concatMsb = flip(concatLsb)

package/types/bit_vec/test.f.mjs

@@ -1,41 +1,129 @@
-import { empty, len, appendBack, vec, uint, removeFront } from './module.f.mjs'
+import { empty, vec, length, concatLsb, uintLsb, uintMsb, removeLsb, concatMsb, removeMsb, uint, popUintLsb, popUintMsb } from './module.f.mjs'
 
 export default {
-    uintExample: () => {
-        const vector = 0b110101n;
-        const extract3Bits = uint(3n);
-        const result = extract3Bits(vector); // result is 0b101n (5n)
+    examples: {
+        vec: () => {
+            const vec4 = vec(4n)
+            const v0 = vec4(5n)     // 0x15n
+            if (v0 !== 0x15n) { throw v0 }
+            const v1 = vec4(0x5FEn) // 0x1En
+            if (v1 !== 0x1En) { throw v1 }
+        },
+        uint: () => {
+            const vector = vec(8n)(0x5n) // 0x105n
+            if (vector !== 0x105n) { throw vector }
+            const result = uint(vector); // result is 0x5n
+            if (result !== 0x5n) { throw result }
+        },
+        uintLsb: () => {
+            const vector = vec(8n)(0xF5n) // 0x1F5n
+            if (vector !== 0x1F5n) { throw vector }
+            const result = uintLsb(4n)(vector); // result is 5n
+            if (result !== 5n) { throw result }
+            const result2 = uintLsb(16n)(vector); // result2 is 0xF5n
+            if (result2 !== 0xF5n) { throw result2 }
+        },
+        uintMsb: () => {
+            const vector = vec(8n)(0xF5n) // 0x1F5n
+            if (vector !== 0x1F5n) { throw vector }
+            const result = uintMsb(4n)(vector); // result is 0xFn
+            if (result !== 0xFn) { throw result }
+            const result2 = uintMsb(16n)(vector); // result2 is 0xF500n
+            if (result2 !== 0xF500n) { throw result2 }
+        },
+        popUintLsb: () => {
+            const vector = vec(8n)(0xF5n) // 0x1F5n
+            const [result, rest] = popUintLsb(4n)(vector); // result is 5n, rest is 0x1Fn
+            if (result !== 5n) { throw result }
+            if (rest !== 0x1Fn) { throw rest }
+            const [result2, rest2] = popUintLsb(16n)(vector); // result2 is 0xF5n, rest2 is 1n
+            if (result2 !== 0xF5n) { throw result2 }
+            if (rest2 !== 1n) { throw rest2 }
+        },
+        popUintMsb: () => {
+            const vector = vec(8n)(0xF5n) // 0x1F5n
+            const [result, rest] = popUintMsb(4n)(vector); // [0xFn, 0x15n]
+            if (result !== 0xFn) { throw result }
+            if (rest !== 0x15n) { throw rest }
+            const [result2, rest2] = popUintMsb(16n)(vector); // [0xF500n, 1n]
+            if (result2 !== 0xF500n) { throw result2 }
+            if (rest2 !== 1n) { throw rest2 }
+        },
+        concatLsb: () => {
+            const u8 = vec(8n)
+            const a = u8(0x45n) // 0x145n
+            if (a !== 0x145n) { throw a }
+            const b = u8(0x89n) // 0x189n
+            if (b !== 0x189n) { throw b }
+            const ab = concatLsb(a)(b) // 0x18945n
+            if (ab !== 0x18945n) { throw ab }
+        },
+        concatMsb: () => {
+            const u8 = vec(8n)
+            const a = u8(0x45n) // 0x145n
+            if (a !== 0x145n) { throw a }
+            const b = u8(0x89n) // 0x189n
+            if (b !== 0x189n) { throw b }
+            const ab = concatMsb(a)(b) // 0x14589n
+            if (ab !== 0x14589n) { throw ab }
+        },
+        removeLsb: () => {
+            const v = vec(16n)(0x3456n) // 0x13456n
+            if (v !== 0x13456n) { throw v }
+            const r = removeLsb(4n)(v) // 0x1345n
+            if (r !== 0x1345n) { throw r }
+            const r2 = removeLsb(24n)(v) // 0x1n
+            if (r2 !== 0x1n) { throw r2 }
+        },
+        removeMsb: () => {
+            const v = vec(16n)(0x3456n) // 0x13456n
+            if (v !== 0x13456n) { throw v }
+            const r = removeMsb(4n)(v) // 0x1456n
+            if (r !== 0x1456n) { throw r }
+            const r2 = removeMsb(24n)(v) // 0x1n
+            if (r2 !== 0x1n) { throw r2 }
+        }
+    },
+    uintLsb: () => {
+        const vector = 0b1110101n
+        const extract3Bits = uintLsb(3n)
+        const result = extract3Bits(vector) // result is 0b101n (5n)
         if (result !== 0b101n) { throw result }
     },
+    uintSmall: () => {
+        const vector = 0b11n
+        const extract3Bits = uintLsb(3n)(vector)
+        if (extract3Bits !== 0b1n) { throw extract3Bits }
+    },
     vecExample: () => {
-        const createVector = vec(4n);
-        const vector = createVector(5n); // vector is 0b10101n
+        const createVector = vec(4n)
+        const vector = createVector(5n) // vector is 0b10101n
         if (vector !== 0b10101n) { throw vector }
     },
     length: () => {
-        const i = len(empty)
+        const i = length(empty)
         if (i !== 0n) { throw i}
     },
     bitset: () => {
         const v = vec(8n)(0x5FEn)
         if (v !== 0x1FEn) { throw v }
-        if (len(v) !== 8n) { throw 'len' }
-        const u = uint(8n)(v)
+        if (length(v) !== 8n) { throw 'len' }
+        const u = uintLsb(8n)(v)
         if (u !== 0xFEn) { throw v }
     },
     appendBack: () => {
         const vec8 = vec(8n)
         const a = vec8(0x345n)
         const b = vec8(0x789n)
-        const ab = appendBack(a)(b)
+        const ab = concatLsb(a)(b)
         if (ab !== 0x18945n) { throw ab }
-        const s = len(ab)
+        const s = length(ab)
         if (s !== 16n) { throw `appendBack: ${s}` }
     },
     removeBack: () => {
         const v = vec(17n)(0x12345n)
         if (v !== 0x32345n) { throw v.toString(16) }
-        const r = removeFront(9n)(v)
+        const r = removeLsb(9n)(v)
         if (r !== 0x191n) { throw r.toString(16) }
     }
 }