pack
Synopsis
| cheia.load “pack” |
|
| |
| packed_data = pack.pack(format, data1, data2, ...) |
|
| ... |
|
| data1, data2, ... = pack.unpack(format, packed_data) |
|
|
Description
This module provides pack and unpack functions similar to those
found in Perl. The pack.pack function is similar in nature to the
string.format function, or C's sprintf(): it takes a format
string followed by a number of data items, and returns a string which
contains the data items encoded according to the format string. Where
string.format is intended to produce human-readable output,
pack.pack is intended to produce machine-readable output, and as
such it has a corresponding pack.unpack function which interprets
an encoded string to return the original data items.
Note: The pack module is primarily intended for interfacing with
external programs and systems. It provides no guarantee that data packed
in a certain way can be meaningfully unpacked. Custom binary data
formats are increasingly being obsoleted in favour of self-describing
formats. For ‘packing’ Lua data, the Module shelve module may be more
appropriate.
The following control characters are defined:
|
z |
A zero-terminated string. |
|
p |
A string preceded by a length byte (unsigned char). |
|
P |
A string preceded by a length word (unsigned short). |
|
a |
A string preceded by a length size_t. |
|
A |
An unterminated string (see below). |
|
f |
A machine float. |
|
d |
A machine double. |
|
n |
A lua_Number (typically a double). |
|
c |
A char. |
|
b |
A byte (unsigned char). |
|
n |
A machine short. |
|
H |
A machine unsigned short. |
|
i |
A machine int. |
|
I |
A machine unsigned int. |
|
l |
A machine long. |
|
L |
A machine unsigned long.
|
|
Any character may be followed by a number which as treated as a
repetition count. As an exception, when unpacking, the number
following an A is treated as the string length. The format string
may also contain spaces and commas, which are ignored.
Examples
Pack and string and then unpack it a different way. Note the trick of
relying on the fact that Lua strings are always 0-terminated during
unpacking.
| x = pack.pack(“A3b”, “Hello”, “, ”, “world”, 33) |
|
| print(x) |
» Hello, world! |
| print(table.concat({ pack.unpack(x, “A2Iz”) }, “:”)) |
» 15:He:745499756: world! |
|
Reference
- pack.pack(format, ...)
-
Packs its parameters according to format and returns the
result.
| Parameters: |
| format : string
|
The format string.
|
| ... : strings/numbers
|
Values to pack.
|
| Returns: |
| string
|
Packed string.
|
- pack.unpack(packed, format, init)
-
Unpacks packed according to format and returns the resulting
values. The extra initial return can be fed back in as init to
continue unpacking the string.
| Parameters: |
| packed : string
|
The packed string.
|
| format : string
|
The format string.
|
| init : number
|
Index (1-based) of charcter to start with.
|
| Returns: |
| number
|
The index of the next charcter to read.
|
| ...
|
The unpacked values.
|
Issues
Unintuitive argument order for unpack? Inconsistent with Perl, and
with C scanf().
See also
None.
Revision history
Added in LuaCheia 5.0.
Credits
Lua module written by Luiz Henrique de Figueiredo with
contributions from Ignacio Castaño.
Modifications for LuaCheia by Thatcher Ulrich.
Documentation for LuaCheia by Jamie Webb.
|
