cpython/Doc/library/array.rst

250 lines
9.4 KiB
ReStructuredText
Raw Normal View History

2007-08-15 11:28:22 -03:00
:mod:`array` --- Efficient arrays of numeric values
===================================================
.. module:: array
Merged revisions 62021,62029,62035-62038,62043-62044,62052-62053 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62021 | benjamin.peterson | 2008-03-28 18:11:01 -0500 (Fri, 28 Mar 2008) | 2 lines NIL => NULL ........ r62029 | amaury.forgeotdarc | 2008-03-28 20:42:31 -0500 (Fri, 28 Mar 2008) | 3 lines Correctly call the base class tearDown(); otherwise running test_logging twice produce the errors we see on all buildbots ........ r62035 | raymond.hettinger | 2008-03-29 05:42:07 -0500 (Sat, 29 Mar 2008) | 1 line Be explicit about what efficient means. ........ r62036 | georg.brandl | 2008-03-29 06:46:18 -0500 (Sat, 29 Mar 2008) | 2 lines Fix capitalization. ........ r62037 | amaury.forgeotdarc | 2008-03-29 07:42:54 -0500 (Sat, 29 Mar 2008) | 5 lines lib2to3 should install a logging handler only when run as a main program, not when used as a library. This may please the buildbots, which fail when test_lib2to3 is run before test_logging. ........ r62043 | benjamin.peterson | 2008-03-29 10:24:25 -0500 (Sat, 29 Mar 2008) | 3 lines #2503 make singletons compared with "is" not == or != Thanks to Wummel for the patch ........ r62044 | gerhard.haering | 2008-03-29 14:11:52 -0500 (Sat, 29 Mar 2008) | 2 lines Documented the lastrowid attribute. ........ r62052 | benjamin.peterson | 2008-03-30 14:35:10 -0500 (Sun, 30 Mar 2008) | 2 lines Updated README regarding doc formats ........ r62053 | georg.brandl | 2008-03-30 14:41:39 -0500 (Sun, 30 Mar 2008) | 2 lines The other download formats will be available for 2.6 too. ........
2008-03-30 22:51:45 -03:00
:synopsis: Space efficient arrays of uniformly typed numeric values.
2007-08-15 11:28:22 -03:00
.. index:: single: arrays
Merged revisions 62021,62029,62035-62038,62043-62044,62052-62053 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62021 | benjamin.peterson | 2008-03-28 18:11:01 -0500 (Fri, 28 Mar 2008) | 2 lines NIL => NULL ........ r62029 | amaury.forgeotdarc | 2008-03-28 20:42:31 -0500 (Fri, 28 Mar 2008) | 3 lines Correctly call the base class tearDown(); otherwise running test_logging twice produce the errors we see on all buildbots ........ r62035 | raymond.hettinger | 2008-03-29 05:42:07 -0500 (Sat, 29 Mar 2008) | 1 line Be explicit about what efficient means. ........ r62036 | georg.brandl | 2008-03-29 06:46:18 -0500 (Sat, 29 Mar 2008) | 2 lines Fix capitalization. ........ r62037 | amaury.forgeotdarc | 2008-03-29 07:42:54 -0500 (Sat, 29 Mar 2008) | 5 lines lib2to3 should install a logging handler only when run as a main program, not when used as a library. This may please the buildbots, which fail when test_lib2to3 is run before test_logging. ........ r62043 | benjamin.peterson | 2008-03-29 10:24:25 -0500 (Sat, 29 Mar 2008) | 3 lines #2503 make singletons compared with "is" not == or != Thanks to Wummel for the patch ........ r62044 | gerhard.haering | 2008-03-29 14:11:52 -0500 (Sat, 29 Mar 2008) | 2 lines Documented the lastrowid attribute. ........ r62052 | benjamin.peterson | 2008-03-30 14:35:10 -0500 (Sun, 30 Mar 2008) | 2 lines Updated README regarding doc formats ........ r62053 | georg.brandl | 2008-03-30 14:41:39 -0500 (Sun, 30 Mar 2008) | 2 lines The other download formats will be available for 2.6 too. ........
2008-03-30 22:51:45 -03:00
This module defines an object type which can compactly represent an array of
2007-08-15 11:28:22 -03:00
basic values: characters, integers, floating point numbers. Arrays are sequence
types and behave very much like lists, except that the type of objects stored in
them is constrained. The type is specified at object creation time by using a
:dfn:`type code`, which is a single character. The following type codes are
defined:
+-----------+----------------+-------------------+-----------------------+
| Type code | C Type | Python Type | Minimum size in bytes |
+===========+================+===================+=======================+
| ``'b'`` | signed char | int | 1 |
+-----------+----------------+-------------------+-----------------------+
| ``'B'`` | unsigned char | int | 1 |
+-----------+----------------+-------------------+-----------------------+
Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ................ r73941 | georg.brandl | 2009-07-11 12:39:00 +0200 (Sa, 11 Jul 2009) | 9 lines Merged revisions 73940 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r73940 | georg.brandl | 2009-07-11 12:37:38 +0200 (Sa, 11 Jul 2009) | 1 line #6430: add note about size of "u" type. ........ ................ r73942 | georg.brandl | 2009-07-11 12:39:23 +0200 (Sa, 11 Jul 2009) | 1 line #6430: remove mention of "w" array typecode. ................ r73943 | georg.brandl | 2009-07-11 12:43:08 +0200 (Sa, 11 Jul 2009) | 1 line #6421: The self argument of module-level PyCFunctions is now a reference to the module object. ................ r74076 | georg.brandl | 2009-07-18 11:07:48 +0200 (Sa, 18 Jul 2009) | 1 line #6502: add missing comma in docstring. ................ r74094 | georg.brandl | 2009-07-19 09:25:56 +0200 (So, 19 Jul 2009) | 10 lines Recorded merge of revisions 74089 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74089 | senthil.kumaran | 2009-07-19 04:43:43 +0200 (So, 19 Jul 2009) | 3 lines Fix for issue5102, timeout value propages between redirects, proxy, digest and auth handlers. Fixed tests to reflect the same. ........ ................ r74186 | georg.brandl | 2009-07-23 11:19:09 +0200 (Do, 23 Jul 2009) | 9 lines Recorded merge of revisions 74185 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74185 | georg.brandl | 2009-07-23 11:17:09 +0200 (Do, 23 Jul 2009) | 1 line Fix the "pylocals" gdb command. ........ ................ r74211 | georg.brandl | 2009-07-26 16:48:09 +0200 (So, 26 Jul 2009) | 9 lines Recorded merge of revisions 74210 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74210 | georg.brandl | 2009-07-26 16:44:23 +0200 (So, 26 Jul 2009) | 1 line Move member descriptions inside the classes. ........ ................ r74212 | georg.brandl | 2009-07-26 16:54:51 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74209 | georg.brandl | 2009-07-26 16:37:28 +0200 (So, 26 Jul 2009) | 1 line builtin -> built-in. ........ ................ r74213 | georg.brandl | 2009-07-26 17:02:41 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74207 | georg.brandl | 2009-07-26 16:19:57 +0200 (So, 26 Jul 2009) | 1 line #6577: fix (hopefully) all links to builtin instead of module/class-specific objects. ........ ................ r74214 | georg.brandl | 2009-07-26 17:03:49 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74205 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74205 | georg.brandl | 2009-07-26 15:36:39 +0200 (So, 26 Jul 2009) | 1 line #6576: fix cross-refs in re docs. ........ ................ r74247 | georg.brandl | 2009-07-29 09:27:08 +0200 (Mi, 29 Jul 2009) | 9 lines Merged revisions 74239 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74239 | georg.brandl | 2009-07-28 18:55:32 +0000 (Di, 28 Jul 2009) | 1 line Clarify quote_plus() usage. ........ ................ r74254 | georg.brandl | 2009-07-29 18:14:16 +0200 (Mi, 29 Jul 2009) | 1 line #6586: fix return/argument type doc for os.read() and os.write(). ................ r74262 | alexandre.vassalotti | 2009-07-29 21:54:39 +0200 (Mi, 29 Jul 2009) | 57 lines Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line #6513: fix example code: warning categories are classes, not instances. ........ r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line #6489: fix an ambiguity in getiterator() documentation. ........ r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line remove docs for deprecated -p option ........ r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line use bools ........ r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line Fix arg types of et#. ........ r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line Dont put "void" in signature for nullary functions. ........ r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line #6571: add index entries for more operators. ........ r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line #6593: fix link targets. ........ r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line #6591: add reference to ioctl in fcntl module for platforms other than Windows. ........ r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line Add a link to readline, and mention IPython and bpython. ........ r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line Fix some markup and small factual glitches found by M. Markert. ........ r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line Fix a few markup glitches. ........ r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better. ........ ................ r74311 | georg.brandl | 2009-08-04 22:29:27 +0200 (Di, 04 Aug 2009) | 1 line Slightly improve buffer-related error message. ................ r74334 | georg.brandl | 2009-08-06 19:51:03 +0200 (Do, 06 Aug 2009) | 1 line #6648: mention surrogateescape handler where all standard handlers are listed. ................ r74368 | georg.brandl | 2009-08-13 09:56:35 +0200 (Do, 13 Aug 2009) | 21 lines Merged revisions 74328,74332-74333,74365 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74328 | georg.brandl | 2009-08-06 17:06:25 +0200 (Do, 06 Aug 2009) | 1 line Fix base keyword arg name for int() and long(). ........ r74332 | georg.brandl | 2009-08-06 19:23:21 +0200 (Do, 06 Aug 2009) | 1 line Fix punctuation and one copy-paste error. ........ r74333 | georg.brandl | 2009-08-06 19:43:55 +0200 (Do, 06 Aug 2009) | 1 line #6658: fix two typos. ........ r74365 | georg.brandl | 2009-08-13 09:48:05 +0200 (Do, 13 Aug 2009) | 1 line #6679: Remove mention that sub supports no flags. ........ ................
2009-08-13 05:26:44 -03:00
| ``'u'`` | Py_UNICODE | Unicode character | 2 (see note) |
2007-08-15 11:28:22 -03:00
+-----------+----------------+-------------------+-----------------------+
| ``'h'`` | signed short | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'H'`` | unsigned short | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'i'`` | signed int | int | 2 |
+-----------+----------------+-------------------+-----------------------+
| ``'I'`` | unsigned int | int | 2 |
2007-08-15 11:28:22 -03:00
+-----------+----------------+-------------------+-----------------------+
| ``'l'`` | signed long | int | 4 |
+-----------+----------------+-------------------+-----------------------+
| ``'L'`` | unsigned long | int | 4 |
2007-08-15 11:28:22 -03:00
+-----------+----------------+-------------------+-----------------------+
| ``'f'`` | float | float | 4 |
+-----------+----------------+-------------------+-----------------------+
| ``'d'`` | double | float | 8 |
+-----------+----------------+-------------------+-----------------------+
Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ................ r73941 | georg.brandl | 2009-07-11 12:39:00 +0200 (Sa, 11 Jul 2009) | 9 lines Merged revisions 73940 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r73940 | georg.brandl | 2009-07-11 12:37:38 +0200 (Sa, 11 Jul 2009) | 1 line #6430: add note about size of "u" type. ........ ................ r73942 | georg.brandl | 2009-07-11 12:39:23 +0200 (Sa, 11 Jul 2009) | 1 line #6430: remove mention of "w" array typecode. ................ r73943 | georg.brandl | 2009-07-11 12:43:08 +0200 (Sa, 11 Jul 2009) | 1 line #6421: The self argument of module-level PyCFunctions is now a reference to the module object. ................ r74076 | georg.brandl | 2009-07-18 11:07:48 +0200 (Sa, 18 Jul 2009) | 1 line #6502: add missing comma in docstring. ................ r74094 | georg.brandl | 2009-07-19 09:25:56 +0200 (So, 19 Jul 2009) | 10 lines Recorded merge of revisions 74089 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74089 | senthil.kumaran | 2009-07-19 04:43:43 +0200 (So, 19 Jul 2009) | 3 lines Fix for issue5102, timeout value propages between redirects, proxy, digest and auth handlers. Fixed tests to reflect the same. ........ ................ r74186 | georg.brandl | 2009-07-23 11:19:09 +0200 (Do, 23 Jul 2009) | 9 lines Recorded merge of revisions 74185 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74185 | georg.brandl | 2009-07-23 11:17:09 +0200 (Do, 23 Jul 2009) | 1 line Fix the "pylocals" gdb command. ........ ................ r74211 | georg.brandl | 2009-07-26 16:48:09 +0200 (So, 26 Jul 2009) | 9 lines Recorded merge of revisions 74210 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74210 | georg.brandl | 2009-07-26 16:44:23 +0200 (So, 26 Jul 2009) | 1 line Move member descriptions inside the classes. ........ ................ r74212 | georg.brandl | 2009-07-26 16:54:51 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74209 | georg.brandl | 2009-07-26 16:37:28 +0200 (So, 26 Jul 2009) | 1 line builtin -> built-in. ........ ................ r74213 | georg.brandl | 2009-07-26 17:02:41 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74207 | georg.brandl | 2009-07-26 16:19:57 +0200 (So, 26 Jul 2009) | 1 line #6577: fix (hopefully) all links to builtin instead of module/class-specific objects. ........ ................ r74214 | georg.brandl | 2009-07-26 17:03:49 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74205 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74205 | georg.brandl | 2009-07-26 15:36:39 +0200 (So, 26 Jul 2009) | 1 line #6576: fix cross-refs in re docs. ........ ................ r74247 | georg.brandl | 2009-07-29 09:27:08 +0200 (Mi, 29 Jul 2009) | 9 lines Merged revisions 74239 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74239 | georg.brandl | 2009-07-28 18:55:32 +0000 (Di, 28 Jul 2009) | 1 line Clarify quote_plus() usage. ........ ................ r74254 | georg.brandl | 2009-07-29 18:14:16 +0200 (Mi, 29 Jul 2009) | 1 line #6586: fix return/argument type doc for os.read() and os.write(). ................ r74262 | alexandre.vassalotti | 2009-07-29 21:54:39 +0200 (Mi, 29 Jul 2009) | 57 lines Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line #6513: fix example code: warning categories are classes, not instances. ........ r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line #6489: fix an ambiguity in getiterator() documentation. ........ r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line remove docs for deprecated -p option ........ r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line use bools ........ r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line Fix arg types of et#. ........ r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line Dont put "void" in signature for nullary functions. ........ r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line #6571: add index entries for more operators. ........ r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line #6593: fix link targets. ........ r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line #6591: add reference to ioctl in fcntl module for platforms other than Windows. ........ r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line Add a link to readline, and mention IPython and bpython. ........ r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line Fix some markup and small factual glitches found by M. Markert. ........ r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line Fix a few markup glitches. ........ r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better. ........ ................ r74311 | georg.brandl | 2009-08-04 22:29:27 +0200 (Di, 04 Aug 2009) | 1 line Slightly improve buffer-related error message. ................ r74334 | georg.brandl | 2009-08-06 19:51:03 +0200 (Do, 06 Aug 2009) | 1 line #6648: mention surrogateescape handler where all standard handlers are listed. ................ r74368 | georg.brandl | 2009-08-13 09:56:35 +0200 (Do, 13 Aug 2009) | 21 lines Merged revisions 74328,74332-74333,74365 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74328 | georg.brandl | 2009-08-06 17:06:25 +0200 (Do, 06 Aug 2009) | 1 line Fix base keyword arg name for int() and long(). ........ r74332 | georg.brandl | 2009-08-06 19:23:21 +0200 (Do, 06 Aug 2009) | 1 line Fix punctuation and one copy-paste error. ........ r74333 | georg.brandl | 2009-08-06 19:43:55 +0200 (Do, 06 Aug 2009) | 1 line #6658: fix two typos. ........ r74365 | georg.brandl | 2009-08-13 09:48:05 +0200 (Do, 13 Aug 2009) | 1 line #6679: Remove mention that sub supports no flags. ........ ................
2009-08-13 05:26:44 -03:00
.. note::
The ``'u'`` typecode corresponds to Python's unicode character. On narrow
Unicode builds this is 2-bytes, on wide builds this is 4-bytes.
2007-08-15 11:28:22 -03:00
The actual representation of values is determined by the machine architecture
(strictly speaking, by the C implementation). The actual size can be accessed
through the :attr:`itemsize` attribute.
2007-08-15 11:28:22 -03:00
The module defines the following type:
.. class:: array(typecode[, initializer])
2007-08-15 11:28:22 -03:00
A new array whose items are restricted by *typecode*, and initialized
from the optional *initializer* value, which must be a list, object
2009-01-03 17:18:54 -04:00
supporting the buffer interface, or iterable over elements of the
appropriate type.
2007-08-15 11:28:22 -03:00
If given a list or string, the initializer is passed to the new array's
:meth:`fromlist`, :meth:`fromstring`, or :meth:`fromunicode` method (see below)
to add initial items to the array. Otherwise, the iterable initializer is
passed to the :meth:`extend` method.
.. data:: ArrayType
Obsolete alias for :class:`array`.
2007-08-15 11:28:22 -03:00
.. data:: typecodes
A string with all available type codes.
2007-08-15 11:28:22 -03:00
Array objects support the ordinary sequence operations of indexing, slicing,
concatenation, and multiplication. When using slice assignment, the assigned
value must be an array object with the same type code; in all other cases,
:exc:`TypeError` is raised. Array objects also implement the buffer interface,
and may be used wherever buffer objects are supported.
The following data items and methods are also supported:
.. attribute:: array.typecode
The typecode character used to create the array.
.. attribute:: array.itemsize
The length in bytes of one array item in the internal representation.
.. method:: array.append(x)
Append a new item with value *x* to the end of the array.
.. method:: array.buffer_info()
Return a tuple ``(address, length)`` giving the current memory address and the
length in elements of the buffer used to hold array's contents. The size of the
memory buffer in bytes can be computed as ``array.buffer_info()[1] *
array.itemsize``. This is occasionally useful when working with low-level (and
inherently unsafe) I/O interfaces that require memory addresses, such as certain
:cfunc:`ioctl` operations. The returned numbers are valid as long as the array
exists and no length-changing operations are applied to it.
.. note::
When using array objects from code written in C or C++ (the only way to
effectively make use of this information), it makes more sense to use the buffer
interface supported by array objects. This method is maintained for backward
compatibility and should be avoided in new code. The buffer interface is
documented in :ref:`bufferobjects`.
.. method:: array.byteswap()
"Byteswap" all items of the array. This is only supported for values which are
1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
raised. It is useful when reading data from a file written on a machine with a
different byte order.
.. method:: array.count(x)
Return the number of occurrences of *x* in the array.
.. method:: array.extend(iterable)
Append items from *iterable* to the end of the array. If *iterable* is another
array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
be raised. If *iterable* is not an array, it must be iterable and its elements
must be the right type to be appended to the array.
.. method:: array.fromfile(f, n)
Read *n* items (as machine values) from the :term:`file object` *f* and append
them to the end of the array. If less than *n* items are available,
:exc:`EOFError` is raised, but the items that were available are still
inserted into the array. *f* must be a real built-in file object; something
else with a :meth:`read` method won't do.
2007-08-15 11:28:22 -03:00
.. method:: array.fromlist(list)
Append items from the list. This is equivalent to ``for x in list:
a.append(x)`` except that if there is a type error, the array is unchanged.
.. method:: array.fromstring(s)
Appends items from the string, interpreting the string as an array of machine
values (as if it had been read from a file using the :meth:`fromfile` method).
.. method:: array.fromunicode(s)
Extends this array with data from the given unicode string. The array must
be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised. Use
``array.fromstring(unicodestring.encode(enc))`` to append Unicode data to an
array of some other type.
.. method:: array.index(x)
Return the smallest *i* such that *i* is the index of the first occurrence of
*x* in the array.
.. method:: array.insert(i, x)
Insert a new item with value *x* in the array before position *i*. Negative
values are treated as being relative to the end of the array.
.. method:: array.pop([i])
Removes the item with the index *i* from the array and returns it. The optional
argument defaults to ``-1``, so that by default the last item is removed and
returned.
.. method:: array.remove(x)
Remove the first occurrence of *x* from the array.
.. method:: array.reverse()
Reverse the order of the items in the array.
.. method:: array.tofile(f)
Write all items (as machine values) to the :term:`file object` *f*.
2007-08-15 11:28:22 -03:00
.. method:: array.tolist()
Convert the array to an ordinary list with the same items.
.. method:: array.tostring()
Convert the array to an array of machine values and return the string
representation (the same sequence of bytes that would be written to a file by
the :meth:`tofile` method.)
.. method:: array.tounicode()
Convert the array to a unicode string. The array must be a type ``'u'`` array;
otherwise a :exc:`ValueError` is raised. Use ``array.tostring().decode(enc)`` to
obtain a unicode string from an array of some other type.
When an array object is printed or converted to a string, it is represented as
``array(typecode, initializer)``. The *initializer* is omitted if the array is
empty, otherwise it is a string if the *typecode* is ``'u'``, otherwise it is a
2007-08-15 11:28:22 -03:00
list of numbers. The string is guaranteed to be able to be converted back to an
array with the same type and value using :func:`eval`, so long as the
:func:`array` function has been imported using ``from array import array``.
Examples::
array('l')
array('u', 'hello \u2641')
2007-08-15 11:28:22 -03:00
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])
.. seealso::
Module :mod:`struct`
Packing and unpacking of heterogeneous binary data.
Module :mod:`xdrlib`
Packing and unpacking of External Data Representation (XDR) data as used in some
remote procedure call systems.
`The Numerical Python Manual <http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm>`_
The Numeric Python extension (NumPy) defines another array type; see
http://numpy.sourceforge.net/ for further information about Numerical Python.
(A PDF version of the NumPy manual is available at
http://numpy.sourceforge.net/numdoc/numdoc.pdf).