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