functionalscript 0.0.570 → 0.0.572

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.0.570",
+  "version": "0.0.572",
   "description": "FunctionalScript is a functional subset of JavaScript",
   "scripts": {
     "tsc": "tsc",

package/types/bigint/README.md

@@ -0,0 +1,35 @@
+# BigInt
+
+Bun has a `bigint` size limitation. It's `1_048_575` bits (`1024 ** 2`) or `131_072` Bytes.
+
+## Benchmarks
+
+### bitLen vs toString(2).length (2024/11/25)
+
+|Framework|bitLen            |toString(2).length|
+|---------|------------------|------------------|
+|Bun      |1.781681          |2.079615          |
+|Deno 1   |0.710344          |1.917003          |
+|Deno 2   |0.986602          |2.286932          |
+|Node 16  |1.521150          |2.330505          |
+|Node 18  |1.393006          |2.312573          |
+|Node 20  |1.055315          |2.320039          |
+|Node 22  |0.983075          |2.336697          |
+|Node 23  |0.699960          |1.872965          |
+
+`bitLen` wins.
+
+### Minus vs Not
+
+|Framework|minus `-`         |not `~`           |
+|---------|------------------|------------------|
+|Bun      |86.269967         | 80.372970        |
+|Deno 1   |18.754810         | 59.498217        |
+|Deno 2   |17.262486         | 57.157273        |
+|Node 16  |70.350582         |121.023162        |
+|Node 18  |61.039463         | 99.369215        |
+|Node 20  |16.908695         | 63.335552        |
+|Node 22  |19.546644         | 59.034978        |
+|Node 23  |18.246697         | 58.825815        |
+
+`-` wins.

package/types/bigint/module.f.cjs

@@ -44,21 +44,41 @@ const scalar_mul = ({ 0: _0, add }) => a => n => {
     }
 }
 
-const bit_len = (/** @type {bigint} */v) => {
-    if (v < 0n) { v = -v }
-    if (v === 0n) { return 0n }
-    let result = 1n
+/**
+ * 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 {bigint} v - The input BigInt.
+ * @returns {bigint} 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.
+ */
+const log2 = 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
     }
-    while (i !== 0n) {
+    // 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) {
@@ -69,7 +89,33 @@ const bit_len = (/** @type {bigint} */v) => {
     return result
 }
 
-const log2 = (/** @type {bigint} */v) => v <= 0n ? -1n : bit_len(v) - 1n
+/**
+ * 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 {bigint} v - The input BigInt.
+ * @returns {bigint} 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.
+ */
+const bitLength = v => {
+    if (v <= 0n) {
+        if (v === 0n) { return 0n }
+        v = -v
+    }
+    return log2(v) + 1n
+}
 
 module.exports = {
     /** @readonly */
@@ -87,5 +133,5 @@ module.exports = {
     /** @readonly */
     log2,
     /** @readonly */
-    bit_len,
+    bitLength,
 }

package/types/bigint/test.f.cjs

@@ -1,4 +1,4 @@
-const { sum, abs, serialize, log2, bit_len } = require('./module.f.cjs')
+const { sum, abs, serialize, log2, bitLength } = require('./module.f.cjs')
 
 module.exports = {
     sum: () => {
@@ -75,40 +75,62 @@ module.exports = {
             const v = 1_048_575n
             const result = log2(1n << v)
             if (result !== v) { throw result }
-        }
+        },
     ],
-    bit_len: {
+    toString2: () => {
+        // max for Bun (131_072 Bytes)
+        const v = 1_048_575n
+        const result = (1n << v).toString(2).length - 1
+        if (result !== 1_048_575) { throw result }
+    },
+    minus: () => {
+        let i = 0n
+        while (i < 1_048_575n) {
+            const s = -i
+            if (i !== -s) { throw [i, s] }
+            i += 1n
+        }
+    },
+    not: () => {
+        let i = 0n
+        while (i < 1_048_575n) {
+            const s = ~i
+            if (i !== ~s) { throw [i, s] }
+            i += 1n
+        }
+    },
+    bitLen: {
         0: () => {
-            const s = bit_len(0n)
+            const s = bitLength(0n)
             if (s !== 0n) { throw s }
         },
         m: () => {
             let i = 0n
             while (i < 10_000n) {
-                const s = bit_len(1n << i)
+                const s = bitLength(1n << i)
                 if (s !== i + 1n) { throw [s, i] }
                 i += 1n
             }
         },
         big: () => {
-            const s = bit_len(1n << 1_000_000n)
+            const s = bitLength(1n << 1_000_000n)
             if (s !== 1_000_001n) { throw s }
         },
         neg: [
             () => {
-                const s = bit_len(-1n)
+                const s = bitLength(-1n)
                 if (s !== 1n) { throw s }
             },
             () => {
-                const s = bit_len(-2n)
+                const s = bitLength(-2n)
                 if (s !== 2n) { throw s }
             },
             () => {
-                const s = bit_len(-3n)
+                const s = bitLength(-3n)
                 if (s !== 2n) { throw s }
             },
             () => {
-                const s = bit_len(-4n)
+                const s = bitLength(-4n)
                 if (s !== 3n) { throw s }
             },
         ]