redscript-mc 3.0.1 → 3.0.2

package/redscript-docs/docs/en/stdlib/bigint.md

@@ -0,0 +1,316 @@
+# Bigint
+
+> Auto-generated from `src/stdlib/bigint.mcrs` — do not edit manually.
+
+## API
+
+- [bigint_base](#bigint-base)
+- [bigint_zero](#bigint-zero)
+- [bigint_copy](#bigint-copy)
+- [bigint_cmp](#bigint-cmp)
+- [bigint_add](#bigint-add)
+- [bigint_sub](#bigint-sub)
+- [bigint_mul_small](#bigint-mul-small)
+- [bigint_div_small](#bigint-div-small)
+- [bigint_mod_small](#bigint-mod-small)
+- [bigint_mul](#bigint-mul)
+- [bigint_sq](#bigint-sq)
+- [bigint_div](#bigint-div)
+
+---
+
+## `bigint_base` <Badge type="info" text="v1.0.0" />
+
+Return the bigint base (10000 = base-10000, each chunk holds 4 decimal digits).
+
+```redscript
+fn bigint_base(): int
+```
+
+**Returns:** 10000
+
+---
+
+## `bigint_zero` <Badge type="info" text="v1.0.0" />
+
+Set all chunks of a bigint array to zero.
+
+```redscript
+fn bigint_zero(arr: int[], len: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `arr` | BigInt array (most-significant chunk at index 0) |
+| `len` | Number of chunks |
+
+**Returns:** void — arr[0..len-1] set to 0
+
+**Example**
+
+```redscript
+bigint_zero(result, 4)  // zero out a 4-chunk bigint
+```
+
+---
+
+## `bigint_copy` <Badge type="info" text="v1.0.0" />
+
+Copy a bigint from src into dst.
+
+```redscript
+fn bigint_copy(src: int[], dst: int[], len: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `src` | Source bigint array |
+| `dst` | Destination bigint array (must have length >= len) |
+| `len` | Number of chunks to copy |
+
+**Returns:** void — dst[0..len-1] = src[0..len-1]
+
+---
+
+## `bigint_cmp` <Badge type="info" text="v1.0.0" />
+
+Compare two bigints of equal length.
+
+```redscript
+fn bigint_cmp(a: int[], b: int[], len: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | First bigint (most-significant chunk at index 0) |
+| `b` | Second bigint |
+| `len` | Number of chunks (must be equal for both) |
+
+**Returns:** 1 if a > b, -1 if a < b, 0 if equal
+
+**Example**
+
+```redscript
+let cmp: int = bigint_cmp(a, b, 4)
+```
+
+---
+
+## `bigint_add` <Badge type="info" text="v1.0.0" />
+
+Add two bigints of equal length, writing result into a pre-allocated array.
+
+```redscript
+fn bigint_add(a: int[], b: int[], result: int[], len: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | First bigint addend |
+| `b` | Second bigint addend |
+| `result` | Output bigint array (must have length >= len, may alias a or b) |
+| `len` | Number of chunks |
+
+**Returns:** Carry out: 0 or 1 (overflow if non-zero)
+
+**Example**
+
+```redscript
+let carry: int = bigint_add(a, b, result, 4)
+```
+
+---
+
+## `bigint_sub` <Badge type="info" text="v1.0.0" />
+
+Subtract bigint b from a, writing result (assumes a >= b, no underflow check).
+
+```redscript
+fn bigint_sub(a: int[], b: int[], result: int[], len: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | Minuend bigint |
+| `b` | Subtrahend bigint (must be <= a) |
+| `result` | Output bigint array |
+| `len` | Number of chunks |
+
+**Returns:** void — result = a - b
+
+---
+
+## `bigint_mul_small` <Badge type="info" text="v1.0.0" />
+
+Multiply a bigint by a small integer (1 ≤ n ≤ 9999).
+
+```redscript
+fn bigint_mul_small(a: int[], n: int, result: int[], len: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | Bigint multiplicand |
+| `n` | Small integer multiplier (must be in [1, 9999] to avoid overflow) |
+| `result` | Output bigint array (must have length >= len) |
+| `len` | Number of chunks |
+
+**Returns:** void — result = a * n; high overflow is silently lost
+
+**Example**
+
+```redscript
+bigint_mul_small(a, 1000, result, 4)  // result = a × 1000
+```
+
+---
+
+## `bigint_div_small` <Badge type="info" text="v1.0.0" />
+
+Divide a bigint by a small integer (1 ≤ divisor ≤ 9999), returning quotient and remainder.
+
+```redscript
+fn bigint_div_small(a: int[], divisor: int, result: int[], len: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | Dividend bigint |
+| `divisor` | Small integer divisor (range [1, 9999]) |
+| `result` | Output quotient bigint array |
+| `len` | Number of chunks |
+
+**Returns:** Remainder (0..divisor-1)
+
+**Example**
+
+```redscript
+let rem: int = bigint_div_small(a, 7, result, 4)
+```
+
+---
+
+## `bigint_mod_small` <Badge type="info" text="v1.0.0" />
+
+Compute a bigint modulo a small integer without allocating a quotient array.
+
+```redscript
+fn bigint_mod_small(a: int[], divisor: int, len: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | Dividend bigint |
+| `divisor` | Small integer divisor (range [1, 9999]) |
+| `len` | Number of chunks |
+
+**Returns:** a % divisor, in [0, divisor-1]
+
+**Example**
+
+```redscript
+let mod: int = bigint_mod_small(a, 10, 4)  // last decimal digit of a
+```
+
+---
+
+## `bigint_mul` <Badge type="info" text="v1.0.0" />
+
+Multiply two bigints using schoolbook O(n²) algorithm.
+
+```redscript
+fn bigint_mul(a: int[], b: int[], result: int[], la: int, lb: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | First bigint (la chunks) |
+| `b` | Second bigint (lb chunks) |
+| `result` | Output bigint array (must have la+lb chunks, pre-zeroed) |
+| `la` | Number of chunks in a |
+| `lb` | Number of chunks in b |
+
+**Returns:** void — result = a * b; result must not alias a or b
+
+**Example**
+
+```redscript
+let result: int[] = [0, 0, 0, 0, 0, 0, 0]
+bigint_mul(a, b, result, 4, 3)
+```
+
+---
+
+## `bigint_sq` <Badge type="info" text="v1.0.0" />
+
+Square a bigint (optimized: computes upper triangle only).
+
+```redscript
+fn bigint_sq(a: int[], result: int[], len: int)
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | Bigint to square (len chunks) |
+| `result` | Output bigint array (must have len*2 chunks, pre-zeroed) |
+| `len` | Number of chunks in a |
+
+**Returns:** void — result = a * a
+
+**Example**
+
+```redscript
+let sq: int[] = [0, 0, 0, 0, 0, 0, 0, 0]
+bigint_sq(a, sq, 4)  // sq = a²
+```
+
+---
+
+## `bigint_div` <Badge type="info" text="v1.0.0" />
+
+Full arbitrary-precision integer division: a / b → quotient and remainder.
+
+```redscript
+fn bigint_div(a: int[], b: int[], quotient: int[], remainder: int[], la: int, lb: int): void
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | Dividend bigint (la chunks) |
+| `b` | Divisor bigint (lb chunks) |
+| `quotient` | Output quotient array (la chunks, pre-zeroed) |
+| `remainder` | Output remainder array (lb chunks, pre-zeroed) |
+| `la` | Number of chunks in a (must be >= lb) |
+| `lb` | Number of chunks in b |
+
+**Returns:** void — quotient = a/b, remainder = a%b; a and b must not alias outputs
+
+**Example**
+
+```redscript
+bigint_div(a, b, quotient, remainder, 4, 2)
+```
+
+---

package/redscript-docs/docs/en/stdlib/bits.md

@@ -0,0 +1,292 @@
+# Bits
+
+> Auto-generated from `src/stdlib/bits.mcrs` — do not edit manually.
+
+## API
+
+- [bit_get](#bit-get)
+- [bit_set](#bit-set)
+- [bit_clear](#bit-clear)
+- [bit_toggle](#bit-toggle)
+- [bit_shl](#bit-shl)
+- [bit_shr](#bit-shr)
+- [bit_and](#bit-and)
+- [bit_or](#bit-or)
+- [bit_xor](#bit-xor)
+- [bit_not](#bit-not)
+- [popcount](#popcount)
+
+---
+
+## `bit_get` <Badge type="info" text="v1.0.0" />
+
+Test whether bit n of x is set.
+
+```redscript
+fn bit_get(x: int, n: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Integer value to test |
+| `n` | Bit index (0 = least significant), range [0, 30] |
+
+**Returns:** 1 if bit n is set, 0 otherwise
+
+**Example**
+
+```redscript
+let b: int = bit_get(0b1010, 1)  // result: 1 (bit 1 of 10 is set)
+```
+
+---
+
+## `bit_set` <Badge type="info" text="v1.0.0" />
+
+Set bit n of x to 1 (idempotent if already set).
+
+```redscript
+fn bit_set(x: int, n: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Integer value to modify |
+| `n` | Bit index to set, range [0, 30] |
+
+**Returns:** x with bit n set to 1
+
+**Example**
+
+```redscript
+let v: int = bit_set(0b0100, 0)  // result: 0b0101 = 5
+```
+
+---
+
+## `bit_clear` <Badge type="info" text="v1.0.0" />
+
+Clear bit n of x to 0 (idempotent if already clear).
+
+```redscript
+fn bit_clear(x: int, n: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Integer value to modify |
+| `n` | Bit index to clear, range [0, 30] |
+
+**Returns:** x with bit n set to 0
+
+**Example**
+
+```redscript
+let v: int = bit_clear(0b0111, 1)  // result: 0b0101 = 5
+```
+
+---
+
+## `bit_toggle` <Badge type="info" text="v1.0.0" />
+
+Toggle bit n of x (flip 0→1 or 1→0).
+
+```redscript
+fn bit_toggle(x: int, n: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Integer value to modify |
+| `n` | Bit index to toggle, range [0, 30] |
+
+**Returns:** x with bit n flipped
+
+**Example**
+
+```redscript
+let v: int = bit_toggle(0b0101, 1)  // result: 0b0111 = 7
+```
+
+---
+
+## `bit_shl` <Badge type="info" text="v1.0.0" />
+
+Left-shift x by n bits (equivalent to x * 2^n).
+
+```redscript
+fn bit_shl(x: int, n: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Integer to shift |
+| `n` | Number of bit positions to shift left, range [0, 30] |
+
+**Returns:** x << n
+
+**Example**
+
+```redscript
+let v: int = bit_shl(1, 4)  // result: 16 (1 << 4)
+```
+
+---
+
+## `bit_shr` <Badge type="info" text="v1.0.0" />
+
+Logical right-shift x by n bits (equivalent to x / 2^n, truncating toward zero).
+
+```redscript
+fn bit_shr(x: int, n: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Integer to shift |
+| `n` | Number of bit positions to shift right, range [0, 30] |
+
+**Returns:** x >> n (logical, not arithmetic for positive values)
+
+**Example**
+
+```redscript
+let v: int = bit_shr(256, 3)  // result: 32 (256 >> 3)
+```
+
+---
+
+## `bit_and` <Badge type="info" text="v1.0.0" />
+
+Bitwise AND of two integers (all 31 non-sign bits).
+
+```redscript
+fn bit_and(a: int, b: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | First operand |
+| `b` | Second operand |
+
+**Returns:** a & b (bits set in both a and b)
+
+**Example**
+
+```redscript
+let v: int = bit_and(0b1100, 0b1010)  // result: 0b1000 = 8
+```
+
+---
+
+## `bit_or` <Badge type="info" text="v1.0.0" />
+
+Bitwise OR of two integers (all 31 non-sign bits).
+
+```redscript
+fn bit_or(a: int, b: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | First operand |
+| `b` | Second operand |
+
+**Returns:** a | b (bits set in either a or b)
+
+**Example**
+
+```redscript
+let v: int = bit_or(0b1100, 0b1010)  // result: 0b1110 = 14
+```
+
+---
+
+## `bit_xor` <Badge type="info" text="v1.0.0" />
+
+Bitwise XOR of two integers (all 31 non-sign bits).
+
+```redscript
+fn bit_xor(a: int, b: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `a` | First operand |
+| `b` | Second operand |
+
+**Returns:** a ^ b (bits set in exactly one of a or b)
+
+**Example**
+
+```redscript
+let v: int = bit_xor(0b1100, 0b1010)  // result: 0b0110 = 6
+```
+
+---
+
+## `bit_not` <Badge type="info" text="v1.0.0" />
+
+Bitwise NOT — inverts all 31 non-sign bits of x.
+
+```redscript
+fn bit_not(x: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Integer to invert |
+
+**Returns:** ~x (all 31 lower bits flipped; sign bit excluded)
+
+**Example**
+
+```redscript
+let v: int = bit_not(0)  // result: 2147483647 (all 31 bits set)
+```
+
+---
+
+## `popcount` <Badge type="info" text="v1.0.0" />
+
+Count the number of set bits in x (population count / Hamming weight).
+
+```redscript
+fn popcount(x: int): int
+```
+
+**Parameters**
+
+| Parameter | Description |
+|-----------|-------------|
+| `x` | Integer value (uses 31 lower bits; sign bit excluded) |
+
+**Returns:** Number of bits set to 1, in [0, 31]
+
+**Example**
+
+```redscript
+let n: int = popcount(255)  // result: 8 (0xFF has 8 bits set)
+```
+
+---