LuaCheia Logo  

LuaCheia Reference Manual

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.

Return to main site

Introduction

 » Writing LuaCheia modules

Module Reference

 » bit
 » cgi
 » fuzzy
 » md5
 » pack
 » rex
 » SDL
 » shelve
 » sqlite

Appendices

 » Module path conventions
 » Module names
 » Application Binary Interface
 » Credits