From 70e543b266d273217869091b90a3cedbe32b4a2e Mon Sep 17 00:00:00 2001 From: Stefan Krah Date: Sat, 8 Aug 2015 14:33:28 +0200 Subject: [PATCH] Issue #23756: Clarify the terms "contiguous" and "bytes-like object". Patch by Martin Panter. --- Doc/c-api/buffer.rst | 15 +++++++++------ Doc/c-api/memoryview.rst | 2 +- Doc/glossary.rst | 18 ++++++++++++++++-- Doc/library/stdtypes.rst | 8 ++++---- 4 files changed, 30 insertions(+), 13 deletions(-) diff --git a/Doc/c-api/buffer.rst b/Doc/c-api/buffer.rst index e6330e75219..6cb474e80e2 100644 --- a/Doc/c-api/buffer.rst +++ b/Doc/c-api/buffer.rst @@ -96,8 +96,8 @@ a buffer, see :c:func:`PyObject_GetBuffer`. block of the exporter. For example, with negative :c:member:`~Py_buffer.strides` the value may point to the end of the memory block. - For contiguous arrays, the value points to the beginning of the memory - block. + For :term:`contiguous` arrays, the value points to the beginning of + the memory block. .. c:member:: void \*obj @@ -281,11 +281,14 @@ of the flags below it. +-----------------------------+-------+---------+------------+ +.. index:: contiguous, C-contiguous, Fortran contiguous + contiguity requests ~~~~~~~~~~~~~~~~~~~ -C or Fortran contiguity can be explicitly requested, with and without stride -information. Without stride information, the buffer must be C-contiguous. +C or Fortran :term:`contiguity ` can be explicitly requested, +with and without stride information. Without stride information, the buffer +must be C-contiguous. .. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l| @@ -466,13 +469,13 @@ Buffer-related functions .. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order) Return 1 if the memory defined by the *view* is C-style (*order* is - ``'C'``) or Fortran-style (*order* is ``'F'``) contiguous or either one + ``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one (*order* is ``'A'``). Return 0 otherwise. .. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char order) - Fill the *strides* array with byte-strides of a contiguous (C-style if + Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style if *order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the given shape with the given number of bytes per element. diff --git a/Doc/c-api/memoryview.rst b/Doc/c-api/memoryview.rst index 5e50977cbee..9f6bfd751ad 100644 --- a/Doc/c-api/memoryview.rst +++ b/Doc/c-api/memoryview.rst @@ -35,7 +35,7 @@ any other object. .. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order) - Create a memoryview object to a contiguous chunk of memory (in either + Create a memoryview object to a :term:`contiguous` chunk of memory (in either 'C' or 'F'ortran *order*) from an object that defines the buffer interface. If memory is contiguous, the memoryview object points to the original memory. Otherwise, a copy is made and the memoryview points to a diff --git a/Doc/glossary.rst b/Doc/glossary.rst index d00185e386f..846c01ae495 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -109,8 +109,10 @@ Glossary A :term:`text file` reads and writes :class:`str` objects. bytes-like object - An object that supports the :ref:`bufferobjects`, like :class:`bytes`, - :class:`bytearray` or :class:`memoryview`. Bytes-like objects can + An object that supports the :ref:`bufferobjects` and can + export a C-:term:`contiguous` buffer. This includes all :class:`bytes`, + :class:`bytearray`, and :class:`array.array` objects, as well as many + common :class:`memoryview` objects. Bytes-like objects can be used for various operations that work with binary data; these include compression, saving to a binary file, and sending over a socket. @@ -169,6 +171,18 @@ Glossary statement by defining :meth:`__enter__` and :meth:`__exit__` methods. See :pep:`343`. + contiguous + .. index:: C-contiguous, Fortran contiguous + + A buffer is considered contiguous exactly if it is either + *C-contiguous* or *Fortran contiguous*. Zero-dimensional buffers are + C and Fortran contiguous. In one-dimensional arrays, the items + must be layed out in memory next to each other, in order of + increasing indexes starting from zero. In multidimensional + C-contiguous arrays, the last index varies the fastest when + visiting items in order of memory address. However, in + Fortran contiguous arrays, the first index varies the fastest. + coroutine Coroutines is a more generalized form of subroutines. Subroutines are entered at one point and exited at another point. Coroutines can be diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index f0cc56b9a51..85734167b52 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -3561,7 +3561,7 @@ copying. Cast a memoryview to a new format or shape. *shape* defaults to ``[byte_length//new_itemsize]``, which means that the result view will be one-dimensional. The return value is a new memoryview, but - the buffer itself is not copied. Supported casts are 1D -> C-contiguous + the buffer itself is not copied. Supported casts are 1D -> C-:term:`contiguous` and C-contiguous -> 1D. The destination format is restricted to a single element native format in @@ -3752,19 +3752,19 @@ copying. .. attribute:: c_contiguous - A bool indicating whether the memory is C-contiguous. + A bool indicating whether the memory is C-:term:`contiguous`. .. versionadded:: 3.3 .. attribute:: f_contiguous - A bool indicating whether the memory is Fortran contiguous. + A bool indicating whether the memory is Fortran :term:`contiguous`. .. versionadded:: 3.3 .. attribute:: contiguous - A bool indicating whether the memory is contiguous. + A bool indicating whether the memory is :term:`contiguous`. .. versionadded:: 3.3