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,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
+--  }
+--)
+```