redscript-mc 3.0.1 → 3.0.2

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

@@ -0,0 +1,316 @@
+# Bigint
+
+> 本文档由 `src/stdlib/bigint.mcrs` 自动生成，请勿手动编辑。
+
+## 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
+```
+
+**返回：** 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)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `arr` | BigInt array (most-significant chunk at index 0) |
+| `len` | Number of chunks |
+
+**返回：** void — arr[0..len-1] set to 0
+
+**示例**
+
+```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)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `src` | Source bigint array |
+| `dst` | Destination bigint array (must have length >= len) |
+| `len` | Number of chunks to copy |
+
+**返回：** void — dst[0..len-1] = src[0..len-1]
+
+---
+
+## `bigint_cmp` <Badge type="info" text="v1.0.0" />
+
+比较两个等长大整数
+
+```redscript
+fn bigint_cmp(a: int[], b: int[], len: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个大整数（最高有效分块在索引 0） |
+| `b` | 第二个大整数 |
+| `len` | 分块数量（两者相同） |
+
+**返回：** a > b 返回 1，a < b 返回 -1，相等返回 0
+
+**示例**
+
+```redscript
+let cmp: int = bigint_cmp(a, b, 4)
+```
+
+---
+
+## `bigint_add` <Badge type="info" text="v1.0.0" />
+
+将两个等长大整数相加，结果写入预分配数组
+
+```redscript
+fn bigint_add(a: int[], b: int[], result: int[], len: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个加数大整数 |
+| `b` | 第二个加数大整数 |
+| `result` | 输出大整数数组（长度需 >= len） |
+| `len` | 分块数量 |
+
+**返回：** 进位：0 或 1（非零表示溢出）
+
+**示例**
+
+```redscript
+let carry: int = bigint_add(a, b, result, 4)
+```
+
+---
+
+## `bigint_sub` <Badge type="info" text="v1.0.0" />
+
+大整数 b 从 a 中减去，结果写入 result（要求 a >= b）
+
+```redscript
+fn bigint_sub(a: int[], b: int[], result: int[], len: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 被减数大整数 |
+| `b` | 减数大整数（必须 <= a） |
+| `result` | 输出大整数数组 |
+| `len` | 分块数量 |
+
+**返回：** void — result = a - b
+
+---
+
+## `bigint_mul_small` <Badge type="info" text="v1.0.0" />
+
+大整数乘以小整数（1 ≤ n ≤ 9999）
+
+```redscript
+fn bigint_mul_small(a: int[], n: int, result: int[], len: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 被乘数大整数 |
+| `n` | 小整数乘数（范围 [1, 9999]） |
+| `result` | 输出数组 |
+| `len` | 分块数量 |
+
+**返回：** void — result = a × n
+
+**示例**
+
+```redscript
+bigint_mul_small(a, 1000, result, 4)  // result = a × 1000
+```
+
+---
+
+## `bigint_div_small` <Badge type="info" text="v1.0.0" />
+
+大整数除以小整数，返回商和余数
+
+```redscript
+fn bigint_div_small(a: int[], divisor: int, result: int[], len: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 被除数大整数 |
+| `divisor` | 小整数除数（范围 [1, 9999]） |
+| `result` | 商输出数组 |
+| `len` | 分块数量 |
+
+**返回：** 余数（范围 0..divisor-1）
+
+**示例**
+
+```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
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | Dividend bigint |
+| `divisor` | Small integer divisor (range [1, 9999]) |
+| `len` | Number of chunks |
+
+**返回：** a % divisor, in [0, divisor-1]
+
+**示例**
+
+```redscript
+let mod: int = bigint_mod_small(a, 10, 4)  // last decimal digit of a
+```
+
+---
+
+## `bigint_mul` <Badge type="info" text="v1.0.0" />
+
+两个大整数相乘（朴素 O(n²) 学校算法）
+
+```redscript
+fn bigint_mul(a: int[], b: int[], result: int[], la: int, lb: int)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个大整数（la 个分块） |
+| `b` | 第二个大整数（lb 个分块） |
+| `result` | 输出数组（需 la+lb 个分块，预置为 0） |
+| `la` | a 的分块数 |
+| `lb` | b 的分块数 |
+
+**返回：** void — result = a × b
+
+**示例**
+
+```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)
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | Bigint to square (len chunks) |
+| `result` | Output bigint array (must have len*2 chunks, pre-zeroed) |
+| `len` | Number of chunks in a |
+
+**返回：** void — result = a * a
+
+**示例**
+
+```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" />
+
+任意精度整数除法，计算商和余数
+
+```redscript
+fn bigint_div(a: int[], b: int[], quotient: int[], remainder: int[], la: int, lb: int): void
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 被除数大整数（la 个分块） |
+| `b` | 除数大整数（lb 个分块） |
+| `quotient` | 商输出数组（la 个分块，预置为 0） |
+| `remainder` | 余数输出数组（lb 个分块，预置为 0） |
+| `la` | a 的分块数（需 >= lb） |
+| `lb` | b 的分块数 |
+
+**返回：** void — quotient = a/b, remainder = a%b
+
+**示例**
+
+```redscript
+bigint_div(a, b, quotient, remainder, 4, 2)
+```
+
+---

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

@@ -0,0 +1,292 @@
+# Bits
+
+> 本文档由 `src/stdlib/bits.mcrs` 自动生成，请勿手动编辑。
+
+## 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" />
+
+检测 x 的第 n 位是否为 1
+
+```redscript
+fn bit_get(x: int, n: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 要检测的整数 |
+| `n` | 位索引（0 = 最低位），范围 [0, 30] |
+
+**返回：** 第 n 位为 1 则返回 1，否则返回 0
+
+**示例**
+
+```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" />
+
+将 x 的第 n 位设为 1（幂等）
+
+```redscript
+fn bit_set(x: int, n: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 要修改的整数 |
+| `n` | 要置 1 的位索引，范围 [0, 30] |
+
+**返回：** 第 n 位置为 1 后的 x
+
+**示例**
+
+```redscript
+let v: int = bit_set(0b0100, 0)  // result: 0b0101 = 5
+```
+
+---
+
+## `bit_clear` <Badge type="info" text="v1.0.0" />
+
+将 x 的第 n 位清零（幂等）
+
+```redscript
+fn bit_clear(x: int, n: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 要修改的整数 |
+| `n` | 要清零的位索引，范围 [0, 30] |
+
+**返回：** 第 n 位置为 0 后的 x
+
+**示例**
+
+```redscript
+let v: int = bit_clear(0b0111, 1)  // result: 0b0101 = 5
+```
+
+---
+
+## `bit_toggle` <Badge type="info" text="v1.0.0" />
+
+翻转 x 的第 n 位（0→1 或 1→0）
+
+```redscript
+fn bit_toggle(x: int, n: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 要修改的整数 |
+| `n` | 要翻转的位索引，范围 [0, 30] |
+
+**返回：** 第 n 位翻转后的 x
+
+**示例**
+
+```redscript
+let v: int = bit_toggle(0b0101, 1)  // result: 0b0111 = 7
+```
+
+---
+
+## `bit_shl` <Badge type="info" text="v1.0.0" />
+
+左移 x n 位（等效于 x * 2^n）
+
+```redscript
+fn bit_shl(x: int, n: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 要移位的整数 |
+| `n` | 左移位数，范围 [0, 30] |
+
+**返回：** x << n
+
+**示例**
+
+```redscript
+let v: int = bit_shl(1, 4)  // result: 16 (1 << 4)
+```
+
+---
+
+## `bit_shr` <Badge type="info" text="v1.0.0" />
+
+逻辑右移 x n 位（等效于 x / 2^n，向零截断）
+
+```redscript
+fn bit_shr(x: int, n: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 要移位的整数 |
+| `n` | 右移位数，范围 [0, 30] |
+
+**返回：** x >> n
+
+**示例**
+
+```redscript
+let v: int = bit_shr(256, 3)  // result: 32 (256 >> 3)
+```
+
+---
+
+## `bit_and` <Badge type="info" text="v1.0.0" />
+
+两个整数的按位与（31 个非符号位）
+
+```redscript
+fn bit_and(a: int, b: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个操作数 |
+| `b` | 第二个操作数 |
+
+**返回：** a & b（两者均为 1 的位）
+
+**示例**
+
+```redscript
+let v: int = bit_and(0b1100, 0b1010)  // result: 0b1000 = 8
+```
+
+---
+
+## `bit_or` <Badge type="info" text="v1.0.0" />
+
+两个整数的按位或（31 个非符号位）
+
+```redscript
+fn bit_or(a: int, b: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个操作数 |
+| `b` | 第二个操作数 |
+
+**返回：** a | b（至少一个为 1 的位）
+
+**示例**
+
+```redscript
+let v: int = bit_or(0b1100, 0b1010)  // result: 0b1110 = 14
+```
+
+---
+
+## `bit_xor` <Badge type="info" text="v1.0.0" />
+
+两个整数的按位异或（31 个非符号位）
+
+```redscript
+fn bit_xor(a: int, b: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `a` | 第一个操作数 |
+| `b` | 第二个操作数 |
+
+**返回：** a ^ b（恰好一个为 1 的位）
+
+**示例**
+
+```redscript
+let v: int = bit_xor(0b1100, 0b1010)  // result: 0b0110 = 6
+```
+
+---
+
+## `bit_not` <Badge type="info" text="v1.0.0" />
+
+按位非 — 翻转 x 的所有 31 个非符号位
+
+```redscript
+fn bit_not(x: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 要取反的整数 |
+
+**返回：** ~x（所有 31 个低位翻转；符号位不变）
+
+**示例**
+
+```redscript
+let v: int = bit_not(0)  // result: 2147483647 (all 31 bits set)
+```
+
+---
+
+## `popcount` <Badge type="info" text="v1.0.0" />
+
+统计 x 中置 1 的位数（汉明重量）
+
+```redscript
+fn popcount(x: int): int
+```
+
+**参数**
+
+| 参数 | 说明 |
+|------|------|
+| `x` | 整数值（使用 31 个低位；符号位不计） |
+
+**返回：** 置 1 的位数，范围 [0, 31]
+
+**示例**
+
+```redscript
+let n: int = popcount(255)  // result: 8 (0xFF has 8 bits set)
+```
+
+---