[Python-checkins] r81992 - python/trunk/Doc/library/struct.rst

[mark.dickinson]

Author: mark.dickinson
Date: Tue Jun 15 10:33:03 2010
New Revision: 81992

Log:
Issue #8469:  Further clarifications and improvements to struct module
documentation.  Thanks Mads Kiilerich.


Modified:
   python/trunk/Doc/library/struct.rst

Modified: python/trunk/Doc/library/struct.rst
==============================================================================
--- python/trunk/Doc/library/struct.rst	(original)
+++ python/trunk/Doc/library/struct.rst	Tue Jun 15 10:33:03 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.
@@ -197,15 +188,15 @@
 | ``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 @@
       :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'``.