add byteutil docs

2024-12-27 09:37:09 +03:00
parent 0af0e8a58d
commit bb2cff5186
2 changed files with 143 additions and 0 deletions
@@ -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
+--  }
+--)
+```