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