人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载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包提供两类能力仓颉数据类型与二进制字节序列的互相转换分为大端序BigEndianOrder与小端序LittleEndianOrder两种转换类型仓颉数据类型自身字节顺序的反转由SwapEndianOrder接口提供。接口名原型功能BigEndianOrderTinterface BigEndianOrderT大端序字节序列转换接口。LittleEndianOrderTinterface LittleEndianOrderT小端序字节序列转换接口。SwapEndianOrderTinterface SwapEndianOrderT反转字节顺序接口。完整接口定义与全部示例见 binary_package_interfaces.md。三、BigEndianOrder大端序字节序列转换接口BigEndianOrderT用于将仓颉基础类型值与大端序字节数组互相转换接口定义为public interface BigEndianOrderT { func writeBigEndian(buffer: ArrayByte): Int64 static func readBigEndian(buffer: ArrayByte): T }3.1 成员函数语义成员原型说明readBigEndian静态static func readBigEndian(buffer: ArrayByte): T从字节数组中以大端序方式读取一个T值。writeBigEndian实例func writeBigEndian(buffer: ArrayByte): Int64将T值以大端序方式写入字节数组返回值为实际写入的字节数Int64。需要注意两个调用形态的区别读取是静态方法通过类型名直接调用例如Int32.readBigEndian(buffer)写入是实例方法挂在具体的值对象上调用例如0x1234i32.writeBigEndian(buffer)。buffer参数类型为 ArrayByteByte为无符号单字节类型作为待读取或待写入的缓冲区。3.2 支持的扩展类型BigEndianOrder通过extend机制为以下 12 种仓颉基础类型提供大端序转换能力每个类型均提供对应类型的静态readBigEndian与实例writeBigEndian布尔Bool浮点Float16、Float32、Float64有符号整数Int8、Int16、Int32、Int64无符号整数UInt8、UInt16、UInt32、UInt64以extend Int16 : BigEndianOrderInt16为例其含义是为Int16扩展BigEndianOrder接口以实现Int16值与大端序字节序列的转换。其他类型的扩展声明完全同构。3.3 读取与写入示例读取一个Int16大端序值字节[0x12, 0x34]对应数值0x1234import std.binary.* import std.unittest.* import std.unittest.testmacro.* main() { let buffer: ArrayByte [0x12, 0x34] let n Int16.readBigEndian(buffer) Assert(n, 0x1234) }写入一个Int16大端序值返回值为写入的字节数import std.binary.* import std.unittest.* import std.unittest.testmacro.* main() { let buffer ArrayByte(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: ArrayByte [0x4A, 0x40] let n Float16.readBigEndian(buffer) println(n 12.5) }运行结果为true。Float32写入12.5f32时返回长度 4缓冲区前 4 字节为[65, 72, 0, 0]即十六进制0x41, 0x48, 0x00, 0x00Float64写入12.5f64时返回长度 8字节序列为[0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]。单字节类型Int8、UInt8、Bool大端序与小端序的字节布局相同Bool读取[0x1]得到true写入true得到 1 字节[0x01]。四、LittleEndianOrder小端序字节序列转换接口LittleEndianOrderT与BigEndianOrderT结构完全对称用于小端序字节数组的转换public interface LittleEndianOrderT { func writeLittleEndian(buffer: ArrayByte): Int64 static func readLittleEndian(buffer: ArrayByte): T }成员原型说明readLittleEndian静态static func readLittleEndian(buffer: ArrayByte): T从字节数组中以小端序方式读取一个T值。writeLittleEndian实例func writeLittleEndian(buffer: ArrayByte): 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: ArrayByte [0x34, 0x12] let n Int16.readLittleEndian(buffer) Assert(n, 0x1234i16) }import std.binary.* import std.unittest.* import std.unittest.testmacro.* main() { let buffer ArrayByte(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字节顺序反转接口SwapEndianOrderT用于将仓颉整数值的字节顺序就地反转典型用途是把本机端序的数据切换为网络字节序或反向切换public interface SwapEndianOrderT { 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/UInt160x1234.swapBytes()得到0x3412对于Int64/UInt640x1234567890123456.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: ArrayByte—— 存放待读取或待写入数据的缓冲区。返回值读取类静态方法返回对应的T值写入类实例方法返回Int64即实际写入的字节数。异常当buffer太小不足以读出或存储目标T值时抛出 IllegalArgumentException。写入端在接口文档的示例中普遍采用ArrayByte(8, repeat: 0)预分配缓冲区——8 字节足以容纳Int64/UInt64/Float64之外的所有类型随后通过返回的字节数配合切片buffer[..n]取用有效区间如果传入的缓冲区小于目标类型宽度则会触发IllegalArgumentException。因此实际工程中建议按最大类型宽度 8 字节 返回值切片的模式组织缓冲区或在写入前用目标类型的固定宽度1/2/4/8 字节精确分配。八、典型应用场景将上述接口组合使用即可完成端到端的二进制数据编解码网络协议编解码对报文头字段统一使用BigEndianOrder网络字节序读写避免不同主机字节序导致的解析错乱跨平台文件格式解析按格式规范指定的端序选择BigEndianOrder或LittleEndianOrder读取结构字段如解析 WAV、BMP 等小端格式文件平台字节序判断与切换结合 core 包Endian枚举Endian.Platform判断运行平台端序再配合SwapEndianOrder.swapBytes()完成本地内存值与对外字节序的相互切换二进制序列化以writeBigEndian/writeLittleEndian将数值字段写入缓冲区以返回的字节数维护写入游标实现定长编码的序列化器。结语std.binary以三个接口、12 种基础类型的扩展覆盖了仓颉语言二进制数据处理的绝大多数场景BigEndianOrder与LittleEndianOrder负责与字节序列的双向转换SwapEndianOrder负责数值自身的字节序反转。配合清晰的静态读/实例写调用约定、返回写入字节数的设计以及缓冲区不足即抛IllegalArgumentException的异常语义开发者可以写出可读、可复用且跨平台一致的二进制编解码代码。更详尽的接口原型与全部可运行示例可继续查阅 BigEndianOrder 接口文档、LittleEndianOrder 接口文档、SwapEndianOrder 接口文档 以及 binary 包接口总文档。赞分享人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载相关推荐仓颉 std.binary 包端序转换全指南大端序、小端序与字节反转接口详解仓颉 std.binary 包端序转换全指南大端序、小端序与字节反转接口详解 本指南围绕仓颉标准库 std.binary 包展开系统讲解仓颉基础数据类型与二文档知识库教程OpenHarmony仓颉 std.binary LittleEndianOrder 接口详解小端序字节序列转换实战指南仓颉 std.binary LittleEndianOrder 接口详解小端序字节序列转换实战指南 本篇技术指南围绕仓颉标准库 std.binary 包中的人工智能AI 技能文档开发工具仓颉标准库 std.binary 完全指南大端/小端字节序转换与字节反转实战仓颉标准库 std.binary 完全指南大端/小端字节序转换与字节反转实战 本篇技术指南围绕仓颉Cangjie标准库中的 std.binary 包展开编程语言语言运行时标准库垃圾回收并发编程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考