企业官网建设流程全解析

• 人工智能
• AI 技能
• 文档
• 开发工具

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接口提供。

完整接口定义与全部示例见 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 成员函数语义

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

• 读取是静态方法，通过类型名直接调用，例如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 }

它同样通过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 }

该接口通过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完成端序切换，两者结果一致。

六、接口覆盖类型全览

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

各类型读写时占用的字节数与其固有宽度一致：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 包接口总文档。

• 人工智能
• AI 技能
• 文档
• 开发工具