mirror of
https://github.com/python/cpython.git
synced 2025-07-24 11:44:31 +00:00
Issue #8469: Reorder struct module sections for clarity; other minor tweaks.
This commit is contained in:
parent
7a70b2c450
commit
cfd56f2dc6
1 changed files with 79 additions and 75 deletions
|
@ -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:
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue