bytes 二进制字节库

bytes 二进制字节库

AI 原文

bytes 二进制字节库

功能

bytes(value, mode) 创建不可变 Bytes 值，用于串口、TCP、UDP、WebSocket、Modbus 等二进制数据边界。

Bytes 不会隐式按 UTF-8 lossy 转字符串。json(bytes(...)) 输出带类型标记的 Base64 对象：{"type":"bytes","encoding":"base64","data":"..."}。

语法

参数

参数类型必填默认值说明
valueString/Array/Bytes/Object否空 Bytes字节来源。String 默认按 UTF-8 编码；Array 元素必须是 0 到 255；Bytes 直接复用；Object 可使用 hex、base64、text 或 data 字段。
modeString否textString 输入的解析模式。可选 text、utf8、hex、base64、base64_url。

value 对象字段

当 value 传入 Object 时，会按下表顺序读取第一个存在的字段：hex、base64、text、data。如果这些字段都不存在，返回空 Bytes。

字段类型必填默认值说明
hexString否无十六进制文本。允许空白符、_、-、:、, 作为分隔符；有效十六进制位数必须为偶数。
base64String否无Base64 文本。可配合 mode 字段选择编码表。
modeString/Int否标准 Base64仅在 base64 字段存在时使用。String 支持 standard_no_pad、no_pad、url_safe、url_safe_no_pad；Int 支持 1 标准无补位、2 URL 安全、3 URL 安全无补位。
textAny否无按字符串形式转为 UTF-8 字节。
dataString/Array/Bytes/Empty/Null/Any否无通用字节来源。Bytes 直接复用；String 按 UTF-8；Array 元素必须是 0 到 255；empty 或 null 生成空 Bytes；其它值先转字符串再写入 UTF-8 字节。

返回值

类型说明
Bytes返回不可变字节值。

方法

方法说明
len返回字节长度。
get读取指定下标字节。
slice截取字节区间。
to_array转为整数数组。
to_hex转为十六进制文本。
to_base64转为 Base64 文本。
to_text按 UTF-8 严格转文本。
append追加数据并返回新 Bytes。

代码示例

注意事项

  • 单个 Bytes 缓冲受 BT_BYTES_LIMIT 限制，默认 16777216 字节，最大 67108864 字节。
  • to_text() 遇到非法 UTF-8 返回 null，不会做 lossy 转换。
  • Bytes 是不可变值，append()、slice() 都返回新的 Bytes。