This library 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 fist argument to both functions is a format string, which describes the layout of the structure. The format string has the following syntax:
"<"
means little-endian;
">"
means big-endian.
When no endian flag is given,
the functions use the machine's native endianness.
"!n"
,
where n is the maximum required alignment
(necessarily a power of 2).
An absent n means the machine's native alignment.
An absent alignment flag means no alignment at all
(which is the same as !1
).
"x"
a padding 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).
"in"
a signed integer with n bytes
(where n must be a power of 2).
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.
struct
.
struct.pack (fmt, d1, d2, ...)
Returns a string containing the values d1
, d2
, etc.
packed according to the format string fmt
.
struct.c
as a
dynamic library.
In Linux you can use the following command:
> gcc -Wall -O2 -shared -o struct.so struct.cIn Mac, you should define the environment variable
MACOSX_DEPLOYMENT_TARGET
as 10.3
and then write
> gcc -bundle -undefined dynamic_lookup -Wall -O2 -o struct.so struct.c
In Windows, you must generate a DLL exporting the single
symbol luaopen_struct
.
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]; };in Linux/gcc/Pentium (little-endian, maximum alignment of 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 may 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)Notice 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 table.insert(a, d) end
To pack a string in a fixed-width field with 10 characters padded with blanks, do as follows:
x = struct.pack("c10", s .. string.rep(" ", 10))