# 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`.