diff --git a/Doc/library/array.rst b/Doc/library/array.rst index 02eb775f31effc..0fd08656e5b6f3 100644 --- a/Doc/library/array.rst +++ b/Doc/library/array.rst @@ -12,7 +12,7 @@ This module defines an object type which can compactly represent an array of basic values: characters, integers, floating-point numbers, complex numbers. Arrays are mutable :term:`sequence` types and behave very much like lists, except that the type of objects stored in them is constrained. The type is specified at object creation time by using a -:dfn:`type code`, which is a single character. The following type codes are +:dfn:`type code`. The following type codes are defined: +-----------+--------------------+-------------------+-----------------------+-------+ @@ -91,7 +91,7 @@ Notes: .. seealso:: The :ref:`ctypes ` and - :ref:`struct ` modules, + :ref:`struct ` modules, as well as third-party modules like `numpy `__, use similar -- but slightly different -- type codes. diff --git a/Doc/library/ctypes.rst b/Doc/library/ctypes.rst index 3db66ad8ea66e7..1d8a0bfa989a31 100644 --- a/Doc/library/ctypes.rst +++ b/Doc/library/ctypes.rst @@ -2572,8 +2572,7 @@ Fundamental data types .. attribute:: _type_ - Class attribute that contains an internal type code, as a - single-character string. + Class attribute that contains an internal type code. See :ref:`ctypes-fundamental-data-types` for a summary. Types marked \* in the summary may be (or always are) aliases of a @@ -2587,7 +2586,7 @@ Fundamental data types .. seealso:: - The :mod:`array` and :ref:`struct ` modules, + The :mod:`array` and :ref:`struct ` modules, as well as third-party modules like `numpy `__, use similar -- but slightly different -- type codes. diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index bf5f754e156d3c..339b3110649dd3 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -111,7 +111,7 @@ Format Strings -------------- Format strings describe the data layout when -packing and unpacking data. They are built up from :ref:`format characters`, +packing and unpacking data. They are built up from :ref:`type codes`, which specify the type of data being packed/unpacked. In addition, special characters control the :ref:`byte order, size and alignment`. Each format string consists of an optional prefix character which @@ -183,8 +183,8 @@ Use :data:`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 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. @@ -208,12 +208,13 @@ Notes: 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 @@ -324,7 +325,7 @@ Notes: 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 @@ -346,22 +347,22 @@ Notes: 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 @@ -376,7 +377,7 @@ Notes: 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, @@ -385,7 +386,7 @@ Notes: 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 @@ -402,7 +403,7 @@ then :exc:`struct.error` is raised. .. 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. @@ -457,7 +458,7 @@ the result in a named tuple:: >>> 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 @@ -515,7 +516,7 @@ When constructing format strings which mimic native layouts, the 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. @@ -534,7 +535,7 @@ code solves that problem:: >>> 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 diff --git a/Objects/memoryobject.c b/Objects/memoryobject.c index 900db864621a84..c0fd0b8b2f0f53 100644 --- a/Objects/memoryobject.c +++ b/Objects/memoryobject.c @@ -1806,7 +1806,7 @@ pylong_as_zu(PyObject *item) dest = x; \ } while (0) -/* Unpack a single item. 'fmt' can be any native format character in struct +/* Unpack a single item. 'fmt' can be any native format in struct module syntax. This function is very sensitive to small changes. With this layout gcc automatically generates a fast jump table. */ static inline PyObject * @@ -1926,7 +1926,7 @@ unpack_single(PyMemoryViewObject *self, const char *ptr, const char *fmt) memcpy(ptr, (char *)&x, sizeof x); \ } while (0) -/* Pack a single item. 'fmt' can be any native format character in +/* Pack a single item. 'fmt' can be any native format in struct module syntax. */ static int pack_single(PyMemoryViewObject *self, char *ptr, PyObject *item, const char *fmt)