Alcor6L/eLua/pack

From Wikibooks, open books for an open world
Jump to navigation Jump to search

This module allows for arbitrary packing of data into Lua strings and unpacking data from Lua strings. In this way, a string can be used to store data in a platform-indepdendent manner. It is based on the lpack module from Luiz Henrique de Figueiredo (with some minor tweaks).

Both methods of this module (pack and unpack) use a format string to describe how to pack/unpack the data. The format string contains one or more data specifiers, each data specifier is applied to a single variable that must be packed/unpacked. The data specifier has the following general format:

[endianness]<format_specifier>[count]

where:

  • endianness is an optional endian flags that specifies how the numbers that are to be packed/unpacked are stored in memory. It can be:
   '<' for little endian.
   '>' for big endian.
   '=' for native endian (the platform's endian order, default).
  • format_specifier describes what kind of variable will be packed/unpacked. The format specifier is case-sensitive. The possible values of this parameter are summarized in the table below:
   'z' zero-terminated string
   'p' string preceded by length byte
   'P' string preceded by length word
   'a' string preceded by length size_t
   'A' string
   'f' float
   'd' double
   'n' Lua number
   'c' char
   'b' byte = unsigned char
   'h' short
   'H' unsigned short
   'i' int
   'I' unsigned int
   'l' long
   'L' unsigned long
  • count is an optional counter for the format specifier. For example, i5 instructs the code to pack/unpack 5 integer variables, as opposed to i that specifies a single integer variable.

Functions[edit | edit source]

pack.pack[edit | edit source]

Packs variables in a string.

packed = pack.pack( format, val1, val2, ..., valn )
  • format - format specifier (as described here).
  • val1 - first variable to pack.
  • val2 - second variable to pack.
  • valn - nth variable to pack.

Returns:

  • packed - a string containing the packed representation of all variables according to the format.

pack.unpack[edit | edit source]

Unpacks a string

nextpos, val1, val2, ..., valn = pack.unpack( string, format, [ init ] )
  • string - the string to unpack.
  • format - format specifier (as described here).
  • init - (optional) marks where in string the unpacking should start (1 if not specified).

Returns:

  • nextpos - the position in the string after unpacking.
  • val1 - the first unpacked value.
  • val2 - the second unpacked value.
  • valn - the nth unpacked value.