Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Issue #8469: Further clarifications and improvements to struct module 

documentation.  Thanks Mads Kiilerich.
This commit is contained in:
Mark Dickinson 2010-06-15 08:33:03 +00:00
parent 019aec22a7
commit 526e5eed71
1 changed files with 33 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
Doc/library/struct.rst
View File

@ -21,9 +21,9 @@ structs and the intended conversion to/from Python values.
order to maintain proper alignment for the C types involved; similarly,
alignment is taken into account when unpacking. This behavior is chosen so
that the bytes of a packed struct correspond exactly to the layout in memory
of the corresponding C struct. To omit pad bytes, use `standard` size and
alignment instead of `native` size and alignment: see :ref:`struct-alignment`
for details.
of the corresponding C struct. To handle platform-independent data formats
or omit implicit pad bytes, use `standard` size and alignment instead of
`native` size and alignment: see :ref:`struct-alignment` for details.
Functions and Exceptions
------------------------
@ -100,19 +100,19 @@ Alternatively, the first character of the format string can be used to indicate
the byte order, size and alignment of the packed data, according to the
following table:
+-----------+------------------------+--------------------+
| Character | Byte order | Size and alignment |
+===========+========================+====================+
| ``@`` | native | native |
+-----------+------------------------+--------------------+
| ``=`` | native | standard |
+-----------+------------------------+--------------------+
| ``<`` | little-endian | standard |
+-----------+------------------------+--------------------+
| ``>`` | big-endian | standard |
+-----------+------------------------+--------------------+
| ``!`` | network (= big-endian) | standard |
+-----------+------------------------+--------------------+
+-----------+------------------------+----------+-----------+
| Character | Byte order | Size | Alignment |
+===========+========================+==========+===========+
| ``@`` | native | native | native |
+-----------+------------------------+----------+-----------+
| ``=`` | native | standard | none |
+-----------+------------------------+----------+-----------+
| ``<`` | little-endian | standard | none |
+-----------+------------------------+----------+-----------+
| ``>`` | big-endian | standard | none |
+-----------+------------------------+----------+-----------+
| ``!`` | network (= big-endian) | standard | none |
+-----------+------------------------+----------+-----------+
If the first character is not one of these, ``'@'`` is assumed.
@ -125,11 +125,8 @@ endianness of your system.
Native size and alignment are determined using the C compiler's
``sizeof`` expression. This is always combined with native byte order.
Standard size and alignment are as follows: no alignment is required for any
type (so you have to use pad bytes); :ctype:`short` is 2 bytes; :ctype:`int` and
:ctype:`long` are 4 bytes; :ctype:`long long` (:ctype:`__int64` on Windows) is 8
bytes; :ctype:`float` and :ctype:`double` are 32-bit and 64-bit IEEE floating
point numbers, respectively. :ctype:`_Bool` is 1 byte.
Standard size depends only on the format character; see the table in
the :ref:`format-characters` section.
Note the difference between ``'@'`` and ``'='``: both use native byte order, but
the size and alignment of the latter is standardized.
@ -140,12 +137,6 @@ whether network byte order is big-endian or little-endian.
There is no way to indicate non-native byte order (force byte-swapping); use the
appropriate choice of ``'<'`` or ``'>'``.
The ``'P'`` format character is only available for the native byte ordering
(selected as the default or with the ``'@'`` byte order character). The byte
order character ``'='`` chooses to use little- or big-endian ordering based on
the host system. The struct module does not interpret this as native ordering,
so the ``'P'`` format is not available.
Notes:
(1) Padding is only automatically added between successive structure members.
@ -197,15 +188,15 @@ Python values should be obvious given their types:
| ``Q`` | :ctype:`unsigned long | integer | 8 | \(2), \(3) |
| | long` | | | |
+--------+-------------------------+--------------------+----------------+------------+
| ``f`` | :ctype:`float` | float | 4 | |
| ``f`` | :ctype:`float` | float | 4 | \(4) |
+--------+-------------------------+--------------------+----------------+------------+
| ``d`` | :ctype:`double` | float | 8 | |
| ``d`` | :ctype:`double` | float | 8 | \(4) |
+--------+-------------------------+--------------------+----------------+------------+
| ``s`` | :ctype:`char[]` | string | | |
+--------+-------------------------+--------------------+----------------+------------+
| ``p`` | :ctype:`char[]` | string | | |
+--------+-------------------------+--------------------+----------------+------------+
| ``P`` | :ctype:`void \*` | integer | | \(3) |
| ``P`` | :ctype:`void \*` | integer | | \(5), \(3) |
+--------+-------------------------+--------------------+----------------+------------+
Notes:
@ -240,6 +231,18 @@ Notes:
:meth:`__int__` method to convert, and :exc:`DeprecationWarning` was
raised only for float arguments.
(4)
For the ``'f'`` and ``'d'`` conversion codes, the packed representation uses
the IEEE 754 binary32 (for ``'f'``) or binary64 (for ``'d'``) format,
regardless of the floating-point format used by the platform.
(5)
The ``'P'`` format character is only available for the native byte ordering
(selected as the default or with the ``'@'`` byte order character). The byte
order character ``'='`` chooses to use little- or big-endian ordering based
on the host system. The struct module does not interpret this as native
ordering, so the ``'P'`` format is not available.
A format character may be preceded by an integral repeat count. For example,
the format string ``'4h'`` means exactly the same as ``'hhhh'``.