Mercurial > cpython-lru_cache-weakref

annotate Doc/library/struct.rst @ 79675:c0a2294de787 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16199: Backport 2to3 typo fix from 3.2.
author Chris Jerdonek <chris.jerdonek@gmail.com>
date Thu, 11 Oct 2012 16:15:46 -0700
parents a36666c52115
children f51ca196d77a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 :mod:`struct` --- Interpret strings as packed binary data
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3 =========================================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 .. module:: struct
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 :synopsis: Interpret strings as packed binary data.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9 pair: C; structures
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10 triple: packing; binary; data
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 This module performs conversions between Python values and C structs represented
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
13 as Python strings. This can be used in handling binary data stored in files or
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
14 from network connections, among other sources. It uses
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
15 :ref:`struct-format-strings` as compact descriptions of the layout of the C
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
16 structs and the intended conversion to/from Python values.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
17
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
18 .. note::
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
19
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
20 By default, the result of packing a given C struct includes pad bytes in
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
21 order to maintain proper alignment for the C types involved; similarly,
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
22 alignment is taken into account when unpacking. This behavior is chosen so
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
23 that the bytes of a packed struct correspond exactly to the layout in memory
62332
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
24 of the corresponding C struct. To handle platform-independent data formats
72196
901c1f025d31 Avoid using the default reST role. Makes Doc/tools/rstlint.py happy.
Éric Araujo <merwok@netwok.org>
parents: 71383
diff changeset
25 or omit implicit pad bytes, use ``standard`` size and alignment instead of
901c1f025d31 Avoid using the default reST role. Makes Doc/tools/rstlint.py happy.
Éric Araujo <merwok@netwok.org>
parents: 71383
diff changeset
26 ``native`` size and alignment: see :ref:`struct-alignment` for details.
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
27
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
28 Functions and Exceptions
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
29 ------------------------
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 The module defines the following exception and functions:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 .. exception:: error
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
36 Exception raised on various occasions; argument is a string describing what
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
37 is wrong.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 .. function:: pack(fmt, v1, v2, ...)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 Return a string containing the values ``v1, v2, ...`` packed according to the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 given format. The arguments must match the values required by the format
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 exactly.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47 .. function:: pack_into(fmt, buffer, offset, v1, v2, ...)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
49 Pack the values ``v1, v2, ...`` according to the given format, write the
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
50 packed bytes into the writable *buffer* starting at *offset*. Note that the
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
51 offset is a required argument.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56 .. function:: unpack(fmt, string)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 Unpack the string (presumably packed by ``pack(fmt, ...)``) according to the
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
59 given format. The result is a tuple even if it contains exactly one item.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
60 The string must contain exactly the amount of data required by the format
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 (``len(string)`` must equal ``calcsize(fmt)``).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 .. function:: unpack_from(fmt, buffer[,offset=0])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
56805
c8630f730907 Merged revisions 70171,70183,70290,70292,70315,70438,70464 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47229
diff changeset
66 Unpack the *buffer* according to the given format. The result is a tuple even
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
67 if it contains exactly one item. The *buffer* must contain at least the
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
68 amount of data required by the format (``len(buffer[offset:])`` must be at
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
69 least ``calcsize(fmt)``).
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
73
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74 .. function:: calcsize(fmt)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 Return the size of the struct (and hence of the string) corresponding to the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 given format.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
79 .. _struct-format-strings:
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
80
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
81 Format Strings
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
82 --------------
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
83
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
84 Format strings are the mechanism used to specify the expected layout when
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
85 packing and unpacking data. They are built up from :ref:`format-characters`,
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
86 which specify the type of data being packed/unpacked. In addition, there are
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
87 special characters for controlling the :ref:`struct-alignment`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
89
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
90 .. _struct-alignment:
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
91
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
92 Byte Order, Size, and Alignment
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
93 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
94
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
95 By default, C types are represented in the machine's native format and byte
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 order, and properly aligned by skipping pad bytes if necessary (according to the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 rules used by the C compiler).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 Alternatively, the first character of the format string can be used to indicate
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 the byte order, size and alignment of the packed data, according to the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 following table:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
62332
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
103 +-----------+------------------------+----------+-----------+
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
104 | Character | Byte order | Size | Alignment |
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
105 +===========+========================+==========+===========+
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
106 | ``@`` | native | native | native |
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
107 +-----------+------------------------+----------+-----------+
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
108 | ``=`` | native | standard | none |
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
109 +-----------+------------------------+----------+-----------+
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
110 | ``<`` | little-endian | standard | none |
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
111 +-----------+------------------------+----------+-----------+
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
112 | ``>`` | big-endian | standard | none |
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
113 +-----------+------------------------+----------+-----------+
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
114 | ``!`` | network (= big-endian) | standard | none |
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
115 +-----------+------------------------+----------+-----------+
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 If the first character is not one of these, ``'@'`` is assumed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118
59002
c254e54ac856 #6414: clarify description of processor endianness.
Andrew M. Kuchling <amk@amk.ca>
parents: 56805
diff changeset
119 Native byte order is big-endian or little-endian, depending on the host
c254e54ac856 #6414: clarify description of processor endianness.
Andrew M. Kuchling <amk@amk.ca>
parents: 56805
diff changeset
120 system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
c254e54ac856 #6414: clarify description of processor endianness.
Andrew M. Kuchling <amk@amk.ca>
parents: 56805
diff changeset
121 Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature
c254e54ac856 #6414: clarify description of processor endianness.
Andrew M. Kuchling <amk@amk.ca>
parents: 56805
diff changeset
122 switchable endianness (bi-endian). Use ``sys.byteorder`` to check the
c254e54ac856 #6414: clarify description of processor endianness.
Andrew M. Kuchling <amk@amk.ca>
parents: 56805
diff changeset
123 endianness of your system.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 Native size and alignment are determined using the C compiler's
44383
3625234bf3d2 Some cleanup in the docs.
Georg Brandl <georg@python.org>
parents: 42775
diff changeset
126 ``sizeof`` expression. This is always combined with native byte order.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127
62332
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
128 Standard size depends only on the format character; see the table in
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
129 the :ref:`format-characters` section.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 Note the difference between ``'@'`` and ``'='``: both use native byte order, but
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 the size and alignment of the latter is standardized.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 The form ``'!'`` is available for those poor souls who claim they can't remember
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 whether network byte order is big-endian or little-endian.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 There is no way to indicate non-native byte order (force byte-swapping); use the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 appropriate choice of ``'<'`` or ``'>'``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
140 Notes:
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
141
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
142 (1) Padding is only automatically added between successive structure members.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
143 No padding is added at the beginning or the end of the encoded struct.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
144
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
145 (2) No padding is added when using non-native size and alignment, e.g.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
146 with '<', '>', '=', and '!'.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
147
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
148 (3) To align the end of a structure to the alignment requirement of a
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
149 particular type, end the format with the code for that type with a repeat
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
150 count of zero. See :ref:`struct-examples`.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
151
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
152
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
153 .. _format-characters:
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
154
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
155 Format Characters
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
156 ^^^^^^^^^^^^^^^^^
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
157
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
158 Format characters have the following meaning; the conversion between C and
62640
b88da4f77f68 Merged revisions 82379 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62332
diff changeset
159 Python values should be obvious given their types. The 'Standard size' column
b88da4f77f68 Merged revisions 82379 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62332
diff changeset
160 refers to the size of the packed value in bytes when using standard size; that
b88da4f77f68 Merged revisions 82379 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62332
diff changeset
161 is, when the format string starts with one of ``'<'``, ``'>'``, ``'!'`` or
b88da4f77f68 Merged revisions 82379 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62332
diff changeset
162 ``'='``. When using native size, the size of the packed value is
b88da4f77f68 Merged revisions 82379 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62332
diff changeset
163 platform-dependent.
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
164
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
165 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
166 | Format | C Type | Python type | Standard size | Notes |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
167 +========+==========================+====================+================+============+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
168 | ``x`` | pad byte | no value | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
169 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
170 | ``c`` | :c:type:`char` | string of length 1 | 1 | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
171 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
172 | ``b`` | :c:type:`signed char` | integer | 1 | \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
173 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
174 | ``B`` | :c:type:`unsigned char` | integer | 1 | \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
175 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
176 | ``?`` | :c:type:`_Bool` | bool | 1 | \(1) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
177 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
178 | ``h`` | :c:type:`short` | integer | 2 | \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
179 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
180 | ``H`` | :c:type:`unsigned short` | integer | 2 | \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
181 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
182 | ``i`` | :c:type:`int` | integer | 4 | \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
183 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
184 | ``I`` | :c:type:`unsigned int` | integer | 4 | \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
185 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
186 | ``l`` | :c:type:`long` | integer | 4 | \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
187 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
188 | ``L`` | :c:type:`unsigned long` | integer | 4 | \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
189 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
190 | ``q`` | :c:type:`long long` | integer | 8 | \(2), \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
191 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
192 | ``Q`` | :c:type:`unsigned long | integer | 8 | \(2), \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
193 | | long` | | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
194 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
195 | ``f`` | :c:type:`float` | float | 4 | \(4) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
196 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
197 | ``d`` | :c:type:`double` | float | 8 | \(4) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
198 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
199 | ``s`` | :c:type:`char[]` | string | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
200 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
201 | ``p`` | :c:type:`char[]` | string | | |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
202 +--------+--------------------------+--------------------+----------------+------------+
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
203 | ``P`` | :c:type:`void \*` | integer | | \(5), \(3) |
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
204 +--------+--------------------------+--------------------+----------------+------------+
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
205
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
206 Notes:
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
207
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
208 (1)
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
209 The ``'?'`` conversion code corresponds to the :c:type:`_Bool` type defined by
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
210 C99. If this type is not available, it is simulated using a :c:type:`char`. In
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
211 standard mode, it is always represented by one byte.
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
212
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
213 .. versionadded:: 2.6
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
214
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
215 (2)
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
216 The ``'q'`` and ``'Q'`` conversion codes are available in native mode only if
74395
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
217 the platform C compiler supports C :c:type:`long long`, or, on Windows,
74ff71b2f53d update to new C roles and directives
Sandro Tosi <sandro.tosi@gmail.com>
parents: 72196
diff changeset
218 :c:type:`__int64`. They are always available in standard modes.
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
219
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
220 .. versionadded:: 2.2
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
221
62332
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
222 (3)
62306
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
223 When attempting to pack a non-integer using any of the integer conversion
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
224 codes, if the non-integer has a :meth:`__index__` method then that method is
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
225 called to convert the argument to an integer before packing. If no
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
226 :meth:`__index__` method exists, or the call to :meth:`__index__` raises
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
227 :exc:`TypeError`, then the :meth:`__int__` method is tried. However, the use
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
228 of :meth:`__int__` is deprecated, and will raise :exc:`DeprecationWarning`.
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
229
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
230 .. versionchanged:: 2.7
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
231 Use of the :meth:`__index__` method for non-integers is new in 2.7.
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
232
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
233 .. versionchanged:: 2.7
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
234 Prior to version 2.7, not all integer conversion codes would use the
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
235 :meth:`__int__` method to convert, and :exc:`DeprecationWarning` was
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
236 raised only for float arguments.
0a55ade6d857 Issue #8469: Add standard sizes to table in struct documentation; additional
Mark Dickinson <dickinsm@gmail.com>
parents: 60563
diff changeset
237
62331
6f9b0c240191 Issue #8469: Further clarifications and improvements to struct module
Mark Dickinson <dickinsm@gmail.com>
parents: 62306
diff changeset
238 (4)
62332
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
239 For the ``'f'`` and ``'d'`` conversion codes, the packed representation uses
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
240 the IEEE 754 binary32 (for ``'f'``) or binary64 (for ``'d'``) format,
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
241 regardless of the floating-point format used by the platform.
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
242
62331
6f9b0c240191 Issue #8469: Further clarifications and improvements to struct module
Mark Dickinson <dickinsm@gmail.com>
parents: 62306
diff changeset
243 (5)
62332
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
244 The ``'P'`` format character is only available for the native byte ordering
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
245 (selected as the default or with the ``'@'`` byte order character). The byte
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
246 order character ``'='`` chooses to use little- or big-endian ordering based
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
247 on the host system. The struct module does not interpret this as native
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
248 ordering, so the ``'P'`` format is not available.
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
249
8f3fcc239781 Merged revisions 81992 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 62308
diff changeset
250
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
251 A format character may be preceded by an integral repeat count. For example,
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
252 the format string ``'4h'`` means exactly the same as ``'hhhh'``.
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
253
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
254 Whitespace characters between formats are ignored; a count and its format must
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
255 not contain whitespace though.
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
256
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
257 For the ``'s'`` format character, the count is interpreted as the size of the
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
258 string, not a repeat count like for the other format characters; for example,
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
259 ``'10s'`` means a single 10-byte string, while ``'10c'`` means 10 characters.
71383
4d5c2843c71e merge from 3.2.
Senthil Kumaran <senthil@uthcode.com>
parents: 70167
diff changeset
260 If a count is not given, it defaults to 1. For packing, the string is
4d5c2843c71e merge from 3.2.
Senthil Kumaran <senthil@uthcode.com>
parents: 70167
diff changeset
261 truncated or padded with null bytes as appropriate to make it fit. For
4d5c2843c71e merge from 3.2.
Senthil Kumaran <senthil@uthcode.com>
parents: 70167
diff changeset
262 unpacking, the resulting string always has exactly the specified number of
4d5c2843c71e merge from 3.2.
Senthil Kumaran <senthil@uthcode.com>
parents: 70167
diff changeset
263 bytes. As a special case, ``'0s'`` means a single, empty string (while
4d5c2843c71e merge from 3.2.
Senthil Kumaran <senthil@uthcode.com>
parents: 70167
diff changeset
264 ``'0c'`` means 0 characters).
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
265
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
266 The ``'p'`` format character encodes a "Pascal string", meaning a short
65126
64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62639
diff changeset
267 variable-length string stored in a *fixed number of bytes*, given by the count.
64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62639
diff changeset
268 The first byte stored is the length of the string, or 255, whichever is smaller.
64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62639
diff changeset
269 The bytes of the string follow. If the string passed in to :func:`pack` is too
64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62639
diff changeset
270 long (longer than the count minus 1), only the leading ``count-1`` bytes of the
64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62639
diff changeset
271 string are stored. If the string is shorter than ``count-1``, it is padded with
64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62639
diff changeset
272 null bytes so that exactly count bytes in all are used. Note that for
64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62639
diff changeset
273 :func:`unpack`, the ``'p'`` format character consumes count bytes, but that the
64989b03398c Merged revisions 82757-82758,82760-82764 via svnmerge from
Georg Brandl <georg@python.org>
parents: 62639
diff changeset
274 string returned can never contain more than 255 characters.
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
275
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
276 For the ``'P'`` format character, the return value is a Python integer or long
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
277 integer, depending on the size needed to hold a pointer when it has been cast to
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
278 an integer type. A *NULL* pointer will always be returned as the Python integer
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
279 ``0``. When packing pointer-sized values, Python integer or long integer objects
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
280 may be used. For example, the Alpha and Merced processors use 64-bit pointer
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
281 values, meaning a Python long integer will be used to hold the pointer; other
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
282 platforms use 32-bit pointers and will use a Python integer.
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
283
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
284 For the ``'?'`` format character, the return value is either :const:`True` or
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
285 :const:`False`. When packing, the truth value of the argument object is used.
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
286 Either 0 or 1 in the native or standard bool representation will be packed, and
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
287 any non-zero value will be True when unpacking.
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
288
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
289
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
290
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
291 .. _struct-examples:
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
292
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
293 Examples
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
294 ^^^^^^^^
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
295
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
296 .. note::
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
297 All examples assume a native byte order, size, and alignment with a
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
298 big-endian machine.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
299
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
300 A basic example of packing/unpacking three integers::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
301
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
302 >>> from struct import *
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
303 >>> pack('hhl', 1, 2, 3)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
304 '\x00\x01\x00\x02\x00\x00\x00\x03'
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
305 >>> unpack('hhl', '\x00\x01\x00\x02\x00\x00\x00\x03')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
306 (1, 2, 3)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
307 >>> calcsize('hhl')
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
308 8
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
309
47229
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
310 Unpacked fields can be named by assigning them to variables or by wrapping
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
311 the result in a named tuple::
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
312
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
313 >>> record = 'raymond \x32\x12\x08\x01\x08'
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
314 >>> name, serialnum, school, gradelevel = unpack('<10sHHb', record)
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
315
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
316 >>> from collections import namedtuple
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
317 >>> Student = namedtuple('Student', 'name serialnum school gradelevel')
70167
874309ce6e62 #12093: fix typo in struct doc. Patch by Sandro Tosi.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 68256
diff changeset
318 >>> Student._make(unpack('<10sHHb', record))
47229
c5a85e4f9e86 Issue 2909: show how to name unpacked fields.
Raymond Hettinger <python@rcn.com>
parents: 46555
diff changeset
319 Student(name='raymond ', serialnum=4658, school=264, gradelevel=8)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
320
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
321 The ordering of format characters may have an impact on size since the padding
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
322 needed to satisfy alignment requirements is different::
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
323
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
324 >>> pack('ci', '*', 0x12131415)
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
325 '*\x00\x00\x00\x12\x13\x14\x15'
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
326 >>> pack('ic', 0x12131415, '*')
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
327 '\x12\x13\x14\x15*'
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
328 >>> calcsize('ci')
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
329 8
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
330 >>> calcsize('ic')
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
331 5
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
332
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
333 The following format ``'llh0l'`` specifies two pad bytes at the end, assuming
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
334 longs are aligned on 4-byte boundaries::
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
335
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
336 >>> pack('llh0l', 1, 2, 3)
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
337 '\x00\x00\x00\x01\x00\x00\x00\x02\x00\x03\x00\x00'
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
338
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
339 This only works when native size and alignment are in effect; standard size and
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
340 alignment does not enforce any alignment.
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
341
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
342
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
343 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
344
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
345 Module :mod:`array`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
346 Packed binary storage of homogeneous data.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
347
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
348 Module :mod:`xdrlib`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
349 Packing and unpacking of XDR data.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
350
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
351
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
352 .. _struct-objects:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
353
62308
b00c736555de Merged revisions 81957 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 61865
diff changeset
354 Classes
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
355 -------
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
356
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
357 The :mod:`struct` module also defines the following type:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
358
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
359
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
360 .. class:: Struct(format)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
361
61865
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
362 Return a new Struct object which writes and reads binary data according to
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
363 the format string *format*. Creating a Struct object once and calling its
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
364 methods is more efficient than calling the :mod:`struct` functions with the
6dc9ec885463 Merged revisions 80013-80015 via svnmerge from
Mark Dickinson <dickinsm@gmail.com>
parents: 59002
diff changeset
365 same format since the format string only needs to be compiled once.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
366
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
367 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
368
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
369 Compiled Struct objects support the following methods and attributes:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
370
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
371
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
372 .. method:: pack(v1, v2, ...)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
373
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
374 Identical to the :func:`pack` function, using the compiled format.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
375 (``len(result)`` will equal :attr:`self.size`.)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
376
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
377
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
378 .. method:: pack_into(buffer, offset, v1, v2, ...)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
379
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
380 Identical to the :func:`pack_into` function, using the compiled format.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
381
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
382
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
383 .. method:: unpack(string)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
384
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
385 Identical to the :func:`unpack` function, using the compiled format.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
386 (``len(string)`` must equal :attr:`self.size`).
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
387
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
388
77102
a36666c52115 #14804: Remove [] around optional arguments with default values
Hynek Schlawack <hs@ox.cx>
parents: 74395
diff changeset
389 .. method:: unpack_from(buffer, offset=0)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
390
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
391 Identical to the :func:`unpack_from` function, using the compiled format.
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
392 (``len(buffer[offset:])`` must be at least :attr:`self.size`).
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
393
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
394
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
395 .. attribute:: format
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
396
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
397 The format string used to construct this Struct object.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
398
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
399 .. attribute:: size
42775
d7517c306791 Merged revisions 57221-57391 via svnmerge from
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
400
46555
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
401 The calculated size of the struct (and hence of the string) corresponding
66c8bd1bedf3 reformat some documentation of classes so methods and attributes are under the class directive
Benjamin Peterson <benjamin@python.org>
parents: 45672
diff changeset
402 to :attr:`format`.
42775
d7517c306791 Merged revisions 57221-57391 via svnmerge from
Guido van Rossum <guido@python.org>
parents: 42604
diff changeset
403