Issue #8469: Reorder struct module sections for clarity; other minor tweaks.

mdickinson · mdickinson · commit cfd56f2dc61c · 2010-06-12T18:37:54.000Z
diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst
@@ -77,9 +77,84 @@ Format Strings
 --------------
 
 Format strings are the mechanism used to specify the expected layout when
-packing and unpacking data.  They are built up from format characters, which
-specify the type of data being packed/unpacked.  In addition, there are
-special characters for controlling the byte order, size, and alignment.
+packing and unpacking data.  They are built up from :ref:`format-characters`,
+which specify the type of data being packed/unpacked.  In addition, there are
+special characters for controlling the :ref:`struct-alignment`.
+
+
+.. _struct-alignment:
+
+Byte Order, Size, and Alignment
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, C types are represented in the machine's native format and byte
+order, and properly aligned by skipping pad bytes if necessary (according to the
+rules used by the C compiler).
+
+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           |
++-----------+------------------------+--------------------+
+
+If the first character is not one of these, ``'@'`` is assumed.
+
+Native byte order is big-endian or little-endian, depending on the host
+system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
+Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature
+switchable endianness (bi-endian). Use ``sys.byteorder`` to check the
+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.
+
+Note the difference between ``'@'`` and ``'='``: both use native byte order, but
+the size and alignment of the latter is standardized.
+
+The form ``'!'`` is available for those poor souls who claim they can't remember
+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.
+    No padding is added at the beginning or the end of the encoded struct.
+
+(2) No padding is added when using non-native size and alignment, e.g.
+    with '<', '>', '=', and '!'.
+
+(3) To align the end of a structure to the alignment requirement of a
+    particular type, end the format with the code for that type with a repeat
+    count of zero.  See :ref:`struct-examples`.
+
+
+.. _format-characters:
 
 Format Characters
 ^^^^^^^^^^^^^^^^^
@@ -196,77 +271,6 @@ Either 0 or 1 in the native or standard bool representation will be packed, and
 any non-zero value will be True when unpacking.
 
 
-.. _struct-alignment:
-
-Byte Order, Size, and Alignment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-By default, C types are represented in the machine's native format and byte
-order, and properly aligned by skipping pad bytes if necessary (according to the
-rules used by the C compiler).
-
-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           |
-+-----------+------------------------+--------------------+
-
-If the first character is not one of these, ``'@'`` is assumed.
-
-Native byte order is big-endian or little-endian, depending on the host
-system. For example, Intel x86 and AMD64 (x86-64) are little-endian;
-Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature
-switchable endianness (bi-endian). Use ``sys.byteorder`` to check the
-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.
-
-Note the difference between ``'@'`` and ``'='``: both use native byte order, but
-the size and alignment of the latter is standardized.
-
-The form ``'!'`` is available for those poor souls who claim they can't remember
-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.
-    No padding is added at the beginning or the end of the encoded struct.
-
-(2) No padding is added when using non-native size and alignment, e.g.
-    with '<', '>', '=', and '!'.
-
-(3) To align the end of a structure to the alignment requirement of a
-    particular type, end the format with the code for that type with a repeat
-    count of zero.  See :ref:`struct-examples`.
-
 
 .. _struct-examples:
 
@@ -331,7 +335,7 @@ alignment does not enforce any alignment.
 
 .. _struct-objects:
 
-Objects
+Classes
 -------
 
 The :mod:`struct` module also defines the following type:
