[Python-checkins] r81993 - in python/branches/release26-maint: Doc/library/struct.rst
mark.dickinson
python-checkins at python.org
Tue Jun 15 10:38:22 CEST 2010
Author: mark.dickinson
Date: Tue Jun 15 10:38:21 2010
New Revision: 81993
Log:
Merged revisions 81992 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r81992 | mark.dickinson | 2010-06-15 09:33:03 +0100 (Tue, 15 Jun 2010) | 3 lines
Issue #8469: Further clarifications and improvements to struct module
documentation. Thanks Mads Kiilerich.
........
Modified:
python/branches/release26-maint/ (props changed)
python/branches/release26-maint/Doc/library/struct.rst
Modified: python/branches/release26-maint/Doc/library/struct.rst
==============================================================================
--- python/branches/release26-maint/Doc/library/struct.rst (original)
+++ python/branches/release26-maint/Doc/library/struct.rst Tue Jun 15 10:38:21 2010
@@ -21,9 +21,9 @@
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 @@
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 @@
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 @@
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.
@@ -174,38 +165,38 @@
+--------+-------------------------+--------------------+----------------+------------+
| ``c`` | :ctype:`char` | string of length 1 | 1 | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``b`` | :ctype:`signed char` | integer | 1 | \(3) |
+| ``b`` | :ctype:`signed char` | integer | 1 | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``B`` | :ctype:`unsigned char` | integer | 1 | \(3) |
+| ``B`` | :ctype:`unsigned char` | integer | 1 | |
+--------+-------------------------+--------------------+----------------+------------+
| ``?`` | :ctype:`_Bool` | bool | 1 | \(1) |
+--------+-------------------------+--------------------+----------------+------------+
-| ``h`` | :ctype:`short` | integer | 2 | \(3) |
+| ``h`` | :ctype:`short` | integer | 2 | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``H`` | :ctype:`unsigned short` | integer | 2 | \(3) |
+| ``H`` | :ctype:`unsigned short` | integer | 2 | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``i`` | :ctype:`int` | integer | 4 | \(3) |
+| ``i`` | :ctype:`int` | integer | 4 | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``I`` | :ctype:`unsigned int` | integer | 4 | \(3) |
+| ``I`` | :ctype:`unsigned int` | integer | 4 | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``l`` | :ctype:`long` | integer | 4 | \(3) |
+| ``l`` | :ctype:`long` | integer | 4 | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``L`` | :ctype:`unsigned long` | integer | 4 | \(3) |
+| ``L`` | :ctype:`unsigned long` | integer | 4 | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``q`` | :ctype:`long long` | integer | 8 | \(2), \(3) |
+| ``q`` | :ctype:`long long` | integer | 8 | \(2) |
+--------+-------------------------+--------------------+----------------+------------+
-| ``Q`` | :ctype:`unsigned long | integer | 8 | \(2), \(3) |
+| ``Q`` | :ctype:`unsigned long | integer | 8 | \(2) |
| | long` | | | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``f`` | :ctype:`float` | float | 4 | |
+| ``f`` | :ctype:`float` | float | 4 | \(3) |
+--------+-------------------------+--------------------+----------------+------------+
-| ``d`` | :ctype:`double` | float | 8 | |
+| ``d`` | :ctype:`double` | float | 8 | \(3) |
+--------+-------------------------+--------------------+----------------+------------+
| ``s`` | :ctype:`char[]` | string | | |
+--------+-------------------------+--------------------+----------------+------------+
| ``p`` | :ctype:`char[]` | string | | |
+--------+-------------------------+--------------------+----------------+------------+
-| ``P`` | :ctype:`void \*` | integer | | \(3) |
+| ``P`` | :ctype:`void \*` | integer | | \(4) |
+--------+-------------------------+--------------------+----------------+------------+
Notes:
@@ -224,6 +215,19 @@
.. versionadded:: 2.2
+(3)
+ 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.
+
+(4)
+ 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'``.
More information about the Python-checkins
mailing list