Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`array` --- Efficient arrays of numeric values |
| 2 | =================================================== |
| 3 | |
| 4 | .. module:: array |
Benjamin Peterson | 2a691a8 | 2008-03-31 01:51:45 +0000 | [diff] [blame] | 5 | :synopsis: Space efficient arrays of uniformly typed numeric values. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 6 | |
| 7 | |
| 8 | .. index:: single: arrays |
| 9 | |
Benjamin Peterson | 2a691a8 | 2008-03-31 01:51:45 +0000 | [diff] [blame] | 10 | This module defines an object type which can compactly represent an array of |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
| 15 | defined: |
| 16 | |
Meador Inge | 1c9f0c9 | 2011-09-20 19:55:51 -0500 | [diff] [blame] | 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 | +-----------+--------------------+-------------------+-----------------------+-------+ |
Victor Stinner | 62bb394 | 2012-08-06 00:46:05 +0200 | [diff] [blame] | 24 | | ``'u'`` | Py_UNICODE | Unicode character | 2 | \(1) | |
Meador Inge | 1c9f0c9 | 2011-09-20 19:55:51 -0500 | [diff] [blame] | 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 | +-----------+--------------------+-------------------+-----------------------+-------+ |
Victor Stinner | 62bb394 | 2012-08-06 00:46:05 +0200 | [diff] [blame] | 38 | | ``'q'`` | signed long long | int | 8 | \(2) | |
Meador Inge | 1c9f0c9 | 2011-09-20 19:55:51 -0500 | [diff] [blame] | 39 | +-----------+--------------------+-------------------+-----------------------+-------+ |
Victor Stinner | 62bb394 | 2012-08-06 00:46:05 +0200 | [diff] [blame] | 40 | | ``'Q'`` | unsigned long long | int | 8 | \(2) | |
Meador Inge | 1c9f0c9 | 2011-09-20 19:55:51 -0500 | [diff] [blame] | 41 | +-----------+--------------------+-------------------+-----------------------+-------+ |
| 42 | | ``'f'`` | float | float | 4 | | |
| 43 | +-----------+--------------------+-------------------+-----------------------+-------+ |
| 44 | | ``'d'`` | double | float | 8 | | |
| 45 | +-----------+--------------------+-------------------+-----------------------+-------+ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
Meador Inge | 1c9f0c9 | 2011-09-20 19:55:51 -0500 | [diff] [blame] | 47 | Notes: |
Georg Brandl | 9cbb125 | 2009-07-11 10:39:00 +0000 | [diff] [blame] | 48 | |
Meador Inge | 1c9f0c9 | 2011-09-20 19:55:51 -0500 | [diff] [blame] | 49 | (1) |
Stefan Krah | 029780b | 2012-08-24 20:14:12 +0200 | [diff] [blame] | 50 | The ``'u'`` type code corresponds to Python's obsolete unicode character |
Victor Stinner | 62bb394 | 2012-08-06 00:46:05 +0200 | [diff] [blame] | 51 | (:c:type:`Py_UNICODE` which is :c:type:`wchar_t`). Depending on the |
| 52 | platform, it can be 16 bits or 32 bits. |
| 53 | |
Stefan Krah | 029780b | 2012-08-24 20:14:12 +0200 | [diff] [blame] | 54 | ``'u'`` will be removed together with the rest of the :c:type:`Py_UNICODE` |
| 55 | API. |
| 56 | |
| 57 | .. deprecated-removed:: 3.3 4.0 |
| 58 | |
Victor Stinner | 62bb394 | 2012-08-06 00:46:05 +0200 | [diff] [blame] | 59 | (2) |
Meador Inge | 1c9f0c9 | 2011-09-20 19:55:51 -0500 | [diff] [blame] | 60 | The ``'q'`` and ``'Q'`` type codes are available only if |
Georg Brandl | f0c51fa | 2011-09-27 07:30:00 +0200 | [diff] [blame] | 61 | the platform C compiler used to build Python supports C :c:type:`long long`, |
| 62 | or, on Windows, :c:type:`__int64`. |
Meador Inge | 1c9f0c9 | 2011-09-20 19:55:51 -0500 | [diff] [blame] | 63 | |
| 64 | .. versionadded:: 3.3 |
| 65 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | ba956ae | 2007-11-29 17:24:34 +0000 | [diff] [blame] | 68 | through the :attr:`itemsize` attribute. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 69 | |
| 70 | The module defines the following type: |
| 71 | |
| 72 | |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 73 | .. class:: array(typecode[, initializer]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Alexandre Vassalotti | 711ed4a | 2009-07-17 10:42:05 +0000 | [diff] [blame] | 75 | A new array whose items are restricted by *typecode*, and initialized |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 76 | from the optional *initializer* value, which must be a list, object |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 77 | supporting the buffer interface, or iterable over elements of the |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 78 | appropriate type. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 80 | If given a list or string, the initializer is passed to the new array's |
Antoine Pitrou | 1ce3eb5 | 2010-09-01 20:29:34 +0000 | [diff] [blame] | 81 | :meth:`fromlist`, :meth:`frombytes`, or :meth:`fromunicode` method (see below) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 82 | to add initial items to the array. Otherwise, the iterable initializer is |
| 83 | passed to the :meth:`extend` method. |
| 84 | |
| 85 | |
Guido van Rossum | 98297ee | 2007-11-06 21:34:58 +0000 | [diff] [blame] | 86 | .. data:: typecodes |
| 87 | |
| 88 | A string with all available type codes. |
| 89 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 buffer objects are supported. |
| 95 | |
| 96 | The following data items and methods are also supported: |
| 97 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 98 | .. attribute:: array.typecode |
| 99 | |
| 100 | The typecode character used to create the array. |
| 101 | |
| 102 | |
| 103 | .. attribute:: array.itemsize |
| 104 | |
| 105 | The length in bytes of one array item in the internal representation. |
| 106 | |
| 107 | |
| 108 | .. method:: array.append(x) |
| 109 | |
| 110 | Append a new item with value *x* to the end of the array. |
| 111 | |
| 112 | |
| 113 | .. method:: array.buffer_info() |
| 114 | |
| 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 |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 120 | :c:func:`ioctl` operations. The returned numbers are valid as long as the array |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 121 | exists and no length-changing operations are applied to it. |
| 122 | |
| 123 | .. note:: |
| 124 | |
| 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`. |
| 130 | |
| 131 | |
| 132 | .. method:: array.byteswap() |
| 133 | |
| 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. |
| 138 | |
| 139 | |
| 140 | .. method:: array.count(x) |
| 141 | |
| 142 | Return the number of occurrences of *x* in the array. |
| 143 | |
| 144 | |
| 145 | .. method:: array.extend(iterable) |
| 146 | |
| 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. |
| 151 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 152 | |
Antoine Pitrou | 1ce3eb5 | 2010-09-01 20:29:34 +0000 | [diff] [blame] | 153 | .. method:: array.frombytes(s) |
| 154 | |
| 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). |
| 157 | |
| 158 | .. versionadded:: 3.2 |
| 159 | :meth:`fromstring` is renamed to :meth:`frombytes` for clarity. |
| 160 | |
| 161 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 162 | .. method:: array.fromfile(f, n) |
| 163 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 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. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | |
| 170 | |
| 171 | .. method:: array.fromlist(list) |
| 172 | |
| 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. |
| 175 | |
| 176 | |
Antoine Pitrou | 1ce3eb5 | 2010-09-01 20:29:34 +0000 | [diff] [blame] | 177 | .. method:: array.fromstring() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 178 | |
Antoine Pitrou | 1ce3eb5 | 2010-09-01 20:29:34 +0000 | [diff] [blame] | 179 | Deprecated alias for :meth:`frombytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 180 | |
| 181 | |
| 182 | .. method:: array.fromunicode(s) |
| 183 | |
| 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 |
Antoine Pitrou | 1ce3eb5 | 2010-09-01 20:29:34 +0000 | [diff] [blame] | 186 | ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 187 | array of some other type. |
| 188 | |
| 189 | |
| 190 | .. method:: array.index(x) |
| 191 | |
| 192 | Return the smallest *i* such that *i* is the index of the first occurrence of |
| 193 | *x* in the array. |
| 194 | |
| 195 | |
| 196 | .. method:: array.insert(i, x) |
| 197 | |
| 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. |
| 200 | |
| 201 | |
| 202 | .. method:: array.pop([i]) |
| 203 | |
| 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 |
| 206 | returned. |
| 207 | |
| 208 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 209 | .. method:: array.remove(x) |
| 210 | |
| 211 | Remove the first occurrence of *x* from the array. |
| 212 | |
| 213 | |
| 214 | .. method:: array.reverse() |
| 215 | |
| 216 | Reverse the order of the items in the array. |
| 217 | |
| 218 | |
Antoine Pitrou | 1ce3eb5 | 2010-09-01 20:29:34 +0000 | [diff] [blame] | 219 | .. method:: array.tobytes() |
| 220 | |
| 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.) |
| 224 | |
| 225 | .. versionadded:: 3.2 |
| 226 | :meth:`tostring` is renamed to :meth:`tobytes` for clarity. |
| 227 | |
| 228 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 229 | .. method:: array.tofile(f) |
| 230 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 231 | Write all items (as machine values) to the :term:`file object` *f*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 232 | |
| 233 | |
| 234 | .. method:: array.tolist() |
| 235 | |
| 236 | Convert the array to an ordinary list with the same items. |
| 237 | |
| 238 | |
| 239 | .. method:: array.tostring() |
| 240 | |
Antoine Pitrou | 1ce3eb5 | 2010-09-01 20:29:34 +0000 | [diff] [blame] | 241 | Deprecated alias for :meth:`tobytes`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 242 | |
| 243 | |
| 244 | .. method:: array.tounicode() |
| 245 | |
| 246 | Convert the array to a unicode string. The array must be a type ``'u'`` array; |
Antoine Pitrou | 1ce3eb5 | 2010-09-01 20:29:34 +0000 | [diff] [blame] | 247 | otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 248 | obtain a unicode string from an array of some other type. |
| 249 | |
| 250 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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 |
Georg Brandl | d2aa7e6 | 2008-12-06 08:12:11 +0000 | [diff] [blame] | 253 | empty, otherwise it is a string if the *typecode* is ``'u'``, otherwise it is a |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 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``. |
| 257 | Examples:: |
| 258 | |
| 259 | array('l') |
Georg Brandl | d2aa7e6 | 2008-12-06 08:12:11 +0000 | [diff] [blame] | 260 | array('u', 'hello \u2641') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 261 | array('l', [1, 2, 3, 4, 5]) |
| 262 | array('d', [1.0, 2.0, 3.14]) |
| 263 | |
| 264 | |
| 265 | .. seealso:: |
| 266 | |
| 267 | Module :mod:`struct` |
| 268 | Packing and unpacking of heterogeneous binary data. |
| 269 | |
| 270 | Module :mod:`xdrlib` |
| 271 | Packing and unpacking of External Data Representation (XDR) data as used in some |
| 272 | remote procedure call systems. |
| 273 | |
| 274 | `The Numerical Python Manual <http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm>`_ |
| 275 | The Numeric Python extension (NumPy) defines another array type; see |
| 276 | http://numpy.sourceforge.net/ for further information about Numerical Python. |
| 277 | (A PDF version of the NumPy manual is available at |
| 278 | http://numpy.sourceforge.net/numdoc/numdoc.pdf). |
| 279 | |