Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libstruct.tex @ 24042:63fbbed10714 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Simplify HTTPSConnection constructor. See discussion in SF bug 458463.
author Jeremy Hylton <jeremy@alum.mit.edu>
date Fri, 28 Jun 2002 23:38:14 +0000
parents 6046e9546a70
children 0bffca64ccc4 914dd5059f38
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
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
36 exactly the amount of data required by the format
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
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}{}
18069
8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in
Tim Peters <tim.peters@gmail.com>
parents: 16226
diff changeset
56 \lineiv{I}{\ctype{unsigned int}}{long}{}
12223
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}{}
18069
8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in
Tim Peters <tim.peters@gmail.com>
parents: 16226
diff changeset
59 \lineiv{q}{\ctype{long long}}{long}{(1)}
8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in
Tim Peters <tim.peters@gmail.com>
parents: 16226
diff changeset
60 \lineiv{Q}{\ctype{unsigned long long}}{long}{(1)}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
61 \lineiv{f}{\ctype{float}}{float}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
62 \lineiv{d}{\ctype{double}}{float}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
63 \lineiv{s}{\ctype{char[]}}{string}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
64 \lineiv{p}{\ctype{char[]}}{string}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
65 \lineiv{P}{\ctype{void *}}{integer}{}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
66 \end{tableiv}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
67
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
68 \noindent
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
69 Notes:
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
70
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
71 \begin{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
72 \item[(1)]
18069
8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in
Tim Peters <tim.peters@gmail.com>
parents: 16226
diff changeset
73 The \character{q} and \character{Q} conversion codes are available in
8e187740aa96 Initial support for 'q' and 'Q' struct format codes: for now, only in
Tim Peters <tim.peters@gmail.com>
parents: 16226
diff changeset
74 native mode only if the platform C compiler supports C \ctype{long long},
18125
27dd9ec3162c Add a version annotation for the Q and q format codes.
Fred Drake <fdrake@acm.org>
parents: 18084
diff changeset
75 or, on Windows, \ctype{__int64}. They are always available in standard
18084
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
76 modes.
18125
27dd9ec3162c Add a version annotation for the Q and q format codes.
Fred Drake <fdrake@acm.org>
parents: 18084
diff changeset
77 \versionadded{2.2}
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
78 \end{description}
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11224
diff changeset
79
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
81 A format character may be preceded by an integral repeat count. For
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
82 example, the format string \code{'4h'} means exactly the same as
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
83 \code{'hhhh'}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
84
6167
9e432468f756 Ignore whitespace between formats (not internal to a count+format).
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
85 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
86 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
87
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
88 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
89 size of the string, not a repeat count like for the other format
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
90 characters; for example, \code{'10s'} means a single 10-byte string, while
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
91 \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
92 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
93 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
94 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
95 string (while \code{'0c'} means 0 characters).
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
96
19927
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
97 The \character{p} format character encodes a "Pascal string", meaning
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
98 a short variable-length string stored in a fixed number of bytes.
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
99 The count is the total number of bytes stored. The first byte stored is
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
100 the length of the string, or 255, whichever is smaller. The bytes
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
101 of the string follow. If the string passed in to \function{pack()} is too
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
102 long (longer than the count minus 1), only the leading count-1 bytes of the
19928
6046e9546a70 Fixed typo in new 'p' description.
Tim Peters <tim.peters@gmail.com>
parents: 19927
diff changeset
103 string are stored. If the string is shorter than count-1, it is padded
19927
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
104 with null bytes so that exactly count bytes in all are used. Note that
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
105 for \function{unpack()}, the \character{p} format character consumes count
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
106 bytes, but that the string returned can never contain more than 255
2894458877c8 SF bug [#461674] struct 'p' format doesn't work (maybe)
Tim Peters <tim.peters@gmail.com>
parents: 18416
diff changeset
107 characters.
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
108
18084
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
109 For the \character{I}, \character{L}, \character{q} and \character{Q}
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
110 format characters, the return value is a Python long integer.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
111
9125
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
112 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
113 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
114 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
115 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
116 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
117 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
118 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
119 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
120
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
121 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
122 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
123 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
124
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
125 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
126 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
127 according to the following table:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
128
8018
011ae71fea96 Lighten up tables.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
129 \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
130 \lineiii{@}{native}{native}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
131 \lineiii{=}{native}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
132 \lineiii{<}{little-endian}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
133 \lineiii{>}{big-endian}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
134 \lineiii{!}{network (= big-endian)}{standard}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
135 \end{tableiii}
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
136
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
137 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
138
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
139 Native byte order is big-endian or little-endian, depending on the
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
140 host system. For example, Motorola and Sun processors are big-endian;
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
141 Intel and DEC processors are little-endian.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
142
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
143 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
144 \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
145 order.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
146
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
147 Standard size and alignment are as follows: no alignment is required
18084
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
148 for any type (so you have to use pad bytes);
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
149 \ctype{short} is 2 bytes;
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
150 \ctype{int} and \ctype{long} are 4 bytes;
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
151 \ctype{long long} (\ctype{__int64} on Windows) is 8 bytes;
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
152 \ctype{float} and \ctype{double} are 32-bit and 64-bit
bbcdbd8f4469 Added q/Q standard (x-platform 8-byte ints) mode in struct module.
Tim Peters <tim.peters@gmail.com>
parents: 18069
diff changeset
153 IEEE floating point numbers, respectively.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
154
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
155 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
156 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
157 standardized.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
158
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
159 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
160 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
161 little-endian.
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
162
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
163 There is no way to indicate non-native byte order (force
8725
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
164 byte-swapping); use the appropriate choice of \character{<} or
f7976e02b873 Document the 'p' format character.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
165 \character{>}.
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
166
9125
6cd93322b810 Patch by Greg Stein to document the 'P' flag.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
167 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
168 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
169 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
170 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
171 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
172 \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
173
4843
38ae2a0fc4f3 Document the new extensions.
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
174 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
175 big-endian machine):
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
176
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 6875
diff changeset
177 \begin{verbatim}
4866
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
178 >>> from struct import *
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
179 >>> 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
180 '\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
181 >>> 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
182 (1, 2, 3)
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
183 >>> calcsize('hhl')
3960340a3252 Describe standard float/double support.
Guido van Rossum <guido@python.org>
parents: 4843
diff changeset
184 8
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 6875
diff changeset
185 \end{verbatim}
9560
06717e52068f Fix minor nit with respect to conversion.
Fred Drake <fdrake@acm.org>
parents: 9125
diff changeset
186
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 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
188 a particular type, end the format with the code for that type with a
18416
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
189 repeat count of zero. For example, the format \code{'llh0l'}
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
190 specifies two pad bytes at the end, assuming longs are aligned on
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
191 4-byte boundaries. This only works when native size and alignment are
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 18125
diff changeset
192 in effect; standard size and alignment does not enforce any alignment.
7612
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
193
46f2c4fc9e38 Moved solitary "see also" paragraph into a {seealso} environment, and told
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
194 \begin{seealso}
11224
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
195 \seemodule{array}{Packed binary storage of homogeneous data.}
905226471b4c Added additional index entries.
Fred Drake <fdrake@acm.org>
parents: 10642
diff changeset
196 \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
197 \end{seealso}