# bytes 二进制字节库

## 功能

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

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

## 语法

```bt
bytes(value, mode)
```

## 参数

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

## value 对象字段

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

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

## 返回值

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

## 方法

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

## 代码示例

```bt
data = bytes('4254', 'hex')

// 输出：BT
print data.to_text()
```

## 注意事项

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