diff options
Diffstat (limited to 'Doc/library/array.rst')
| -rw-r--r-- | Doc/library/array.rst | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/Doc/library/array.rst b/Doc/library/array.rst new file mode 100644 index 0000000..5194edc --- /dev/null +++ b/Doc/library/array.rst @@ -0,0 +1,272 @@ + +:mod:`array` --- Efficient arrays of numeric values +=================================================== + +.. module:: array + :synopsis: Efficient arrays of uniformly typed numeric values. + + +.. index:: single: arrays + +This module defines an object type which can efficiently represent an array of +basic values: characters, integers, floating point numbers. Arrays are 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 +defined: + ++-----------+----------------+-------------------+-----------------------+ +| Type code | C Type | Python Type | Minimum size in bytes | ++===========+================+===================+=======================+ +| ``'c'`` | char | character | 1 | ++-----------+----------------+-------------------+-----------------------+ +| ``'b'`` | signed char | int | 1 | ++-----------+----------------+-------------------+-----------------------+ +| ``'B'`` | unsigned char | int | 1 | ++-----------+----------------+-------------------+-----------------------+ +| ``'u'`` | Py_UNICODE | Unicode character | 2 | ++-----------+----------------+-------------------+-----------------------+ +| ``'h'`` | signed short | int | 2 | ++-----------+----------------+-------------------+-----------------------+ +| ``'H'`` | unsigned short | int | 2 | ++-----------+----------------+-------------------+-----------------------+ +| ``'i'`` | signed int | int | 2 | ++-----------+----------------+-------------------+-----------------------+ +| ``'I'`` | unsigned int | long | 2 | ++-----------+----------------+-------------------+-----------------------+ +| ``'l'`` | signed long | int | 4 | ++-----------+----------------+-------------------+-----------------------+ +| ``'L'`` | unsigned long | long | 4 | ++-----------+----------------+-------------------+-----------------------+ +| ``'f'`` | float | float | 4 | ++-----------+----------------+-------------------+-----------------------+ +| ``'d'`` | double | float | 8 | ++-----------+----------------+-------------------+-----------------------+ + +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. The values stored for ``'L'`` and +``'I'`` items will be represented as Python long integers when retrieved, +because Python's plain integer type cannot represent the full range of C's +unsigned (long) integers. + +The module defines the following type: + + +.. function:: array(typecode[, initializer]) + + Return a new array whose items are restricted by *typecode*, and initialized + from the optional *initializer* value, which must be a list, string, or iterable + over elements of the appropriate type. + + .. versionchanged:: 2.4 + Formerly, only lists or strings were accepted. + + If given a list or string, the initializer is passed to the new array's + :meth:`fromlist`, :meth:`fromstring`, or :meth:`fromunicode` method (see below) + to add initial items to the array. Otherwise, the iterable initializer is + passed to the :meth:`extend` method. + + +.. data:: ArrayType + + Obsolete alias for :func:`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 buffer objects are supported. + +The following data items and methods are also supported: + + +.. attribute:: array.typecode + + The typecode character used to create the array. + + +.. attribute:: array.itemsize + + The length in bytes of one array item in the internal representation. + + +.. method:: array.append(x) + + Append a new item with value *x* to the end of the array. + + +.. method:: array.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 + :cfunc:`ioctl` operations. The returned numbers are valid as long as the array + exists and no length-changing operations are applied to it. + + .. 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`. + + +.. method:: array.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. + + +.. method:: array.count(x) + + Return the number of occurrences of *x* in the array. + + +.. method:: array.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. + + .. versionchanged:: 2.4 + Formerly, the argument could only be another array. + + +.. method:: array.fromfile(f, n) + + Read *n* items (as machine values) from the 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. + *f* must be a real built-in file object; something else with a :meth:`read` + method won't do. + + +.. method:: array.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. + + +.. method:: array.fromstring(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). + + +.. method:: array.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.fromstring(unicodestring.encode(enc))`` to append Unicode data to an + array of some other type. + + +.. method:: array.index(x) + + Return the smallest *i* such that *i* is the index of the first occurrence of + *x* in the array. + + +.. 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. + + +.. method:: array.pop([i]) + + 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.read(f, n) + + .. deprecated:: 1.5.1 + Use the :meth:`fromfile` method. + + Read *n* items (as machine values) from the 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. + *f* must be a real built-in file object; something else with a :meth:`read` + method won't do. + + +.. method:: array.remove(x) + + Remove the first occurrence of *x* from the array. + + +.. method:: array.reverse() + + Reverse the order of the items in the array. + + +.. method:: array.tofile(f) + + Write all items (as machine values) to the file object *f*. + + +.. method:: array.tolist() + + Convert the array to an ordinary list with the same items. + + +.. method:: array.tostring() + + Convert the array to an array of machine values and return the string + representation (the same sequence of bytes that would be written to a file by + the :meth:`tofile` method.) + + +.. method:: array.tounicode() + + Convert the array to a unicode string. The array must be a type ``'u'`` array; + otherwise a :exc:`ValueError` is raised. Use ``array.tostring().decode(enc)`` to + obtain a unicode string from an array of some other type. + + +.. method:: array.write(f) + + .. deprecated:: 1.5.1 + Use the :meth:`tofile` method. + + Write all items (as machine values) to the file object *f*. + +When an array object is printed or converted to a string, it is represented as +``array(typecode, initializer)``. The *initializer* is omitted if the array is +empty, otherwise it is a string if the *typecode* is ``'c'``, otherwise it is a +list of numbers. The string is guaranteed to be able to be converted back to an +array with the same type and value using :func:`eval`, so long as the +:func:`array` function has been imported using ``from array import array``. +Examples:: + + array('l') + array('c', 'hello world') + array('u', u'hello \u2641') + array('l', [1, 2, 3, 4, 5]) + array('d', [1.0, 2.0, 3.14]) + + +.. seealso:: + + Module :mod:`struct` + Packing and unpacking of heterogeneous binary data. + + Module :mod:`xdrlib` + Packing and unpacking of External Data Representation (XDR) data as used in some + remote procedure call systems. + + `The Numerical Python Manual <http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm>`_ + The Numeric Python extension (NumPy) defines another array type; see + http://numpy.sourceforge.net/ for further information about Numerical Python. + (A PDF version of the NumPy manual is available at + http://numpy.sourceforge.net/numdoc/numdoc.pdf). + |