traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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.
........
This commit is contained in:
Mark Dickinson 2010-06-15 08:38:21 +00:00
parent fb49f9a0be
commit b80d44f898
1 changed files with 44 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
Doc/library/struct.rst
View File

@ -21,9 +21,9 @@ structs and the intended conversion to/from Python values.
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 @@ 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 |
+-----------+------------------------+--------------------+
+-----------+------------------------+----------+-----------+
| 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 @@ 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.
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 @@ 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.
@ -174,38 +165,38 @@ Python values should be obvious given their types:
+--------+-------------------------+--------------------+----------------+------------+
| ``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 @@ Notes:
.. 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'``.