6.4.2 – Format Strings for Pack and Unpack
The first argument to string.pack
, string.packsize
, and string.unpack
is a format string, which describes the layout of the structure being created or read.
A format string is a sequence of conversion options. The conversion options are as follows:
-
<
: sets little endian -
>
: sets big endian -
=
: sets native endian -
![n]
: sets maximum alignment ton
(default is native alignment) -
b
: a signed byte (char
) -
B
: an unsigned byte (char
) -
h
: a signedshort
(native size) -
H
: an unsignedshort
(native size) -
l
: a signedlong
(native size) -
L
: an unsignedlong
(native size) -
j
: alua_Integer
-
J
: alua_Unsigned
-
T
: asize_t
(native size) -
i[n]
: a signedint
withn
bytes (default is native size) -
I[n]
: an unsignedint
withn
bytes (default is native size) -
f
: afloat
(native size) -
d
: adouble
(native size) -
n
: alua_Number
-
cn
: a fixed-sized string withn
bytes -
z
: a zero-terminated string -
s[n]
: a string preceded by its length coded as an unsigned integer withn
bytes (default is asize_t
) -
x
: one byte of padding -
Xop
: an empty item that aligns according to optionop
(which is otherwise ignored) - '': (empty space) ignored
(A "[n]
" means an optional integral numeral.) Except for padding, spaces, and configurations (options "xX <=>!
"), each option corresponds to an argument (in string.pack
) or a result (in string.unpack
).
For options "!n
", "sn
", "in
", and "In
", n
can be any integer between 1 and 16. All integral options check overflows; string.pack
checks whether the given value fits in the given size; string.unpack
checks whether the read value fits in a Lua integer.
Any format string starts as if prefixed by "!1=
", that is, with maximum alignment of 1 (no alignment) and native endianness.
Alignment works as follows: For each option, the format gets extra padding until the data starts at an offset that is a multiple of the minimum between the option size and the maximum alignment; this minimum must be a power of 2. Options "c
" and "z
" are not aligned; option "s
" follows the alignment of its starting integer.
All padding is filled with zeros by string.pack
(and ignored by string.unpack
).
Please login to continue.