Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstruct.tex @ 10123:bc287c6cfa23 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Restructured a bit.
author Guido van Rossum <guido@python.org>
date Mon, 08 Feb 1999 22:27:18 +0000
parents 06717e52068f
children eaca3775b425
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} ---
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8725
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
7694
5e3c9d530bc1 Adjusted an index entry.
Fred Drake <fdrake@acm.org>
parents: 7612
diff changeset
7 \indexii{C@\C{}}{structures}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
9 This module performs conversions between Python values and \C{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 structs represented as Python strings. It uses \dfn{format strings}
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
11 (explained below) as compact descriptions of the lay-out of the \C{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 structs and the intended conversion to/from Python values.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
13
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 The module defines the following exception and functions:
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
7612
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
16
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \begin{excdesc}{error}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 Exception raised on various occasions; argument is a string
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 describing what is wrong.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \end{excdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
22 \begin{funcdesc}{pack}{fmt, v1, v2, \textrm{\ldots}}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 Return a string containing the values
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
24 \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
25 format. The arguments must match the values required by the format
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 exactly.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7694
diff changeset
29 \begin{funcdesc}{unpack}{fmt, string}
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
30 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
31 \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
32 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
33 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
34 \code{len(\var{string})} must equal \code{calcsize(\var{fmt})}).
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
36
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 \begin{funcdesc}{calcsize}{fmt}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 Return the size of the struct (and hence of the string)
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 corresponding to the given format.
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
41
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
42 Format characters have the following meaning; the conversion between
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
43 \C{} and Python values should be obvious given their types:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
8018
011ae71fea96 Lighten up tables.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
45 \begin{tableiii}{c|l|l}{samp}{Format}{C Type}{Python}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 \lineiii{x}{pad byte}{no value}
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
47 \lineiii{c}{\ctype{char}}{string of length 1}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
48 \lineiii{b}{\ctype{signed char}}{integer}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
49 \lineiii{B}{\ctype{unsigned char}}{integer}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
50 \lineiii{h}{\ctype{short}}{integer}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
51 \lineiii{H}{\ctype{unsigned short}}{integer}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
52 \lineiii{i}{\ctype{int}}{integer}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
53 \lineiii{I}{\ctype{unsigned int}}{integer}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
54 \lineiii{l}{\ctype{long}}{integer}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
55 \lineiii{L}{\ctype{unsigned long}}{integer}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
56 \lineiii{f}{\ctype{float}}{float}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
57 \lineiii{d}{\ctype{double}}{float}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
58 \lineiii{s}{\ctype{char[]}}{string}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
59 \lineiii{p}{\ctype{char[]}}{string}
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
60 \lineiii{P}{\ctype{void *}}{integer}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 \end{tableiii}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
62
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
63 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
64 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
65 \code{'hhhh'}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
66
6167
9e432468f756 Ignore whitespace between formats (not internal to a count+format).
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
67 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
68 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
69
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
70 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
71 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
72 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
73 \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
74 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
75 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
76 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
77 string (while \code{'0c'} means 0 characters).
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
78
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
79 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
80 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
81 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
82 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
83 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
84 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
85 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
86
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
87 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
88 value is a Python long integer.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
89
9125
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
90 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
91 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
92 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
93 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
94 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
95 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
96 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
97 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
98
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
99 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
100 and byte order, and properly aligned by skipping pad bytes if
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
101 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
102
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
103 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
104 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
105 according to the following table:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
106
8018
011ae71fea96 Lighten up tables.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
107 \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
108 \lineiii{@}{native}{native}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
109 \lineiii{=}{native}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
110 \lineiii{<}{little-endian}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
111 \lineiii{>}{big-endian}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
112 \lineiii{!}{network (= big-endian)}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
113 \end{tableiii}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
114
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
115 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
116
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
117 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
118 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
119 little-endian).
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
120
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
121 Native size and alignment are determined using the \C{} compiler's
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
122 \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
123 order.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
124
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
125 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
126 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
127 \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
128 \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
129 respectively.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
130
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
131 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
132 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
133 standardized.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
134
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
135 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
136 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
137 little-endian.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
138
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
139 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
140 byte-swapping); use the appropriate choice of \character{<} or
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
141 \character{>}.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
142
9125
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
143 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
144 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
145 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
146 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
147 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
148 \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
149
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
150 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
151 big-endian machine):
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
152
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 6875
diff changeset
153 \begin{verbatim}
4866
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
154 >>> from struct import *
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
155 >>> pack('hhl', 1, 2, 3)
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
156 '\000\001\000\002\000\000\000\003'
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
157 >>> unpack('hhl', '\000\001\000\002\000\000\000\003')
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
158 (1, 2, 3)
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
159 >>> calcsize('hhl')
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
160 8
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
161 >>>
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 6875
diff changeset
162 \end{verbatim}
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
163
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
164 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
165 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
166 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
167 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
168 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
169 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
170
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
171 \begin{seealso}
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
172 \seemodule{array}{packed binary storage of homogeneous data}
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
173 \end{seealso}