traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests 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, order to maintain proper alignment for the C types involved; similarly,
alignment is taken into account when unpacking. This behavior is chosen so 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 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 of the corresponding C struct. To handle platform-independent data formats
alignment instead of `native` size and alignment: see :ref:`struct-alignment` or omit implicit pad bytes, use `standard` size and alignment instead of
for details. `native` size and alignment: see :ref:`struct-alignment` for details.
Functions and Exceptions 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 the byte order, size and alignment of the packed data, according to the
following table: following table:
+-----------+------------------------+--------------------+ +-----------+------------------------+----------+-----------+
| Character | Byte order | Size and alignment | | Character | Byte order | Size | Alignment |
+===========+========================+====================+ +===========+========================+==========+===========+
| ``@`` | native | native | | ``@`` | native | native | native |
+-----------+------------------------+--------------------+ +-----------+------------------------+----------+-----------+
| ``=`` | native | standard | | ``=`` | native | standard | none |
+-----------+------------------------+--------------------+ +-----------+------------------------+----------+-----------+
| ``<`` | little-endian | standard | | ``<`` | little-endian | standard | none |
+-----------+------------------------+--------------------+ +-----------+------------------------+----------+-----------+
| ``>`` | big-endian | standard | | ``>`` | big-endian | standard | none |
+-----------+------------------------+--------------------+ +-----------+------------------------+----------+-----------+
| ``!`` | network (= big-endian) | standard | | ``!`` | network (= big-endian) | standard | none |
+-----------+------------------------+--------------------+ +-----------+------------------------+----------+-----------+
If the first character is not one of these, ``'@'`` is assumed. 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 Native size and alignment are determined using the C compiler's
``sizeof`` expression. This is always combined with native byte order. ``sizeof`` expression. This is always combined with native byte order.
Standard size and alignment are as follows: no alignment is required for any Standard size depends only on the format character; see the table in
type (so you have to use pad bytes); :ctype:`short` is 2 bytes; :ctype:`int` and the :ref:`format-characters` section.
: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.
Note the difference between ``'@'`` and ``'='``: both use native byte order, but Note the difference between ``'@'`` and ``'='``: both use native byte order, but
the size and alignment of the latter is standardized. 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 There is no way to indicate non-native byte order (force byte-swapping); use the
appropriate choice of ``'<'`` or ``'>'``. 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: Notes:
(1) Padding is only automatically added between successive structure members. (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) | | ``Q`` | :ctype:`unsigned long | integer | 8 | \(2), \(3) |
| | long` | | | | | | 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 | | | | ``s`` | :ctype:`char[]` | string | | |
+--------+-------------------------+--------------------+----------------+------------+ +--------+-------------------------+--------------------+----------------+------------+
| ``p`` | :ctype:`char[]` | string | | | | ``p`` | :ctype:`char[]` | string | | |
+--------+-------------------------+--------------------+----------------+------------+ +--------+-------------------------+--------------------+----------------+------------+
| ``P`` | :ctype:`void \*` | integer | | \(3) | | ``P`` | :ctype:`void \*` | integer | | \(5), \(3) |
+--------+-------------------------+--------------------+----------------+------------+ +--------+-------------------------+--------------------+----------------+------------+
Notes: Notes:
@ -240,6 +231,18 @@ Notes:
:meth:`__int__` method to convert, and :exc:`DeprecationWarning` was :meth:`__int__` method to convert, and :exc:`DeprecationWarning` was
raised only for float arguments. 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, A format character may be preceded by an integral repeat count. For example,
the format string ``'4h'`` means exactly the same as ``'hhhh'``. the format string ``'4h'`` means exactly the same as ``'hhhh'``.