mirror of https://github.com/python/cpython
gh-100925: Move array methods under class in array doc (#101485)
* Move array methods under class in array doc * Fix a few internal references related to the touched lines
This commit is contained in:
C.A.M. Gerlach
GitHub
parent
0ca67e6313
commit
1b6045668d
|
|
@ -60,7 +60,7 @@ Notes:
|
|||
|
||||
The actual representation of values is determined by the machine architecture
|
||||
(strictly speaking, by the C implementation). The actual size can be accessed
|
||||
through the :attr:`itemsize` attribute.
|
||||
through the :attr:`array.itemsize` attribute.
|
||||
|
||||
The module defines the following item:
|
||||
|
||||
|
|
@ -85,161 +85,160 @@ The module defines the following type:
|
|||
to add initial items to the array. Otherwise, the iterable initializer is
|
||||
passed to the :meth:`extend` method.
|
||||
|
||||
Array objects support the ordinary sequence operations of indexing, slicing,
|
||||
concatenation, and multiplication. When using slice assignment, the assigned
|
||||
value must be an array object with the same type code; in all other cases,
|
||||
:exc:`TypeError` is raised. Array objects also implement the buffer interface,
|
||||
and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported.
|
||||
|
||||
.. audit-event:: array.__new__ typecode,initializer array.array
|
||||
|
||||
|
||||
Array objects support the ordinary sequence operations of indexing, slicing,
|
||||
concatenation, and multiplication. When using slice assignment, the assigned
|
||||
value must be an array object with the same type code; in all other cases,
|
||||
:exc:`TypeError` is raised. Array objects also implement the buffer interface,
|
||||
and may be used wherever :term:`bytes-like objects <bytes-like object>` are supported.
|
||||
.. attribute:: typecode
|
||||
|
||||
The following data items and methods are also supported:
|
||||
|
||||
.. attribute:: array.typecode
|
||||
|
||||
The typecode character used to create the array.
|
||||
The typecode character used to create the array.
|
||||
|
||||
|
||||
.. attribute:: array.itemsize
|
||||
.. attribute:: itemsize
|
||||
|
||||
The length in bytes of one array item in the internal representation.
|
||||
The length in bytes of one array item in the internal representation.
|
||||
|
||||
|
||||
.. method:: array.append(x)
|
||||
.. method:: append(x)
|
||||
|
||||
Append a new item with value *x* to the end of the array.
|
||||
Append a new item with value *x* to the end of the array.
|
||||
|
||||
|
||||
.. method:: array.buffer_info()
|
||||
.. method:: buffer_info()
|
||||
|
||||
Return a tuple ``(address, length)`` giving the current memory address and the
|
||||
length in elements of the buffer used to hold array's contents. The size of the
|
||||
memory buffer in bytes can be computed as ``array.buffer_info()[1] *
|
||||
array.itemsize``. This is occasionally useful when working with low-level (and
|
||||
inherently unsafe) I/O interfaces that require memory addresses, such as certain
|
||||
:c:func:`ioctl` operations. The returned numbers are valid as long as the array
|
||||
exists and no length-changing operations are applied to it.
|
||||
Return a tuple ``(address, length)`` giving the current memory address and the
|
||||
length in elements of the buffer used to hold array's contents. The size of the
|
||||
memory buffer in bytes can be computed as ``array.buffer_info()[1] *
|
||||
array.itemsize``. This is occasionally useful when working with low-level (and
|
||||
inherently unsafe) I/O interfaces that require memory addresses, such as certain
|
||||
:c:func:`!ioctl` operations. The returned numbers are valid as long as the array
|
||||
exists and no length-changing operations are applied to it.
|
||||
|
||||
.. note::
|
||||
.. note::
|
||||
|
||||
When using array objects from code written in C or C++ (the only way to
|
||||
effectively make use of this information), it makes more sense to use the buffer
|
||||
interface supported by array objects. This method is maintained for backward
|
||||
compatibility and should be avoided in new code. The buffer interface is
|
||||
documented in :ref:`bufferobjects`.
|
||||
When using array objects from code written in C or C++ (the only way to
|
||||
effectively make use of this information), it makes more sense to use the buffer
|
||||
interface supported by array objects. This method is maintained for backward
|
||||
compatibility and should be avoided in new code. The buffer interface is
|
||||
documented in :ref:`bufferobjects`.
|
||||
|
||||
|
||||
.. method:: array.byteswap()
|
||||
.. method:: byteswap()
|
||||
|
||||
"Byteswap" all items of the array. This is only supported for values which are
|
||||
1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
|
||||
raised. It is useful when reading data from a file written on a machine with a
|
||||
different byte order.
|
||||
"Byteswap" all items of the array. This is only supported for values which are
|
||||
1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
|
||||
raised. It is useful when reading data from a file written on a machine with a
|
||||
different byte order.
|
||||
|
||||
|
||||
.. method:: array.count(x)
|
||||
.. method:: count(x)
|
||||
|
||||
Return the number of occurrences of *x* in the array.
|
||||
Return the number of occurrences of *x* in the array.
|
||||
|
||||
|
||||
.. method:: array.extend(iterable)
|
||||
.. method:: extend(iterable)
|
||||
|
||||
Append items from *iterable* to the end of the array. If *iterable* is another
|
||||
array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
|
||||
be raised. If *iterable* is not an array, it must be iterable and its elements
|
||||
must be the right type to be appended to the array.
|
||||
Append items from *iterable* to the end of the array. If *iterable* is another
|
||||
array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
|
||||
be raised. If *iterable* is not an array, it must be iterable and its elements
|
||||
must be the right type to be appended to the array.
|
||||
|
||||
|
||||
.. method:: array.frombytes(s)
|
||||
.. method:: frombytes(s)
|
||||
|
||||
Appends items from the string, interpreting the string as an array of machine
|
||||
values (as if it had been read from a file using the :meth:`fromfile` method).
|
||||
Appends items from the string, interpreting the string as an array of machine
|
||||
values (as if it had been read from a file using the :meth:`fromfile` method).
|
||||
|
||||
.. versionadded:: 3.2
|
||||
:meth:`fromstring` is renamed to :meth:`frombytes` for clarity.
|
||||
.. versionadded:: 3.2
|
||||
:meth:`!fromstring` is renamed to :meth:`frombytes` for clarity.
|
||||
|
||||
|
||||
.. method:: array.fromfile(f, n)
|
||||
.. method:: fromfile(f, n)
|
||||
|
||||
Read *n* items (as machine values) from the :term:`file object` *f* and append
|
||||
them to the end of the array. If less than *n* items are available,
|
||||
:exc:`EOFError` is raised, but the items that were available are still
|
||||
inserted into the array.
|
||||
Read *n* items (as machine values) from the :term:`file object` *f* and append
|
||||
them to the end of the array. If less than *n* items are available,
|
||||
:exc:`EOFError` is raised, but the items that were available are still
|
||||
inserted into the array.
|
||||
|
||||
|
||||
.. method:: array.fromlist(list)
|
||||
.. method:: fromlist(list)
|
||||
|
||||
Append items from the list. This is equivalent to ``for x in list:
|
||||
a.append(x)`` except that if there is a type error, the array is unchanged.
|
||||
Append items from the list. This is equivalent to ``for x in list:
|
||||
a.append(x)`` except that if there is a type error, the array is unchanged.
|
||||
|
||||
|
||||
.. method:: array.fromunicode(s)
|
||||
.. method:: fromunicode(s)
|
||||
|
||||
Extends this array with data from the given unicode string. The array must
|
||||
be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised. Use
|
||||
``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
|
||||
array of some other type.
|
||||
Extends this array with data from the given unicode string. The array must
|
||||
be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised. Use
|
||||
``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
|
||||
array of some other type.
|
||||
|
||||
|
||||
.. method:: array.index(x[, start[, stop]])
|
||||
.. method:: index(x[, start[, stop]])
|
||||
|
||||
Return the smallest *i* such that *i* is the index of the first occurrence of
|
||||
*x* in the array. The optional arguments *start* and *stop* can be
|
||||
specified to search for *x* within a subsection of the array. Raise
|
||||
:exc:`ValueError` if *x* is not found.
|
||||
Return the smallest *i* such that *i* is the index of the first occurrence of
|
||||
*x* in the array. The optional arguments *start* and *stop* can be
|
||||
specified to search for *x* within a subsection of the array. Raise
|
||||
:exc:`ValueError` if *x* is not found.
|
||||
|
||||
.. versionchanged:: 3.10
|
||||
Added optional *start* and *stop* parameters.
|
||||
|
||||
.. method:: array.insert(i, x)
|
||||
|
||||
Insert a new item with value *x* in the array before position *i*. Negative
|
||||
values are treated as being relative to the end of the array.
|
||||
.. versionchanged:: 3.10
|
||||
Added optional *start* and *stop* parameters.
|
||||
|
||||
|
||||
.. method:: array.pop([i])
|
||||
.. method:: insert(i, x)
|
||||
|
||||
Removes the item with the index *i* from the array and returns it. The optional
|
||||
argument defaults to ``-1``, so that by default the last item is removed and
|
||||
returned.
|
||||
Insert a new item with value *x* in the array before position *i*. Negative
|
||||
values are treated as being relative to the end of the array.
|
||||
|
||||
|
||||
.. method:: array.remove(x)
|
||||
.. method:: pop([i])
|
||||
|
||||
Remove the first occurrence of *x* from the array.
|
||||
Removes the item with the index *i* from the array and returns it. The optional
|
||||
argument defaults to ``-1``, so that by default the last item is removed and
|
||||
returned.
|
||||
|
||||
|
||||
.. method:: array.reverse()
|
||||
.. method:: remove(x)
|
||||
|
||||
Reverse the order of the items in the array.
|
||||
Remove the first occurrence of *x* from the array.
|
||||
|
||||
|
||||
.. method:: array.tobytes()
|
||||
.. method:: reverse()
|
||||
|
||||
Convert the array to an array of machine values and return the bytes
|
||||
representation (the same sequence of bytes that would be written to a file by
|
||||
the :meth:`tofile` method.)
|
||||
|
||||
.. versionadded:: 3.2
|
||||
:meth:`tostring` is renamed to :meth:`tobytes` for clarity.
|
||||
Reverse the order of the items in the array.
|
||||
|
||||
|
||||
.. method:: array.tofile(f)
|
||||
.. method:: tobytes()
|
||||
|
||||
Write all items (as machine values) to the :term:`file object` *f*.
|
||||
Convert the array to an array of machine values and return the bytes
|
||||
representation (the same sequence of bytes that would be written to a file by
|
||||
the :meth:`tofile` method.)
|
||||
|
||||
.. versionadded:: 3.2
|
||||
:meth:`!tostring` is renamed to :meth:`tobytes` for clarity.
|
||||
|
||||
|
||||
.. method:: array.tolist()
|
||||
.. method:: tofile(f)
|
||||
|
||||
Convert the array to an ordinary list with the same items.
|
||||
Write all items (as machine values) to the :term:`file object` *f*.
|
||||
|
||||
|
||||
.. method:: array.tounicode()
|
||||
.. method:: tolist()
|
||||
|
||||
Convert the array to a unicode string. The array must be a type ``'u'`` array;
|
||||
otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to
|
||||
obtain a unicode string from an array of some other type.
|
||||
Convert the array to an ordinary list with the same items.
|
||||
|
||||
|
||||
.. method:: tounicode()
|
||||
|
||||
Convert the array to a unicode string. The array must be a type ``'u'`` array;
|
||||
otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to
|
||||
obtain a unicode string from an array of some other type.
|
||||
|
||||
|
||||
When an array object is printed or converted to a string, it is represented as
|
||||
|
|
|
|||
Loading…
Reference in New Issue