# bytes Binary byte library

## Function

`bytes(value, mode)` Create immutable Bytes Value, used for binary data boundaries such as serial port, TCP, UDP, WebSocket, Modbus, etc.

Bytes does not implicitly convert strings according to UTF-8 lossy. `json(bytes(...))` outputs a Base64 object tagged with type: `{"type":"bytes","encoding":"base64","data":"..."}`.

## Syntax

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

## Parameters

| Parameters | Type | Required | Default value | Description |
|------|------|------|------|------|
| value | String/Array/Bytes/Object | No | Empty Bytes | Bytes source. String is encoded by UTF-8 by default; Array elements must be 0 to 255; Bytes are directly multiplexed; Object can use `hex`, `base64`, `text` or `data` fields. |
| mode | String | No | `text` | String Input parsing mode. Optional `text`, `utf8`, `hex`, `base64`, `base64_url`. |

## value Object field

When `value` is passed into Object, the first existing field will be read in the order of the following table: `hex`, `base64`, `text`, `data`. If none of these fields exist, empty Bytes are returned.

| Field | Type | Required | Default | Description |
|------|------|------|------|------|
| hex | String | No | None | Hexadecimal text. Whitespace, `_`, `-`, `:`, `,` are allowed as delimiters; valid hexadecimal digits must be an even number. |
| base64 | String | No | None | Base64 text. The encoding table can be selected with the `mode` field. |
| mode | String/Int | No | Standard Base64 | Only used if the `base64` field is present. String supports `standard_no_pad`, `no_pad`, `url_safe`, and `url_safe_no_pad`; Int supports `1` standard without padding, `2` URL security, and `3` URL security without padding. |
| text | Any | No | None | Convert to UTF-8 bytes in string form. |
| data | String/Array/Bytes/Empty/Null/Any | No | None | Generic bytes source. Bytes are directly reused; String is UTF-8; Array elements must be 0 to 255; `empty` or `null` generates empty Bytes; other values are first converted to strings and then written to UTF-8 bytes. |

## Return Value

| Type | Description |
|------|------|
| Bytes | Returns an immutable byte value. |

## Method

| Method | Description |
|------|------|
| [len](/en/docs/bytes/len) | Returns the length in bytes. |
| [get](/en/docs/bytes/get) | Read the specified index byte. |
| [slice](/en/docs/bytes/slice) | Intercept byte range. |
| [to_array](/en/docs/bytes/to_array) | Convert to integer array. |
| [to_hex](/en/docs/bytes/to_hex) | Convert to hexadecimal text. |
| [to_base64](/en/docs/bytes/to_base64) | Convert to Base64 text. |
| [to_text](/en/docs/bytes/to_text) | Convert text strictly to UTF-8. |
| [append](/en/docs/bytes/append) | Append data and return new Bytes. |

## Code Examples

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

// Output: BT
print data.to_text()
```

## Notes

- A single Bytes buffer is limited by `BT_BYTES_LIMIT`, with a default of 16777216 bytes and a maximum of 67108864 bytes.
- `to_text()` encounters illegal UTF-8 and returns `null` without lossy conversion.
- Bytes is an immutable value, and `append()` and `slice()` both return new Bytes.