summaryrefslogtreecommitdiffstats
path: root/Doc/libstruct.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/libstruct.tex')
-rw-r--r--Doc/libstruct.tex140
1 files changed, 0 insertions, 140 deletions
diff --git a/Doc/libstruct.tex b/Doc/libstruct.tex
deleted file mode 100644
index 5925328..0000000
--- a/Doc/libstruct.tex
+++ /dev/null
@@ -1,140 +0,0 @@
-\section{Built-in Module \module{struct}}
-\label{module-struct}
-\bimodindex{struct}
-\indexii{C@\C{}}{structures}
-
-This module performs conversions between Python values and C
-structs represented as Python strings. It uses \dfn{format strings}
-(explained below) as compact descriptions of the lay-out of the C
-structs and the intended conversion to/from Python values.
-
-The module defines the following exception and functions:
-
-
-\begin{excdesc}{error}
- Exception raised on various occasions; argument is a string
- describing what is wrong.
-\end{excdesc}
-
-\begin{funcdesc}{pack}{fmt, v1, v2, {\rm \ldots}}
- Return a string containing the values
- \code{\var{v1}, \var{v2}, {\rm \ldots}} packed according to the given
- format. The arguments must match the values required by the format
- exactly.
-\end{funcdesc}
-
-\begin{funcdesc}{unpack}{fmt, string}
- Unpack the string (presumably packed by \code{pack(\var{fmt}, {\rm \ldots})})
- according to the given format. The result is a tuple even if it
- contains exactly one item. The string must contain exactly the
- amount of data required by the format (i.e. \code{len(\var{string})} must
- equal \code{calcsize(\var{fmt})}).
-\end{funcdesc}
-
-\begin{funcdesc}{calcsize}{fmt}
- Return the size of the struct (and hence of the string)
- corresponding to the given format.
-\end{funcdesc}
-
-Format characters have the following meaning; the conversion between C
-and Python values should be obvious given their types:
-
-\begin{tableiii}{c|l|l}{samp}{Format}{C Type}{Python}
- \lineiii{x}{pad byte}{no value}
- \lineiii{c}{char}{string of length 1}
- \lineiii{b}{signed char}{integer}
- \lineiii{B}{unsigned char}{integer}
- \lineiii{h}{short}{integer}
- \lineiii{H}{unsigned short}{integer}
- \lineiii{i}{int}{integer}
- \lineiii{I}{unsigned int}{integer}
- \lineiii{l}{long}{integer}
- \lineiii{L}{unsigned long}{integer}
- \lineiii{f}{float}{float}
- \lineiii{d}{double}{float}
- \lineiii{s}{char[]}{string}
-\end{tableiii}
-
-A format character may be preceded by an integral repeat count; e.g.\
-the format string \code{'4h'} means exactly the same as \code{'hhhh'}.
-
-Whitespace characters between formats are ignored; a count and its
-format must not contain whitespace though.
-
-For the \code{'s'} format character, the count is interpreted as the
-size of the string, not a repeat count like for the other format
-characters; e.g. \code{'10s'} means a single 10-byte string, while
-\code{'10c'} means 10 characters. For packing, the string is
-truncated or padded with null bytes as appropriate to make it fit.
-For unpacking, the resulting string always has exactly the specified
-number of bytes. As a special case, \code{'0s'} means a single, empty
-string (while \code{'0c'} means 0 characters).
-
-For the \code{'I'} and \code{'L'} format characters, the return
-value is a Python long integer.
-
-By default, C numbers are represented in the machine's native format
-and byte order, and properly aligned by skipping pad bytes if
-necessary (according to the rules used by the C compiler).
-
-Alternatively, the first character of the format string can be used to
-indicate the byte order, size and alignment of the packed data,
-according to the following table:
-
-\begin{tableiii}{c|l|l}{samp}{Character}{Byte order}{Size and alignment}
- \lineiii{@}{native}{native}
- \lineiii{=}{native}{standard}
- \lineiii{<}{little-endian}{standard}
- \lineiii{>}{big-endian}{standard}
- \lineiii{!}{network (= big-endian)}{standard}
-\end{tableiii}
-
-If the first character is not one of these, \code{'@'} is assumed.
-
-Native byte order is big-endian or little-endian, depending on the
-host system (e.g. Motorola and Sun are big-endian; Intel and DEC are
-little-endian).
-
-Native size and alignment are determined using the C compiler's sizeof
-expression. This is always combined with native byte order.
-
-Standard size and alignment are as follows: no alignment is required
-for any type (so you have to use pad bytes); short is 2 bytes; int and
-long are 4 bytes. Float and double are 32-bit and 64-bit IEEE floating
-point numbers, respectively.
-
-Note the difference between \code{'@'} and \code{'='}: both use native
-byte order, but the size and alignment of the latter is standardized.
-
-The form \code{'!'} is available for those poor souls who claim they
-can't remember whether network byte order is big-endian or
-little-endian.
-
-There is no way to indicate non-native byte order (i.e. force
-byte-swapping); use the appropriate choice of \code{'<'} or
-\code{'>'}.
-
-Examples (all using native byte order, size and alignment, on a
-big-endian machine):
-
-\begin{verbatim}
->>> from struct import *
->>> pack('hhl', 1, 2, 3)
-'\000\001\000\002\000\000\000\003'
->>> unpack('hhl', '\000\001\000\002\000\000\000\003')
-(1, 2, 3)
->>> calcsize('hhl')
-8
->>>
-\end{verbatim}
-%
-Hint: to align the end of a structure to the alignment requirement of
-a particular type, end the format with the code for that type with a
-repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two
-pad bytes at the end, assuming longs are aligned on 4-byte boundaries.
-This only works when native size and alignment are in effect;
-standard size and alignment does not enforce any alignment.
-
-\begin{seealso}
-\seemodule{array}{packed binary storage of homogeneous data}
-\end{seealso}