diff --git a/doc/en/scripting/builtins/libbyteutil.md b/doc/en/scripting/builtins/libbyteutil.md new file mode 100644 index 00000000..fce89eae --- /dev/null +++ b/doc/en/scripting/builtins/libbyteutil.md @@ -0,0 +1,71 @@ +# *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. + +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) +debug.print(byteutil.unpack('>iBH?', bytes)) +-- outputs: +-- debug.print( +-- { +-- -8, +-- 250, +-- 2019, +-- true +-- } +--) +``` diff --git a/doc/ru/scripting/builtins/libbyteutil.md b/doc/ru/scripting/builtins/libbyteutil.md new file mode 100644 index 00000000..e7fb53bd --- /dev/null +++ b/doc/ru/scripting/builtins/libbyteutil.md @@ -0,0 +1,72 @@ +# Библиотека *byteutil* + +Библиотека предоставляет функции для работы с массивами байт, представленными в виде таблиц или Bytearray. + +```lua +byteutil.pack(format: str, ...) -> Bytearray +byteutil.tpack(format: str, ...) -> table +``` + +Возвращает массив байт, содержащий переданные значения, упакованные в соответствии со строкой формата. Аргументы должны точно соответствовать значениям, требуемым форматом. + +Строка формата состоит из специальных символов и символов значений. + +Специальные символы позволяют указать порядок байт для последующих значений: + +| Символ | Порядок байт | +| ------ | -------------------- | +| `@` | Системный | +| `=` | Системный | +| `<` | Little-endian | +| `>` | Big-endian | +| `!` | Сетевой (big-endian) | + + +Символы значений описывают тип и размер. + +| Символ | Аналог в С++ | Тип Lua | Размер | +| ------ | ------------ | -------- | ------- | +| `b` | int8_t | number | 1 байт | +| `B` | uint8_t | number | 1 байт | +| `?` | bool | boolean | 1 байт | +| `h` | int16_t | number | 2 байта | +| `H` | uint16_t | number | 2 байта | +| `i` | int32_t | number | 4 байта | +| `I` | uint32_t | number | 4 байта | +| `l` | int64_t | number | 8 байта | +| `L` | uint64_t | number | 8 байта | + +> [!WARNING] +> Из-за отсутствия в Lua целочисленного типа для значений `l` и `L` гарантируется +> только выходной размер в 8 байт, значение может отличаться от ожидаемого. + +Пример: + +```lua +debug.print(byteutil.tpack('>iBH?', -8, 250, 2019, true)) +-- выводит: +-- debug.print( +-- { +-- 255, +-- 255, +-- 255, +-- 248, +-- 250, +-- 7, +-- 227, +-- 1 +-- } +-- ) + +local bytes = byteutil.pack('>iBH?', -8, 250, 2019, true) +debug.print(byteutil.unpack('>iBH?', bytes)) +-- выводит: +-- debug.print( +-- { +-- -8, +-- 250, +-- 2019, +-- true +-- } +--) +```