Module struct

Corona binding to struct, a library offering basic facilities to convert Lua values to and from C structs.

local struct = require("plugin.serialize").struct

Its main functions are pack, which packs multiple Lua values into a struct-like string; and unpack, which unpacks multiple Lua values from a given struct-like string.

The fist 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.

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.

Notice in the original:

This package is distributed under the MIT license. See copyright notice at the end of file struct.c.

Examples

  • The code print(struct.size("i")) prints the size of a machine's native int.

  • To pack and unpack the structure

    struct Str {
      char b;
      int i[4];
    };
    

you can use the string "<!4biiii".

  • If you need to code a structure with a large array, you may use string.rep to automatically generate part of the string format. For instance, for the structure

    struct Str {
      double x;
      int i[400];
    };
    

you can build the format string with the code "d"..string.rep("i", 400).

  • 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.

  • 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
    
  • 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))
    

Functions

pack (fmt, ...) Returns a string containing the values packed according to the format string fmt.
unpack (fmt, s[, i=1]) Returns the values packed in string s according to the format string fmt.
size (fmt) Returns the size of a string formatted according to the format string fmt.


Functions

pack (fmt, ...)
Returns a string containing the values packed according to the format string fmt.

Parameters:

  • fmt string Format string.
  • ... Values to pack.

Returns:

    string Packed string.
unpack (fmt, s[, i=1])
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.

Parameters:

  • fmt string Format string.
  • s string String to unpack.
  • i int Initial read position. (default 1)

Returns:

  1. One or more values unpacked from string.
  2. int Next position to read.
size (fmt)
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".

Parameters:

Returns:

    uint Size.
generated by LDoc 1.4.0