仓颉 std.binary 包实战指南：大小端字节序列转换与字节序反转接口详解

std.binary 是仓颉标准库中专用于处理字节序（Endianness）的包，它把仓颉基础数据类型（Bool、整数与浮点数）与二进制字节序列之间的转换能力封装为三个接口：BigEndianOrder、LittleEndianOrder 和 SwapEndianOrder。本篇指南以 std/binary/readme.md 为骨架，结合包内接口文档与可运行示例，系统讲解端序概念、三个接口的完整原型、支持的仓颉类型清单、缓冲区读写规则与异常语义，帮助你在网络协议编解码、文件格式解析、跨平台数据交换等场景中直接落地使用。

一、端序基础：大端序与小端序

在理解 std.binary 之前，需要先厘清端序（Endianness，又称字节顺序、尾序）这一概念。正如 binary 包总览 中所述：

一般来说，多字节对象被存储为连续的字节序列。存储器或数字通信链路中，字节的排列顺序称为端序（Endianness）。

• 大端序（Big-endian）：将多位数的高位字节存储在内存的低地址端、低位字节存储在高地址端，即"高位在前"。
• 小端序（Little-endian）：将低位字节存储在内存的低地址端、高位字节存储在高地址端，即"低位在前"。

例如数值 0x12345678：

• 大端序字节序列为 [0x12, 0x34, 0x56, 0x78]；
• 小端序字节序列为 [0x78, 0x56, 0x34, 0x12]。

常见网络协议（TCP/IP 报文头、DNS、RTP 等）约定使用大端序（网络字节序），而 x86 等主流处理器内存中则是小端序，因此跨端序系统间交换二进制数据时，显式指定端序的转换接口必不可少。仓颉语言还在 core 包 中提供了 Endian 枚举（Big / Little，以及获取当前运行平台端序的 Endian.Platform 属性），可与 std.binary 配合进行平台相关判断。

二、std.binary 包能力总览

std.binary 包提供两类能力：

1. 仓颉数据类型与二进制字节序列的互相转换，分为大端序（BigEndianOrder）与小端序（LittleEndianOrder）两种转换类型；
2. 仓颉数据类型自身字节顺序的反转，由 SwapEndianOrder 接口提供。

接口名	原型	功能
BigEndianOrder<T>	interface BigEndianOrder<T>	大端序字节序列转换接口。
LittleEndianOrder<T>	interface LittleEndianOrder<T>	小端序字节序列转换接口。
SwapEndianOrder<T>	interface SwapEndianOrder<T>	反转字节顺序接口。

完整接口定义与全部示例见 binary_package_interfaces.md。

三、BigEndianOrder：大端序字节序列转换接口

BigEndianOrder<T> 用于将仓颉基础类型值与大端序字节数组互相转换，接口定义为：

public interface BigEndianOrder<T> {
    func writeBigEndian(buffer: Array<Byte>): Int64
    static func readBigEndian(buffer: Array<Byte>): T
}

3.1 成员函数语义

成员	原型	说明
readBigEndian（静态）	static func readBigEndian(buffer: Array<Byte>): T	从字节数组中以大端序方式读取一个 T 值。
writeBigEndian（实例）	func writeBigEndian(buffer: Array<Byte>): Int64	将 T 值以大端序方式写入字节数组，返回值为实际写入的字节数（Int64）。

需要注意两个调用形态的区别：

• 读取是静态方法，通过类型名直接调用，例如 Int32.readBigEndian(buffer)；
• 写入是实例方法，挂在具体的值对象上调用，例如 0x1234i32.writeBigEndian(buffer)。

buffer 参数类型为 Array<Byte>（Byte 为无符号单字节类型），作为待读取或待写入的缓冲区。

3.2 支持的扩展类型

BigEndianOrder 通过 extend 机制为以下 12 种仓颉基础类型提供大端序转换能力（每个类型均提供对应类型的静态 readBigEndian 与实例 writeBigEndian）：

• 布尔：Bool
• 浮点：Float16、Float32、Float64
• 有符号整数：Int8、Int16、Int32、Int64
• 无符号整数：UInt8、UInt16、UInt32、UInt64

以 extend Int16 <: BigEndianOrder<Int16> 为例，其含义是：为 Int16 扩展 BigEndianOrder 接口，以实现 Int16 值与大端序字节序列的转换。其他类型的扩展声明完全同构。

3.3 读取与写入示例

读取一个 Int16 大端序值（字节 [0x12, 0x34] 对应数值 0x1234）：

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x12, 0x34]
    let n = Int16.readBigEndian(buffer)
    @Assert(n, 0x1234)
}

写入一个 Int16 大端序值，返回值为写入的字节数：

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234i16.writeBigEndian(buffer)
    @Assert(n, 2)
    @Assert(buffer[..n] == [0x12, 0x34])
}

浮点类型同样适用。以 Float16 为例，12.5 的 IEEE 754 半精度表示为 0x4A40，因此大端序字节序列为 [0x4A, 0x40]：

import std.binary.*

main() {
    /* 12.5的IEEE 754表示为0x4A40 */
    let buffer: Array<Byte> = [0x4A, 0x40]
    let n = Float16.readBigEndian(buffer)
    println(n == 12.5)
}

运行结果为 true。Float32 写入 12.5f32 时返回长度 4，缓冲区前 4 字节为 [65, 72, 0, 0]（即十六进制 0x41, 0x48, 0x00, 0x00）；Float64 写入 12.5f64 时返回长度 8，字节序列为 [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]。

单字节类型（Int8、UInt8、Bool）大端序与小端序的字节布局相同：Bool 读取 [0x1] 得到 true，写入 true 得到 1 字节 [0x01]。

四、LittleEndianOrder：小端序字节序列转换接口

LittleEndianOrder<T> 与 BigEndianOrder<T> 结构完全对称，用于小端序字节数组的转换：

public interface LittleEndianOrder<T> {
    func writeLittleEndian(buffer: Array<Byte>): Int64
    static func readLittleEndian(buffer: Array<Byte>): T
}

成员	原型	说明
readLittleEndian（静态）	static func readLittleEndian(buffer: Array<Byte>): T	从字节数组中以小端序方式读取一个 T 值。
writeLittleEndian（实例）	func writeLittleEndian(buffer: Array<Byte>): Int64	将 T 值以小端序方式写入字节数组，返回实际写入的字节数。

它同样通过 extend 为 Bool、Float16、Float32、Float64、Int8、Int16、Int32、Int64、UInt8、UInt16、UInt32、UInt64 共 12 种类型提供转换能力。

与第三章节对比可以直观看到大小端字节序列的差异：同一个 0x1234，大端序读取 [0x12, 0x34]，小端序则要读取 [0x34, 0x12]：

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer: Array<Byte> = [0x34, 0x12]
    let n = Int16.readLittleEndian(buffer)
    @Assert(n, 0x1234i16)
}

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let buffer = Array<Byte>(8, repeat: 0)
    let n = 0x1234i16.writeLittleEndian(buffer)
    @Assert(n, 2)
    @Assert(buffer[..n] == [0x34, 0x12])
}

浮点的小端序布局同样与大小端相反：Float32 读取 12.5 的小端序字节为 [0x00, 0x00, 0x48, 0x41]（大端序为 [0x41, 0x48, 0x00, 0x00]），Float64 的小端序字节为 [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40]。

五、SwapEndianOrder：字节顺序反转接口

SwapEndianOrder<T> 用于将仓颉整数值的字节顺序就地反转，典型用途是把本机端序的数据切换为网络字节序或反向切换：

public interface SwapEndianOrder<T> {
    func swapBytes(): T
}

成员	原型	说明
swapBytes（实例）	func swapBytes(): T	反转 T 值的字节顺序并返回新值。

该接口通过 extend 为 8 种整数类型提供能力：Int8、Int16、Int32、Int64、UInt8、UInt16、UInt32、UInt64。注意它不包含 Bool 与浮点类型。

swapBytes 的调用非常简洁：

import std.binary.*
import std.unittest.*
import std.unittest.testmacro.*

main() {
    let n = 0x12345678i32
    let m = n.swapBytes()
    @Assert(m, 0x78563412)
}

对于 Int16 / UInt16，0x1234.swapBytes() 得到 0x3412；对于 Int64 / UInt64，0x1234567890123456.swapBytes() 得到 0x5634129078563412。单字节类型（Int8、UInt8）只有一个字节，反转后仍是原值（如 0x12.swapBytes() 仍为 0x12），示例中对此也有明确断言。

从使用逻辑看，swapBytes 与大/小端转换接口可以形成闭环：例如在 x86（小端）机器上，先用 writeBigEndian 写出网络序数据，或对内存中的整数值调用 swapBytes 完成端序切换，两者结果一致。

六、接口覆盖类型全览

为便于查阅，下表汇总三个接口各自支持的仓颉基础类型：

仓颉类型	BigEndianOrder（大端读写）	LittleEndianOrder（小端读写）	SwapEndianOrder（字节反转）
Bool	✅	✅	—
Float16	✅	✅	—
Float32	✅	✅	—
Float64	✅	✅	—
Int8	✅	✅	✅（原值返回）
Int16	✅	✅	✅
Int32	✅	✅	✅
Int64	✅	✅	✅
UInt8	✅	✅	✅（原值返回）
UInt16	✅	✅	✅
UInt32	✅	✅	✅
UInt64	✅	✅	✅

各类型读写时占用的字节数与其固有宽度一致：Bool 与 8 位整数为 1 字节，Int16/UInt16/Float16 为 2 字节，Int32/UInt32/Float32 为 4 字节，Int64/UInt64/Float64 为 8 字节。

七、缓冲区规则与异常处理

两个转换接口对缓冲区 buffer 有明确的能力边界约束，接口文档 对每个成员都标注了参数、返回值与异常语义：

• 参数：buffer: Array<Byte> —— 存放待读取或待写入数据的缓冲区。
• 返回值：读取类静态方法返回对应的 T 值；写入类实例方法返回 Int64，即实际写入的字节数。
• 异常：当 buffer 太小，不足以读出或存储目标 T 值时，抛出 IllegalArgumentException。

写入端在接口文档的示例中普遍采用 Array<Byte>(8, repeat: 0) 预分配缓冲区——8 字节足以容纳 Int64/UInt64/Float64 之外的所有类型，随后通过返回的字节数配合切片 buffer[..n] 取用有效区间；如果传入的缓冲区小于目标类型宽度，则会触发 IllegalArgumentException。因此实际工程中建议按"最大类型宽度 8 字节 + 返回值切片"的模式组织缓冲区，或在写入前用目标类型的固定宽度（1/2/4/8 字节）精确分配。

八、典型应用场景

将上述接口组合使用，即可完成端到端的二进制数据编解码：

1. 网络协议编解码：对报文头字段统一使用 BigEndianOrder（网络字节序）读写，避免不同主机字节序导致的解析错乱；
2. 跨平台文件格式解析：按格式规范指定的端序选择 BigEndianOrder 或 LittleEndianOrder 读取结构字段，如解析 WAV、BMP 等小端格式文件；
3. 平台字节序判断与切换：结合 core 包 Endian 枚举（Endian.Platform）判断运行平台端序，再配合 SwapEndianOrder.swapBytes() 完成本地内存值与对外字节序的相互切换；
4. 二进制序列化：以 writeBigEndian/writeLittleEndian 将数值字段写入缓冲区，以返回的字节数维护写入游标，实现定长编码的序列化器。

结语

std.binary 以三个接口、12 种基础类型的扩展覆盖了仓颉语言二进制数据处理的绝大多数场景：BigEndianOrder 与 LittleEndianOrder 负责与字节序列的双向转换，SwapEndianOrder 负责数值自身的字节序反转。配合清晰的静态读/实例写调用约定、返回写入字节数的设计以及缓冲区不足即抛 IllegalArgumentException 的异常语义，开发者可以写出可读、可复用且跨平台一致的二进制编解码代码。更详尽的接口原型与全部可运行示例，可继续查阅 BigEndianOrder 接口文档、LittleEndianOrder 接口文档、SwapEndianOrder 接口文档 以及 binary 包接口总文档。