1
:mod:`array` --- Efficient arrays of numeric values
2
===================================================
5
:synopsis: Space efficient arrays of uniformly typed numeric values.
8
.. index:: single: arrays
10
This module defines an object type which can compactly represent an array of
11
basic values: characters, integers, floating point numbers. Arrays are sequence
12
types and behave very much like lists, except that the type of objects stored in
13
them is constrained. The type is specified at object creation time by using a
14
:dfn:`type code`, which is a single character. The following type codes are
17
+-----------+--------------------+-------------------+-----------------------+-------+
18
| Type code | C Type | Python Type | Minimum size in bytes | Notes |
19
+===========+====================+===================+=======================+=======+
20
| ``'b'`` | signed char | int | 1 | |
21
+-----------+--------------------+-------------------+-----------------------+-------+
22
| ``'B'`` | unsigned char | int | 1 | |
23
+-----------+--------------------+-------------------+-----------------------+-------+
24
| ``'u'`` | Py_UNICODE | Unicode character | 2 | \(1) |
25
+-----------+--------------------+-------------------+-----------------------+-------+
26
| ``'h'`` | signed short | int | 2 | |
27
+-----------+--------------------+-------------------+-----------------------+-------+
28
| ``'H'`` | unsigned short | int | 2 | |
29
+-----------+--------------------+-------------------+-----------------------+-------+
30
| ``'i'`` | signed int | int | 2 | |
31
+-----------+--------------------+-------------------+-----------------------+-------+
32
| ``'I'`` | unsigned int | int | 2 | |
33
+-----------+--------------------+-------------------+-----------------------+-------+
34
| ``'l'`` | signed long | int | 4 | |
35
+-----------+--------------------+-------------------+-----------------------+-------+
36
| ``'L'`` | unsigned long | int | 4 | |
37
+-----------+--------------------+-------------------+-----------------------+-------+
38
| ``'q'`` | signed long long | int | 8 | \(2) |
39
+-----------+--------------------+-------------------+-----------------------+-------+
40
| ``'Q'`` | unsigned long long | int | 8 | \(2) |
41
+-----------+--------------------+-------------------+-----------------------+-------+
42
| ``'f'`` | float | float | 4 | |
43
+-----------+--------------------+-------------------+-----------------------+-------+
44
| ``'d'`` | double | float | 8 | |
45
+-----------+--------------------+-------------------+-----------------------+-------+
50
The ``'u'`` type code corresponds to Python's obsolete unicode character
51
(:c:type:`Py_UNICODE` which is :c:type:`wchar_t`). Depending on the
52
platform, it can be 16 bits or 32 bits.
54
``'u'`` will be removed together with the rest of the :c:type:`Py_UNICODE`
57
.. deprecated-removed:: 3.3 4.0
60
The ``'q'`` and ``'Q'`` type codes are available only if
61
the platform C compiler used to build Python supports C :c:type:`long long`,
62
or, on Windows, :c:type:`__int64`.
66
The actual representation of values is determined by the machine architecture
67
(strictly speaking, by the C implementation). The actual size can be accessed
68
through the :attr:`itemsize` attribute.
70
The module defines the following type:
73
.. class:: array(typecode[, initializer])
75
A new array whose items are restricted by *typecode*, and initialized
76
from the optional *initializer* value, which must be a list, a
77
:term:`bytes-like object`, or iterable over elements of the
80
If given a list or string, the initializer is passed to the new array's
81
:meth:`fromlist`, :meth:`frombytes`, or :meth:`fromunicode` method (see below)
82
to add initial items to the array. Otherwise, the iterable initializer is
83
passed to the :meth:`extend` method.
88
A string with all available type codes.
90
Array objects support the ordinary sequence operations of indexing, slicing,
91
concatenation, and multiplication. When using slice assignment, the assigned
92
value must be an array object with the same type code; in all other cases,
93
:exc:`TypeError` is raised. Array objects also implement the buffer interface,
94
and may be used wherever :term:`bytes-like object`\ s are supported.
96
The following data items and methods are also supported:
98
.. attribute:: array.typecode
100
The typecode character used to create the array.
103
.. attribute:: array.itemsize
105
The length in bytes of one array item in the internal representation.
108
.. method:: array.append(x)
110
Append a new item with value *x* to the end of the array.
113
.. method:: array.buffer_info()
115
Return a tuple ``(address, length)`` giving the current memory address and the
116
length in elements of the buffer used to hold array's contents. The size of the
117
memory buffer in bytes can be computed as ``array.buffer_info()[1] *
118
array.itemsize``. This is occasionally useful when working with low-level (and
119
inherently unsafe) I/O interfaces that require memory addresses, such as certain
120
:c:func:`ioctl` operations. The returned numbers are valid as long as the array
121
exists and no length-changing operations are applied to it.
125
When using array objects from code written in C or C++ (the only way to
126
effectively make use of this information), it makes more sense to use the buffer
127
interface supported by array objects. This method is maintained for backward
128
compatibility and should be avoided in new code. The buffer interface is
129
documented in :ref:`bufferobjects`.
132
.. method:: array.byteswap()
134
"Byteswap" all items of the array. This is only supported for values which are
135
1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
136
raised. It is useful when reading data from a file written on a machine with a
137
different byte order.
140
.. method:: array.count(x)
142
Return the number of occurrences of *x* in the array.
145
.. method:: array.extend(iterable)
147
Append items from *iterable* to the end of the array. If *iterable* is another
148
array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
149
be raised. If *iterable* is not an array, it must be iterable and its elements
150
must be the right type to be appended to the array.
153
.. method:: array.frombytes(s)
155
Appends items from the string, interpreting the string as an array of machine
156
values (as if it had been read from a file using the :meth:`fromfile` method).
158
.. versionadded:: 3.2
159
:meth:`fromstring` is renamed to :meth:`frombytes` for clarity.
162
.. method:: array.fromfile(f, n)
164
Read *n* items (as machine values) from the :term:`file object` *f* and append
165
them to the end of the array. If less than *n* items are available,
166
:exc:`EOFError` is raised, but the items that were available are still
167
inserted into the array. *f* must be a real built-in file object; something
168
else with a :meth:`read` method won't do.
171
.. method:: array.fromlist(list)
173
Append items from the list. This is equivalent to ``for x in list:
174
a.append(x)`` except that if there is a type error, the array is unchanged.
177
.. method:: array.fromstring()
179
Deprecated alias for :meth:`frombytes`.
182
.. method:: array.fromunicode(s)
184
Extends this array with data from the given unicode string. The array must
185
be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised. Use
186
``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
187
array of some other type.
190
.. method:: array.index(x)
192
Return the smallest *i* such that *i* is the index of the first occurrence of
196
.. method:: array.insert(i, x)
198
Insert a new item with value *x* in the array before position *i*. Negative
199
values are treated as being relative to the end of the array.
202
.. method:: array.pop([i])
204
Removes the item with the index *i* from the array and returns it. The optional
205
argument defaults to ``-1``, so that by default the last item is removed and
209
.. method:: array.remove(x)
211
Remove the first occurrence of *x* from the array.
214
.. method:: array.reverse()
216
Reverse the order of the items in the array.
219
.. method:: array.tobytes()
221
Convert the array to an array of machine values and return the bytes
222
representation (the same sequence of bytes that would be written to a file by
223
the :meth:`tofile` method.)
225
.. versionadded:: 3.2
226
:meth:`tostring` is renamed to :meth:`tobytes` for clarity.
229
.. method:: array.tofile(f)
231
Write all items (as machine values) to the :term:`file object` *f*.
234
.. method:: array.tolist()
236
Convert the array to an ordinary list with the same items.
239
.. method:: array.tostring()
241
Deprecated alias for :meth:`tobytes`.
244
.. method:: array.tounicode()
246
Convert the array to a unicode string. The array must be a type ``'u'`` array;
247
otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to
248
obtain a unicode string from an array of some other type.
251
When an array object is printed or converted to a string, it is represented as
252
``array(typecode, initializer)``. The *initializer* is omitted if the array is
253
empty, otherwise it is a string if the *typecode* is ``'u'``, otherwise it is a
254
list of numbers. The string is guaranteed to be able to be converted back to an
255
array with the same type and value using :func:`eval`, so long as the
256
:func:`array` function has been imported using ``from array import array``.
260
array('u', 'hello \u2641')
261
array('l', [1, 2, 3, 4, 5])
262
array('d', [1.0, 2.0, 3.14])
268
Packing and unpacking of heterogeneous binary data.
271
Packing and unpacking of External Data Representation (XDR) data as used in some
272
remote procedure call systems.
274
`The Numerical Python Documentation <http://docs.scipy.org/doc/>`_
275
The Numeric Python extension (NumPy) defines another array type; see
276
http://www.numpy.org/ for further information about Numerical Python.
added
removed
python-3.5.1-docs-html/_sources/library/array.txt
