173 lines
4.7 KiB
Markdown
173 lines
4.7 KiB
Markdown
# struct module
|
|
|
|
This module offers basic facilities to convert Lua values to and from C
|
|
structs. Its main functions are `struct.pack`, which packs multiple Lua
|
|
values into a struct-like string; and `struct.unpack`, which unpacks
|
|
multiple Lua values from a given struct-like string.
|
|
|
|
The first argument to both functions is a *format string*, which
|
|
describes the layout of the structure. The format string is a sequence
|
|
of conversion elements, which respect the current endianess and the
|
|
current alignment requirements. Initially, the current endianess is the
|
|
machine's native endianness and the current alignment requirement is 1
|
|
(meaning no alignment at all). You can change these settings with
|
|
appropriate directives in the format string.
|
|
|
|
Note that the float and double conversions are only available with
|
|
a floating point NodeMCU build.
|
|
|
|
### Format String
|
|
|
|
The elements in the format string are as follows:
|
|
|
|
- `" "` (empty space) ignored.
|
|
- `"!n"` flag to set the current alignment requirement to *n*
|
|
(necessarily a power of 2); an absent *n* means the machine's native
|
|
alignment.
|
|
- `">"` flag to set mode to big endian.
|
|
- `"<"` flag to set mode to little endian.
|
|
- `"x"` a padding zero byte with no corresponding Lua value.
|
|
- `"b"` a signed `char`.
|
|
- `"B"` an unsigned `char`.
|
|
- `"h"` a signed `short` (native size).
|
|
- `"H"` an unsigned `short` (native size).
|
|
- `"l"` a signed `long` (native size).
|
|
- `"L"` an unsigned `long` (native size).
|
|
- `"T"` a `size_t` (native size).
|
|
- `"in"` a signed integer with *n* bytes. An absent *n* means the
|
|
native size of an `int`.
|
|
- `"In"` like `"in"` but unsigned.
|
|
- `"f"` a `float` (native size).
|
|
- `"d"` a `double` (native size).
|
|
- `"s"` a zero-terminated string.
|
|
- `"cn"` a sequence of exactly *n* chars corresponding to a single Lua
|
|
string. An absent *n* means 1. When packing, the given string must
|
|
have at least *n* characters (extra characters are discarded).
|
|
- `"c0"` this is like `"cn"`, except that the *n* is given by other
|
|
means: When packing, *n* is the length of the given string; when
|
|
unpacking, *n* is the value of the previous unpacked value (which
|
|
must be a number). In that case, this previous value is not
|
|
returned.
|
|
|
|
#### Examples
|
|
|
|
To pack and unpack the structure
|
|
|
|
struct Str {
|
|
char b;
|
|
int i[4];
|
|
};
|
|
|
|
you can use the string `"<!4biiii"`.
|
|
|
|
To pack a string with its length coded in its first byte, use the
|
|
following code:
|
|
|
|
x = struct.pack("Bc0", string.len(s), s)
|
|
|
|
To unpack that string, do as follows:
|
|
|
|
s = struct.unpack("Bc0", x)
|
|
|
|
Note that the length (read by the element `"B"`) is not returned.
|
|
|
|
To pack a string in a fixed-width field of 10 characters padded with
|
|
blanks, do as follows:
|
|
|
|
x = struct.pack("c10", s .. string.rep(" ", 10))
|
|
|
|
|
|
## struct.pack()
|
|
|
|
Returns a string containing the values `d1`, `d2`, etc. packed
|
|
according to the format string `fmt`.
|
|
|
|
#### Syntax
|
|
|
|
`struct.pack (fmt, d1, d2, ...)`
|
|
|
|
#### Parameters
|
|
|
|
- `fmt` The format string in the format above
|
|
- `d1` The first data item to be packed
|
|
- `d2` The second data item to be packed etc.
|
|
|
|
#### Returns
|
|
|
|
The packed string.
|
|
|
|
#### Example
|
|
|
|
```
|
|
s = struct.pack("I", 0x41424344)
|
|
print(s)
|
|
```
|
|
|
|
## struct.unpack()
|
|
|
|
Returns the values packed in string `s` according to the format
|
|
string `fmt`. An optional `i` marks where in `s` to start reading
|
|
(default is 1). After the read values, this function also returns
|
|
the index in `s` where it stopped reading, which is also where you
|
|
should start to read the rest of the string.
|
|
|
|
#### Syntax
|
|
|
|
`struct.unpack (fmt, s[, offset])`
|
|
|
|
#### Parameters
|
|
|
|
- `fmt` The format string in the format above
|
|
- `s` The string holding the data to be unpacked
|
|
- `offset` The position to start in the string (default is 1)
|
|
|
|
#### Returns
|
|
|
|
All the unpacked data.
|
|
|
|
#### Example
|
|
|
|
Suppose we have to decode a string `s` with an unknown number of
|
|
doubles; the end is marked by a zero value. We can use the following
|
|
code:
|
|
|
|
local a = {}
|
|
local i = 1 -- index where to read
|
|
while true do
|
|
local d
|
|
d, i = struct.unpack("d", s, i)
|
|
if d == 0 then break end
|
|
a[#a + 1] = d
|
|
end
|
|
|
|
## struct.size()
|
|
|
|
Returns the size of a string formatted according to the format
|
|
string `fmt`. The format string should contain neither the option
|
|
`s` nor the option `c0`.
|
|
|
|
#### Syntax
|
|
|
|
`struct.size (fmt)`
|
|
|
|
#### Parameters
|
|
|
|
- `fmt` The format string in the format above
|
|
|
|
#### Returns
|
|
|
|
The size of the string that would be output in a pack operation with this format string.
|
|
|
|
#### Example
|
|
|
|
```
|
|
print(struct.size("i"))
|
|
```
|
|
|
|
This prints the size of the native integer type.
|
|
|
|
### License
|
|
|
|
This package is distributed under the MIT license. See copyright notice
|
|
at the end of file `struct.c`.
|