NAME

lib/struct.pir - struct library

DESCRIPTION

See original on http://www.inf.puc-rio.br/~roberto/struct/

NOT UNDER TEST

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:

* First, it may contain a endianness flag, which governs all conversions for that structure. "<" means little-endian; ""> means big-endian. When no endian flag is given, the functions use the machine's native endianness.

* The next optional item is a alignment flag, in the form "!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).

* After those optional flags, the format string contains a sequence of zero or more of the following conversion elements:

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

Functions

All functions are registered inside a table struct.

struct.pack (fmt, d1, d2, ...)

Returns a string containing the values d1, d2, ect. packed according to the format string fmt.STILL INCOMPLETE.

struct.unpack (fmt, s, [i])

Returns the values packed in string saccording 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.STILL INCOMPLETE.

struct.size (fmt)

Returns the size of a string formatted according to the format string fmt. For obvious reasons, the format string cannot contains neither the option s nor the option c0.