API Conv8

Conv8

面向 UInt8Array 的静态二进制编解码帮助类型。

脚本 API 参考 · UInt8Array

概述

Conv8 是基础设施 NativeType，在字节缓冲上读写标量与 UTF-8 文本。typeof Conv8 为 "type"，new Conv8() 失败，也不保存状态。缓冲区必须是 UInt8Array；Int8Array 及其他 packed array 会按类型不匹配失败。

多字节整数与浮点通过 littleEndian 控制字节序，默认 true（低字节在前）。脚本 string 本身是 UTF-16；getString / setString 只做 UTF-8 字节 ↔ 脚本字符串，没有通用 Encoding 对象。

偏移越界或字符串写入超出剩余空间时抛出运行时错误。Conv8.getInt64 / getUInt64 仍以 Number 往返，超出精确整数范围会丢失精度；需要完整 64 位时使用 int64 或 Int64Array。

未遮蔽且参数类型已证明时，固定参数方法可直调 Core。

快速参考

Member	Returns	摘要
Conv8.BYTES1	number	1 字节宽度（bool、int8、uint8）。
Conv8.BYTES2	number	2 字节宽度（int16、uint16）。
Conv8.BYTES4	number	4 字节宽度（int32、uint32、float32）。
Conv8.BYTES8	number	8 字节宽度（int64、uint64、float64）。
Conv8.getBool(buffer, offset)	boolean	读 1 字节；非 0 为 true。
Conv8.setBool(buffer, offset, value)	—	写 1 字节 0 或 1。
Conv8.getInt8(buffer, offset)	number	有符号 8 位。
Conv8.setInt8(buffer, offset, value)	—	有符号 8 位。
Conv8.getUInt8(buffer, offset)	number	无符号 8 位。
Conv8.setUInt8(buffer, offset, value)	—	无符号 8 位。
Conv8.getInt16(buffer, offset, littleEndian?)	number	有符号 16 位。
Conv8.setInt16(buffer, offset, value, littleEndian?)	—	有符号 16 位。
Conv8.getUInt16(buffer, offset, littleEndian?)	number	无符号 16 位。
Conv8.setUInt16(buffer, offset, value, littleEndian?)	—	无符号 16 位。
Conv8.getInt32(buffer, offset, littleEndian?)	number	有符号 32 位。
Conv8.setInt32(buffer, offset, value, littleEndian?)	—	有符号 32 位。
Conv8.getUInt32(buffer, offset, littleEndian?)	number	无符号 32 位。
Conv8.setUInt32(buffer, offset, value, littleEndian?)	—	无符号 32 位。
Conv8.getInt64(buffer, offset, littleEndian?)	number	有符号 64 位，经 Number。
Conv8.setInt64(buffer, offset, value, littleEndian?)	—	有符号 64 位，来自 Number。
Conv8.getUInt64(buffer, offset, littleEndian?)	number	无符号 64 位，经 Number。
Conv8.setUInt64(buffer, offset, value, littleEndian?)	—	无符号 64 位，来自 Number。
Conv8.getFloat32(buffer, offset, littleEndian?)	number	IEEE-754 binary32。
Conv8.setFloat32(buffer, offset, value, littleEndian?)	—	IEEE-754 binary32。
Conv8.getFloat64(buffer, offset, littleEndian?)	number	IEEE-754 binary64。
Conv8.setFloat64(buffer, offset, value, littleEndian?)	—	IEEE-754 binary64。
Conv8.getString(buffer, offset, byteLength)	string	按字节长度读 UTF-8。
Conv8.setString(buffer, offset, value)	number	写 UTF-8，返回写入字节数。

buffer 一律为 UInt8Array。offset 为从 0 起的字节偏移。省略 littleEndian 时视为 true。set*（除 setString）无返回值。

常量

字节宽度常量便于手工推进偏移。同宽的有符号/无符号/浮点共用一个常量。

var bytes = new UInt8Array(Conv8.BYTES4 + Conv8.BYTES2);
Conv8.setInt32(bytes, 0, 7);
Conv8.setInt16(bytes, Conv8.BYTES4, -3);
return Conv8.getInt16(bytes, 4); // -3

整数与浮点

8 位读写没有字节序参数。16/32/64 位整数与 float32/float64 的最后一个参数为 littleEndian。

var bytes = new UInt8Array(4);
Conv8.setInt32(bytes, 0, 0x01020304, true);
var little = [bytes[0], bytes[1], bytes[2], bytes[3]]; // [4, 3, 2, 1]
Conv8.setInt32(bytes, 0, 0x01020304, false);
return Conv8.getInt32(bytes, 0, false); // 0x01020304

getBool 把非零字节当作 true；setBool 只写入 0 或 1。

字符串

setString 按 UTF-8 写入（无 BOM），返回实际字节数。getString 需要调用方提供该字节长度。脚本字符串内部仍是 UTF-16。

var bytes = new UInt8Array(16);
var written = Conv8.setString(bytes, 2, "hi");
return Conv8.getString(bytes, 2, written); // "hi"

剩余空间不足或 offset/byteLength 越界时抛错。不要把 Encoding.Unicode 理解成这套 API；需要 UTF-16 定长字段时应另议封闭常量，而不是通用 Encoding 类型。

边界

• 只接受 UInt8Array。Int8Array、Int32Array 等会失败。
• 索引范围是 [offset, offset + size)，必须落在 buffer.length 内。
• int64 / uint64 不提供精确 64 位整数类型；超出 Number 精确整数范围会丢失精度。
• 没有脚本级 Encoding 全局。Conv8 字符串路径固定 UTF-8。