Doc/lib/libstruct.tex

   1 \section{Built-in Module \sectcode{struct}}
   2 \bimodindex{struct}
   3 \indexii{C}{structures}
   4
   5 This module performs conversions between Python values and C
   6 structs represented as Python strings.  It uses \dfn{format strings}
   7 (explained below) as compact descriptions of the lay-out of the C
   8 structs and the intended conversion to/from Python values.
   9
  10 See also built-in module \code{array}.
  11 \bimodindex{array}
  12
  13 The module defines the following exception and functions:
  14
  15 \renewcommand{\indexsubitem}{(in module struct)}
  16 \begin{excdesc}{error}
  17   Exception raised on various occasions; argument is a string
  18   describing what is wrong.
  19 \end{excdesc}
  20
  21 \begin{funcdesc}{pack}{fmt\, v1\, v2\, {\rm \ldots}}
  22   Return a string containing the values
  23   \code{\var{v1}, \var{v2}, {\rm \ldots}} packed according to the given
  24   format.  The arguments must match the values required by the format
  25   exactly.
  26 \end{funcdesc}
  27
  28 \begin{funcdesc}{unpack}{fmt\, string}
  29   Unpack the string (presumably packed by \code{pack(\var{fmt}, {\rm \ldots})})
  30   according to the given format.  The result is a tuple even if it
  31   contains exactly one item.  The string must contain exactly the
  32   amount of data required by the format (i.e.  \code{len(\var{string})} must
  33   equal \code{calcsize(\var{fmt})}).
  34 \end{funcdesc}
  35
  36 \begin{funcdesc}{calcsize}{fmt}
  37   Return the size of the struct (and hence of the string)
  38   corresponding to the given format.
  39 \end{funcdesc}
  40
  41 Format characters have the following meaning; the conversion between C
  42 and Python values should be obvious given their types:
  43
  44 \begin{tableiii}{|c|l|l|}{samp}{Format}{C}{Python}
  45   \lineiii{x}{pad byte}{no value}
  46   \lineiii{c}{char}{string of length 1}
  47   \lineiii{b}{signed char}{integer}
  48   \lineiii{h}{short}{integer}
  49   \lineiii{i}{int}{integer}
  50   \lineiii{l}{long}{integer}
  51   \lineiii{f}{float}{float}
  52   \lineiii{d}{double}{float}
  53 \end{tableiii}
  54
  55 A format character may be preceded by an integral repeat count; e.g.\
  56 the format string \code{'4h'} means exactly the same as \code{'hhhh'}.
  57
  58 C numbers are represented in the machine's native format and byte
  59 order, and properly aligned by skipping pad bytes if necessary
  60 (according to the rules used by the C compiler).
  61
  62 Examples (all on a big-endian machine):
  63
  64 \bcode\begin{verbatim}
  65 pack('hhl', 1, 2, 3) == '\000\001\000\002\000\000\000\003'
  66 unpack('hhl', '\000\001\000\002\000\000\000\003') == (1, 2, 3)
  67 calcsize('hhl') == 8
  68 \end{verbatim}\ecode
  69
  70 Hint: to align the end of a structure to the alignment requirement of
  71 a particular type, end the format with the code for that type with a
  72 repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two
  73 pad bytes at the end, assuming longs are aligned on 4-byte boundaries.
  74
  75 (More format characters are planned, e.g.\ \code{'s'} for character
  76 arrays, upper case for unsigned variants, and a way to specify the
  77 byte order, which is useful for [de]constructing network packets and
  78 reading/writing portable binary file formats like TIFF and AIFF.)