The Struct class offers basic facilities to convert Lua values to and from C-style structs in binary Lua strings. This is based on Roberto Ierusalimschy’s Lua struct library found in http://www.inf.puc-rio.br/~roberto/struct/, with some minor modifications as follows:
UInt64being packed/unpacked, using e/E.
All but the first of those changes are based on an email from Flemming Madsen, on the lua-users mailing list, which can be found here.
The main functions are
Struct.pack, which packs multiple Lua values into a struct-like
Lua binary string; and
Struct.unpack, which unpacks multiple Lua values from a given
struct-like Lua binary string. There are some additional helper functions available as well.
All functions in the Struct library are called as static member functions, not object methods, so they are invoked as "Struct.pack(…)" instead of "object:pack(…)".
The fist argument to several of the
Struct 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 endianness and the current alignment requirements. Initially, the
current endianness 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 supported elements in the format string are as follows:
!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 (i.e., network-order).
<’ 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.
e’ signed 8-byte Integer (64-bits, long long), to/from a
E’ unsigned 8-byte Integer (64-bits, long long), to/from a
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.
xn’ pad to n number of bytes, default 1.
Xn’ pad to n alignment, default MAXALIGN.
(’ to stop assigning items, and ‘
)’ start assigning (padding when packing).
=’ to return the current position / offset.
Returns a string containing the values arg1, arg2, etc. packed/encoded according to the format string.
The packed binary Lua string, plus any positions due to = being used in format.
Unpacks/decodes multiple Lua values from a given struct-like binary Lua string. The number of returned values depends on the format given, plus an additional value of the position where it stopped reading is returned.
One or more values based on format, plus the position it stopped unpacking.
Returns the length of a binary string that would be consumed/handled by the given format string.
The size number
Returns the number of Lua values contained in the given format string. This will be the number of returned values from a call to Struct.unpack() not including the extra return value of offset position. (i.e., Struct.values() does not count that extra return value) This will also be the number of arguments Struct.pack() expects, not including the format string argument.
The number of values
Converts the passed-in binary string to a hex-ascii string.
The Lua hex-ascii string
Converts the passed-in hex-ascii string to a binary string.
The Lua binary string