71 lines
2.0 KiB
Markdown
71 lines
2.0 KiB
Markdown
# *byteutil* library
|
||
|
||
The library provides functions for working with byte arrays represented as tables or Bytearrays.
|
||
|
||
```lua
|
||
byteutil.pack(format: str, ...) -> Bytearray
|
||
byteutil.tpack(format: str, ...) -> table
|
||
```
|
||
|
||
Returns a byte array containing the provided values packed according to the format string. The arguments must exactly match the values required by the format.
|
||
|
||
The format string consists of special characters and value characters.
|
||
|
||
Special characters specify the byte order for the subsequent values:
|
||
|
||
| Character | Byte Order |
|
||
| --------- | ------------------- |
|
||
| `@` | System |
|
||
| `=` | System |
|
||
| `<` | Little-endian |
|
||
| `>` | Big-endian |
|
||
| `!` | Network (big-endian)|
|
||
|
||
|
||
Value characters describe the type and size.
|
||
|
||
| Character | C++ Equivalent | Lua Type | Size |
|
||
| --------- | -------------- | -------- | ------- |
|
||
| `b` | int8_t | number | 1 byte |
|
||
| `B` | uint8_t | number | 1 byte |
|
||
| `?` | bool | boolean | 1 byte |
|
||
| `h` | int16_t | number | 2 bytes |
|
||
| `H` | uint16_t | number | 2 bytes |
|
||
| `i` | int32_t | number | 4 bytes |
|
||
| `I` | uint32_t | number | 4 bytes |
|
||
| `l` | int64_t | number | 8 bytes |
|
||
| `L` | uint64_t | number | 8 bytes |
|
||
|
||
> [!WARNING]
|
||
> Due to the absence of an integer type in Lua for values `l` and `L`, only an output size of 8 bytes is guaranteed; the value may differ from what is expected.
|
||
|
||
```lua
|
||
byteutil.unpack(format: str, bytes: table|Bytearray) -> ...
|
||
```
|
||
|
||
Extracts values from a byte array based on a format string.
|
||
|
||
Example:
|
||
|
||
```lua
|
||
debug.print(byteutil.tpack('>iBH?', -8, 250, 2019, true))
|
||
-- outputs:
|
||
-- debug.print(
|
||
-- {
|
||
-- 255,
|
||
-- 255,
|
||
-- 255,
|
||
-- 248,
|
||
-- 250,
|
||
-- 7,
|
||
-- 227,
|
||
-- 1
|
||
-- }
|
||
-- )
|
||
|
||
local bytes = byteutil.pack('>iBH?', -8, 250, 2019, true)
|
||
print(byteutil.unpack('>iBH?', bytes))
|
||
-- outputs:
|
||
-- -8 250 2019 true
|
||
```
|