From b80d44f898347908776be23f2448bfafa5ba9272 Mon Sep 17 00:00:00 2001 From: Mark Dickinson Date: Tue, 15 Jun 2010 08:38:21 +0000 Subject: [PATCH] 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. ........ --- Doc/library/struct.rst | 84 ++++++++++++++++++++++-------------------- 1 file changed, 44 insertions(+), 40 deletions(-) diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index aa3de40750c..bc763e0cff9 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -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'``.