hibase32-cj API完整参考：6个核心函数的参数、返回值与用法示例速查
【免费下载链接】hibase32-cjBase32(RFC 4648)编码/解码库项目地址: https://gitcode.com/Cangjie-TPC/hibase32-cj
hibase32-cj是一个使用仓颉语言实现的Base32（RFC 4648）编码/解码库，支持 UTF-8 中文文本与原始字节的互转。本文是一份完整的 API 速查指南：逐一讲解 6 个核心函数的参数、返回值与用法示例，帮你在 5 分钟内掌握全部接口，避免踩坑。
为什么选择 hibase32-cj？
Base32 编码把任意二进制数据映射为A-Z和2-7共 31 个安全字符，天然不区分大小写歧义（字符表不含0/O/1/I），常用于 Token、验证码、文件名编码等场景。hibase32-cj 的优势：
- ⚡纯仓颉实现：无外部 JS 依赖，
encodeBytes与unsignedRightShift均为自行实现 - 🈶UTF-8 友好：中文、emoji、生僻字（如
𠜎）均可正确编解码 - 🧪测试充分：配套 base32_test.cj 覆盖 ASCII、UTF-8、数组、异常等场景
项目结构非常简单，核心逻辑全部在 src/base32.cj 一个文件里：
src/ ├── base32.cj # 核心代码（全部 6 个核心函数都在这里） └── test/ └── base32_test.cj # 单元测试6个核心函数一览表
| 函数 | 参数 | 返回值 | 一句话用途 |
|---|---|---|---|
encode(input: String) | 待编码的字符串 | String | 字符串 → Base32 |
encode(input: Array<UInt8>) | 待编码的字节数组 | String | 字节数组 → Base32 |
decodeAsString(base32Str) | Base32 字符串 | String | Base32 → UTF-8 字符串 |
decodeAsBytes(base32Str) | Base32 字符串 | Array<UInt8> | Base32 → 字节数组 |
unsignedRightShift(value, shift) | 被移位值、移位位数 | Int64 | 32 位无符号右移（>>>） |
testVaildBase32(str) | 待校验字符串 | Bool | 校验是否为合法 Base32 字符 |
💡 记忆技巧：encode 管编码、decode 管解码、unsignedRightShift 是底层位运算、testVaildBase32 是输入校验，四个角色各司其职。
encode(String)：字符串编码函数怎么调用？
源码位置：src/base32.cj#L17-L19
public func encode(input: String): String- 参数：
input— 任意 UTF-8 字符串（中文、英文、emoji 均可） - 返回值：标准 Base32 编码字符串，末尾按需补齐
= - 内部流程：字符串先通过
toArray()转为字节序列，再交给私有的 encodeBytes 完成位运算
用法示例（摘自 README.md 功能示例）：
encode("Hello") // JBSWY3DP encode("中文") // 4S4K3ZUWQ4====== encode("𠜎") // 6CQJZDQ=encode(Array )：字节数组编码函数参数说明
源码位置：src/base32.cj#L13-L15
public func encode(input: Array<UInt8>): String与字符串版本同名的重载函数，适合处理二进制数据（文件内容、Buffer 等）。
- 参数：
input—UInt8字节数组 - 返回值：Base32 字符串
用法示例（与 base32_test.cj#L84-L88 中testUint8Arryay用例一致）：
var arr = ArrayList<UInt8>([72, 101, 108, 108, 111]).toArray() encode(arr) // JBSWY3DP✅ 字节
[72, 101, 108, 108, 111]正是"Hello"的 ASCII 值，两种入参编码结果完全一致。
decodeAsString：Base32解码为字符串的完整用法
源码位置：src/base32.cj#L21-L23
public func decodeAsString(base32Str: String): String- 参数：
base32Str— 标准 Base32 字符串（允许末尾=填充） - 返回值：按 UTF-8 还原后的字符串
- 实现原理：内部先调用
decodeAsBytes得到字节数组，再由String.fromUtf8还原为文本
用法示例（对应 base32_test.cj#L104-L112 的testUtf8Decode）：
decodeAsString("JBSQ====") // He decodeAsString("4S4K3ZUWQ4======") // 中文 decodeAsString("6CQJZDQ=") // 𠜎⚠️ 两个常见异常：
- 输入含非法字符（小写字母、
0/1/8/9、空格等）→ 抛出Exception("Invalid base32 characters") - 解码出的字节不是合法 UTF-8 → 抛出
OverflowException，例如解码7A======（字节 0x7A 无法独立构成 UTF-8）
下图就是一个真实的解码异常堆栈，指向 base32.cj 的decode调用链：
decodeAsBytes：解码为字节数组的参数与返回值
源码位置：src/base32.cj#L25-L125
public func decodeAsBytes(base32Str: String): Array<UInt8>- 参数：
base32Str— Base32 字符串 - 返回值：
Array<UInt8>字节数组 - 边界行为：
- 空字符串 → 返回空数组（不抛异常）
- 非法字符 → 抛出
Exception - 解码采用「8 字符一组」批量处理 + 剩余 2/4/5/7 字符的余数分支，保证填充
=被正确处理
如果你要的是"解码成可打印文本"，直接用decodeAsString；需要操作原始二进制（写文件、协议组包）时才用decodeAsBytes。
unsignedRightShift：仓颉版无符号右移怎么用？
源码位置：src/base32.cj#L206-L216
public func unsignedRightShift(value: Int64, shift: Int64): Int64这是本库对 JavaScript>>>运算符的等价实现，也是 Base32 位拼接的底层基石：
- 参数：
value— 被移位值；shift— 右移位数 - 返回值：32 位无符号右移结果
- 细节：移位位数会先对 32 取模，
shift % 32 == 0时直接返回原值
用法示例（摘自 base32_test.cj#L129-L158 的testUnsignedRightShift）：
unsignedRightShift(2, 1) // 1 unsignedRightShift(-2, 1) // 2147483647（负数按无符号处理） unsignedRightShift(2, 32) // 2（移位位数大于32时自动取模）💡 一般业务代码很少直接调用它，但理解它有助于你看懂 encodeBytes 里每 5 字节拼出 8 个字符的位运算。
testVaildBase32：如何快速校验Base32字符串合法性？
源码位置：src/base32.cj#L218-L228
public func testVaildBase32(str: String): Bool- 参数：
str— 待校验字符串 - 返回值：
true表示每个字符都在ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=白名单内 - 典型用途：在调用解码前先做"前置体检"，给用户更友好的错误提示
用法示例（摘自 base32_test.cj#L160-L172 的testVaildBase32）：
testVaildBase32("A2B3C4D5") // true testVaildBase32("abcdefgh") // false（小写不合法） testVaildBase32("ABCD*EFG") // false（含非法字符 *）Base32 字符表速记：A-Z映射 0–25，2-7映射 26–31（定义见 BASE32_DECODE_CHAR），注意0、1、8、9 是刻意缺席的。
解码原理中的 Rune 类型是什么？
decodeAsBytes内部把输入转成 Rune 数组遍历（base32.cj#L34 的toRuneArray()）。Rune 是仓颉中表示 Unicode 字符的类型，覆盖\u{0000}–\u{D7FF}与\u{E000}–\u{10FFF}：
正因为按 Rune（而非字节）遍历，中文等多字节字符才能被正确识别。
如何编译运行与验证测试？
在项目根目录执行即可（配置见 cjpm.toml，当前要求 cjc 0.53.4+）：
cjpm build # 编译构建（Win/Linux/Mac 通用）想自己验证接口行为，运行单元测试即可覆盖 ASCII、UTF-8、数组、异常全部用例：
cjpm test常见问题速答（FAQ）
Q1：编码结果末尾的=是错误吗？不是。=是 RFC 4648 的标准填充，长度取决于输入字节数 mod 5，解码时会被自动忽略。
Q2：为什么小写字母不能解码？RFC 4648 标准字符表只含大写字母与2-7，testVaildBase32 对abcdefgh会返回false，请自行做大小写转换后再解码。
Q3：空字符串能编解码吗？可以。encode("")返回空字符串，decodeAsBytes("")返回空数组，均不会抛异常。
Q4：解码到非法 UTF-8 会怎样？decodeAsString会抛出OverflowException。若不确定输出是否为文本，建议先用decodeAsBytes拿到字节再自行处理。
总结
hibase32-cj 以极小的 API 面提供了完整的 Base32 能力：两个encode重载负责编码，两个decode变体负责解码，unsignedRightShift与testVaildBase32分别是位运算与校验的基石。配合 src/test/base32_test.cj 的完整用例，你可以放心地在仓颉项目中用它处理 Token、验证码、文件编码等一切 Base32 场景。
【免费下载链接】hibase32-cjBase32(RFC 4648)编码/解码库项目地址: https://gitcode.com/Cangjie-TPC/hibase32-cj
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
