[Python-checkins] r81956 - python/branches/py3k/Doc/library/struct.rst
mark.dickinson
python-checkins at python.org
Sat Jun 12 20:37:54 CEST 2010
Author: mark.dickinson
Date: Sat Jun 12 20:37:54 2010
New Revision: 81956
Log:
Issue #8469: Reorder struct module sections for clarity; other minor tweaks.
Modified:
python/branches/py3k/Doc/library/struct.rst
Modified: python/branches/py3k/Doc/library/struct.rst
==============================================================================
--- python/branches/py3k/Doc/library/struct.rst (original)
+++ python/branches/py3k/Doc/library/struct.rst Sat Jun 12 20:37:54 2010
@@ -77,9 +77,84 @@
--------------
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 @@
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 @@
.. _struct-objects:
-Objects
+Classes
-------
The :mod:`struct` module also defines the following type:
More information about the Python-checkins
mailing list