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