Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstruct.tex @ 1590:ac2e5cc29949 legacy-trunk

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