--------------
Format strings describe the data layout when
-packing and unpacking data. They are built up from :ref:`format characters<format-characters>`,
+packing and unpacking data. They are built up from :ref:`type codes <type-codes>`,
which specify the type of data being packed/unpacked. In addition,
special characters control the :ref:`byte order, size and alignment<struct-alignment>`.
Each format string consists of an optional prefix character which
Native size and alignment are determined using the C compiler's
``sizeof`` expression. This is always combined with native byte order.
-Standard size depends only on the format character; see the table in
-the :ref:`format-characters` section.
+Standard size depends only on the type code; see the table in
+the :ref:`type-codes` section.
Note the difference between ``'@'`` and ``'='``: both use native byte order, but
the size and alignment of the latter is standardized.
count of zero. See :ref:`struct-examples`.
+.. _type-codes:
.. _format-characters:
-Format Characters
-^^^^^^^^^^^^^^^^^
+Type Codes
+^^^^^^^^^^
-Format characters have the following meaning; the conversion between C and
+Type codes (or format codes) have the following meaning; the conversion between C and
Python values should be obvious given their types. The 'Standard size' column
refers to the size of the packed value in bytes when using standard size; that
is, when the format string starts with one of ``'<'``, ``'>'``, ``'!'`` or
format used by the platform.
(5)
- The ``'P'`` format character is only available for the native byte ordering
+ The ``'P'`` type code 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
When packing, ``'x'`` inserts one NUL byte.
(8)
- The ``'p'`` format character encodes a "Pascal string", meaning a short
+ The ``'p'`` type code encodes a "Pascal string", meaning a short
variable-length string stored in a *fixed number of bytes*, given by the count.
The first byte stored is the length of the string, or 255, whichever is
smaller. The bytes of the string follow. If the byte string passed in to
:func:`pack` is too long (longer than the count minus 1), only the leading
``count-1`` bytes of the string are stored. If the byte string is shorter than
``count-1``, it is padded with null bytes so that exactly count bytes in all
- are used. Note that for :func:`unpack`, the ``'p'`` format character consumes
+ are used. Note that for :func:`unpack`, the ``'p'`` type code consumes
``count`` bytes, but that the :class:`!bytes` object returned can never contain more than 255
bytes.
When packing, arguments of types :class:`bytes` and :class:`bytearray`
are accepted.
(9)
- For the ``'s'`` format character, the count is interpreted as the length of the
- byte string, not a repeat count like for the other format characters; for example,
+ For the ``'s'`` type code, the count is interpreted as the length of the
+ byte string, not a repeat count like for the other type codes; for example,
``'10s'`` means a single 10-byte string mapping to or from a single
Python byte string, while ``'10c'`` means 10
separate one byte character elements (e.g., ``cccccccccc``) mapping
are accepted.
(10)
- For the ``'F'`` and ``'D'`` format characters, the packed representation uses
+ For the ``'F'`` and ``'D'`` type codes, the packed representation uses
the IEEE 754 binary32 and binary64 format for components of the complex
number, regardless of the floating-point format used by the platform.
Note that complex types (``F``/``Zf`` and ``D``/``Zd``) are available unconditionally,
two-element C array containing, respectively, the real and imaginary parts.
-A format character may be preceded by an integral repeat count. For example,
+A type code may be preceded by an integral repeat count. For example,
the format string ``'4h'`` means exactly the same as ``'hhhh'``.
Whitespace characters between formats are ignored; a count and its format must
.. index:: single: ? (question mark); in struct format strings
-For the ``'?'`` format character, the return value is either :const:`True` or
+For the ``'?'`` type code, the return value is either :const:`True` or
:const:`False`. When packing, the truth value of the argument object is used.
Either 0 or 1 in the native or standard bool representation will be packed, and
any non-zero value will be ``True`` when unpacking.
>>> Student._make(unpack('<10sHHb', record))
Student(name=b'raymond ', serialnum=4658, school=264, gradelevel=8)
-The ordering of format characters may have an impact on size in native
+The ordering of type codes may have an impact on size in native
mode since padding is implicit. In standard mode, the user is
responsible for inserting any desired padding.
Note in
compiler and machine architecture determine byte ordering and padding.
In such cases, the ``@`` format character should be used to specify
native byte ordering and data sizes. Internal pad bytes are normally inserted
-automatically. It is possible that a zero-repeat format code will be
+automatically. It is possible that a zero-repeat type code will be
needed at the end of a format string to round up to the correct
byte boundary for proper alignment of consecutive chunks of data.
>>> calcsize('@llh0l')
24
-The ``'x'`` format code can be used to specify the repeat, but for
+The ``'x'`` type code can be used to specify the repeat, but for
native formats it is better to use a zero-repeat format like ``'0l'``.
By default, native byte ordering and alignment is used, but it is
projects / thirdparty / Python / cpython.git / commitdiff
