Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstruct.tex @ 17581:c1937faabb23 2.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added support for optional explanation parameter to the \versionadded macro. Refactored do_cmd_versionadded() and do_cmd_versionchanged() to do most of the work in a helper function, with the do_cmd_*() wrappers just supplying a portion of the replacement text.
author Fred Drake <fdrake@acm.org>
date Wed, 18 Apr 2001 17:29:14 +0000
parents c7c404b35f33
children 8e187740aa96
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8725
diff changeset
1 \section{\module{struct} ---
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
2 Interpret strings as packed binary data}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
3 \declaremodule{builtin}{struct}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
4
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
5 \modulesynopsis{Interpret strings as packed binary data.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
6
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
7 \indexii{C}{structures}
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
8 \indexiii{packing}{binary}{data}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
10 This module performs conversions between Python values and C
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 structs represented as Python strings. It uses \dfn{format strings}
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
12 (explained below) as compact descriptions of the lay-out of the C
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
13 structs and the intended conversion to/from Python values. This can
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
14 be used in handling binary data stored in files or from network
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
15 connections, among other sources.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 The module defines the following exception and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18
7612
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
19
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 Exception raised on various occasions; argument is a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 describing what is wrong.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
24
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
25 \begin{funcdesc}{pack}{fmt, v1, v2, \textrm{\ldots}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 Return a string containing the values
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
27 \code{\var{v1}, \var{v2}, \textrm{\ldots}} packed according to the given
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 format. The arguments must match the values required by the format
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 exactly.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7694
diff changeset
32 \begin{funcdesc}{unpack}{fmt, string}
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
33 Unpack the string (presumably packed by \code{pack(\var{fmt},
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
34 \textrm{\ldots})}) according to the given format. The result is a
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
35 tuple even if it contains exactly one item. The string must contain
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
36 exactly the amount of data required by the format (i.e.
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
37 \code{len(\var{string})} must equal \code{calcsize(\var{fmt})}).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 \begin{funcdesc}{calcsize}{fmt}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 Return the size of the struct (and hence of the string)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 corresponding to the given format.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
45 Format characters have the following meaning; the conversion between
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
46 C and Python values should be obvious given their types:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
47
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
48 \begin{tableiv}{c|l|l|c}{samp}{Format}{C Type}{Python}{Notes}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
49 \lineiv{x}{pad byte}{no value}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
50 \lineiv{c}{\ctype{char}}{string of length 1}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
51 \lineiv{b}{\ctype{signed char}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
52 \lineiv{B}{\ctype{unsigned char}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
53 \lineiv{h}{\ctype{short}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
54 \lineiv{H}{\ctype{unsigned short}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
55 \lineiv{i}{\ctype{int}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
56 \lineiv{I}{\ctype{unsigned int}}{long}{(1)}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
57 \lineiv{l}{\ctype{long}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
58 \lineiv{L}{\ctype{unsigned long}}{long}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
59 \lineiv{f}{\ctype{float}}{float}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
60 \lineiv{d}{\ctype{double}}{float}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
61 \lineiv{s}{\ctype{char[]}}{string}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
62 \lineiv{p}{\ctype{char[]}}{string}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
63 \lineiv{P}{\ctype{void *}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
64 \end{tableiv}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
65
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
66 \noindent
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
67 Notes:
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
68
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
69 \begin{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
70 \item[(1)]
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
71 The \character{I} conversion code will convert to a Python long if
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
72 the C \ctype{int} is the same size as a C \ctype{long}, which is
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
73 typical on most modern systems. If a C \ctype{int} is smaller than
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
74 a C \ctype{long}, an Python integer will be created instead.
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
75 \end{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
76
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
77
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
78 A format character may be preceded by an integral repeat count;
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
79 e.g.\ the format string \code{'4h'} means exactly the same as
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
80 \code{'hhhh'}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
81
6167
9e432468f756 Ignore whitespace between formats (not internal to a count+format).
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
82 Whitespace characters between formats are ignored; a count and its
9e432468f756 Ignore whitespace between formats (not internal to a count+format).
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
83 format must not contain whitespace though.
9e432468f756 Ignore whitespace between formats (not internal to a count+format).
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
84
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
85 For the \character{s} format character, the count is interpreted as the
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
86 size of the string, not a repeat count like for the other format
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
87 characters; e.g. \code{'10s'} means a single 10-byte string, while
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
88 \code{'10c'} means 10 characters. For packing, the string is
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
89 truncated or padded with null bytes as appropriate to make it fit.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
90 For unpacking, the resulting string always has exactly the specified
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
91 number of bytes. As a special case, \code{'0s'} means a single, empty
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
92 string (while \code{'0c'} means 0 characters).
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
93
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
94 The \character{p} format character can be used to encode a Pascal
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
95 string. The first byte is the length of the stored string, with the
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
96 bytes of the string following. If count is given, it is used as the
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
97 total number of bytes used, including the length byte. If the string
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
98 passed in to \function{pack()} is too long, the stored representation
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
99 is truncated. If the string is too short, padding is used to ensure
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
100 that exactly enough bytes are used to satisfy the count.
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
101
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
102 For the \character{I} and \character{L} format characters, the return
4878
a9e7e0ccaa4a 'I' and 'L' now always return a Python long.
Guido van Rossum <guido@python.org>
parents: 4866
diff changeset
103 value is a Python long integer.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
104
9125
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
105 For the \character{P} format character, the return value is a Python
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
106 integer or long integer, depending on the size needed to hold a
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
107 pointer when it has been cast to an integer type. A \NULL{} pointer will
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
108 always be returned as the Python integer \code{0}. When packing pointer-sized
9125
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
109 values, Python integer or long integer objects may be used. For
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
110 example, the Alpha and Merced processors use 64-bit pointer values,
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
111 meaning a Python long integer will be used to hold the pointer; other
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
112 platforms use 32-bit pointers and will use a Python integer.
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
113
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
114 By default, C numbers are represented in the machine's native format
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
115 and byte order, and properly aligned by skipping pad bytes if
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
116 necessary (according to the rules used by the C compiler).
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
117
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
118 Alternatively, the first character of the format string can be used to
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
119 indicate the byte order, size and alignment of the packed data,
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
120 according to the following table:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121
8018
011ae71fea96 Lighten up tables.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
122 \begin{tableiii}{c|l|l}{samp}{Character}{Byte order}{Size and alignment}
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
123 \lineiii{@}{native}{native}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
124 \lineiii{=}{native}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
125 \lineiii{<}{little-endian}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
126 \lineiii{>}{big-endian}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
127 \lineiii{!}{network (= big-endian)}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
128 \end{tableiii}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
129
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
130 If the first character is not one of these, \character{@} is assumed.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
131
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
132 Native byte order is big-endian or little-endian, depending on the
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
133 host system (e.g. Motorola and Sun are big-endian; Intel and DEC are
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
134 little-endian).
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
135
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
136 Native size and alignment are determined using the C compiler's
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
137 \keyword{sizeof} expression. This is always combined with native byte
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
138 order.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
139
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
140 Standard size and alignment are as follows: no alignment is required
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
141 for any type (so you have to use pad bytes); \ctype{short} is 2 bytes;
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
142 \ctype{int} and \ctype{long} are 4 bytes. \ctype{float} and
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
143 \ctype{double} are 32-bit and 64-bit IEEE floating point numbers,
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
144 respectively.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
145
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
146 Note the difference between \character{@} and \character{=}: both use
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
147 native byte order, but the size and alignment of the latter is
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
148 standardized.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
149
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
150 The form \character{!} is available for those poor souls who claim they
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
151 can't remember whether network byte order is big-endian or
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
152 little-endian.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
153
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
154 There is no way to indicate non-native byte order (i.e. force
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
155 byte-swapping); use the appropriate choice of \character{<} or
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
156 \character{>}.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
157
9125
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
158 The \character{P} format character is only available for the native
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
159 byte ordering (selected as the default or with the \character{@} byte
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
160 order character). The byte order character \character{=} chooses to
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
161 use little- or big-endian ordering based on the host system. The
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
162 struct module does not interpret this as native ordering, so the
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
163 \character{P} format is not available.
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
164
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
165 Examples (all using native byte order, size and alignment, on a
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
166 big-endian machine):
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
167
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 6875
diff changeset
168 \begin{verbatim}
4866
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
169 >>> from struct import *
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
170 >>> pack('hhl', 1, 2, 3)
16226
c7c404b35f33 Show '\011', '\012', and '\015' as '\t', '\n', '\r' in strings.
Ka-Ping Yee <ping@zesty.ca>
parents: 12223
diff changeset
171 '\x00\x01\x00\x02\x00\x00\x00\x03'
c7c404b35f33 Show '\011', '\012', and '\015' as '\t', '\n', '\r' in strings.
Ka-Ping Yee <ping@zesty.ca>
parents: 12223
diff changeset
172 >>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
4866
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
173 (1, 2, 3)
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
174 >>> calcsize('hhl')
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
175 8
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 6875
diff changeset
176 \end{verbatim}
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
177
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 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
179 a particular type, end the format with the code for that type with a
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1471
diff changeset
180 repeat count of zero, e.g.\ the format \code{'llh0l'} specifies two
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
181 pad bytes at the end, assuming longs are aligned on 4-byte boundaries.
7612
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
182 This only works when native size and alignment are in effect;
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
183 standard size and alignment does not enforce any alignment.
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
184
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
185 \begin{seealso}
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
186 \seemodule{array}{Packed binary storage of homogeneous data.}
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
187 \seemodule{xdrlib}{Packing and unpacking of XDR data.}
7612
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
188 \end{seealso}