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