nodemcu-firmware/docs/en/modules/struct.md

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.