Mercurial > cpython-lru_cache-weakref

annotate Doc/library/array.rst @ 84007:dbfbdf2b5c19 3.3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix #17967: For ftp urls CWD to target instead of hopping to each directory towards target. This fixes a bug where target is accessible, but parent directories are restricted.
author Senthil Kumaran <senthil@uthcode.com>
date Sat, 01 Jun 2013 08:27:06 -0700
parents 003e4eb92683
children aafa11c1dd61
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1 :mod:`array` --- Efficient arrays of numeric values
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 ===================================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. module:: array
46222
aed698c8647b Merged revisions 62021,62029,62035-62038,62043-62044,62052-62053 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 45084
diff changeset
5 :synopsis: Space efficient arrays of uniformly typed numeric values.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index:: single: arrays
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
46222
aed698c8647b Merged revisions 62021,62029,62035-62038,62043-62044,62052-62053 via svnmerge from
Benjamin Peterson <benjamin@python.org>
parents: 45084
diff changeset
10 This module defines an object type which can compactly represent an array of
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 basic values: characters, integers, floating point numbers. Arrays are sequence
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12 types and behave very much like lists, except that the type of objects stored in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 them is constrained. The type is specified at object creation time by using a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 :dfn:`type code`, which is a single character. The following type codes are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15 defined:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16
72430
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
17 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
18 | Type code | C Type | Python Type | Minimum size in bytes | Notes |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
19 +===========+====================+===================+=======================+=======+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
20 | ``'b'`` | signed char | int | 1 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
21 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
22 | ``'B'`` | unsigned char | int | 1 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
23 +-----------+--------------------+-------------------+-----------------------+-------+
78447
95da47ddebe0 Close #13072: Restore code before the PEP 393 for the array module
Victor Stinner <victor.stinner@gmail.com>
parents: 73120
diff changeset
24 | ``'u'`` | Py_UNICODE | Unicode character | 2 | \(1) |
72430
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
25 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
26 | ``'h'`` | signed short | int | 2 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
27 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
28 | ``'H'`` | unsigned short | int | 2 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
29 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
30 | ``'i'`` | signed int | int | 2 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
31 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
32 | ``'I'`` | unsigned int | int | 2 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
33 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
34 | ``'l'`` | signed long | int | 4 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
35 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
36 | ``'L'`` | unsigned long | int | 4 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
37 +-----------+--------------------+-------------------+-----------------------+-------+
78447
95da47ddebe0 Close #13072: Restore code before the PEP 393 for the array module
Victor Stinner <victor.stinner@gmail.com>
parents: 73120
diff changeset
38 | ``'q'`` | signed long long | int | 8 | \(2) |
72430
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
39 +-----------+--------------------+-------------------+-----------------------+-------+
78447
95da47ddebe0 Close #13072: Restore code before the PEP 393 for the array module
Victor Stinner <victor.stinner@gmail.com>
parents: 73120
diff changeset
40 | ``'Q'`` | unsigned long long | int | 8 | \(2) |
72430
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
41 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
42 | ``'f'`` | float | float | 4 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
43 +-----------+--------------------+-------------------+-----------------------+-------+
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
44 | ``'d'`` | double | float | 8 | |
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
45 +-----------+--------------------+-------------------+-----------------------+-------+
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
46
72430
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
47 Notes:
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
48
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
49 (1)
78748
9c7515e29219 Issue #13072: The array module's 'u' format code is now deprecated and
Stefan Krah <skrah@bytereef.org>
parents: 78447
diff changeset
50 The ``'u'`` type code corresponds to Python's obsolete unicode character
78447
95da47ddebe0 Close #13072: Restore code before the PEP 393 for the array module
Victor Stinner <victor.stinner@gmail.com>
parents: 73120
diff changeset
51 (:c:type:`Py_UNICODE` which is :c:type:`wchar_t`). Depending on the
95da47ddebe0 Close #13072: Restore code before the PEP 393 for the array module
Victor Stinner <victor.stinner@gmail.com>
parents: 73120
diff changeset
52 platform, it can be 16 bits or 32 bits.
95da47ddebe0 Close #13072: Restore code before the PEP 393 for the array module
Victor Stinner <victor.stinner@gmail.com>
parents: 73120
diff changeset
53
78748
9c7515e29219 Issue #13072: The array module's 'u' format code is now deprecated and
Stefan Krah <skrah@bytereef.org>
parents: 78447
diff changeset
54 ``'u'`` will be removed together with the rest of the :c:type:`Py_UNICODE`
9c7515e29219 Issue #13072: The array module's 'u' format code is now deprecated and
Stefan Krah <skrah@bytereef.org>
parents: 78447
diff changeset
55 API.
9c7515e29219 Issue #13072: The array module's 'u' format code is now deprecated and
Stefan Krah <skrah@bytereef.org>
parents: 78447
diff changeset
56
9c7515e29219 Issue #13072: The array module's 'u' format code is now deprecated and
Stefan Krah <skrah@bytereef.org>
parents: 78447
diff changeset
57 .. deprecated-removed:: 3.3 4.0
9c7515e29219 Issue #13072: The array module's 'u' format code is now deprecated and
Stefan Krah <skrah@bytereef.org>
parents: 78447
diff changeset
58
78447
95da47ddebe0 Close #13072: Restore code before the PEP 393 for the array module
Victor Stinner <victor.stinner@gmail.com>
parents: 73120
diff changeset
59 (2)
72430
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
60 The ``'q'`` and ``'Q'`` type codes are available only if
72471
84280fac98b9 Fix markup.
Georg Brandl <georg@python.org>
parents: 72430
diff changeset
61 the platform C compiler used to build Python supports C :c:type:`long long`,
84280fac98b9 Fix markup.
Georg Brandl <georg@python.org>
parents: 72430
diff changeset
62 or, on Windows, :c:type:`__int64`.
72430
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
63
15659e0e2b2e Issue #1172711: Add 'long long' support to the array module.
Meador Inge <meadori@gmail.com>
parents: 68257
diff changeset
64 .. versionadded:: 3.3
55580
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 54170
diff changeset
65
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66 The actual representation of values is determined by the machine architecture
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 (strictly speaking, by the C implementation). The actual size can be accessed
44052
e6ca92b18cf4 Remove mentions of "long integer" in the docs.
Georg Brandl <georg@python.org>
parents: 43777
diff changeset
68 through the :attr:`itemsize` attribute.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 The module defines the following type:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72
55617
a267c604465f Recorded merge of revisions 74057 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
73 .. class:: array(typecode[, initializer])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
55617
a267c604465f Recorded merge of revisions 74057 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
75 A new array whose items are restricted by *typecode*, and initialized
83605
003e4eb92683 #16518: use "bytes-like object" throughout the docs.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78748
diff changeset
76 from the optional *initializer* value, which must be a list, a
003e4eb92683 #16518: use "bytes-like object" throughout the docs.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78748
diff changeset
77 :term:`bytes-like object`, or iterable over elements of the
43777
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
78 appropriate type.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 If given a list or string, the initializer is passed to the new array's
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
81 :meth:`fromlist`, :meth:`frombytes`, or :meth:`fromunicode` method (see below)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 to add initial items to the array. Otherwise, the iterable initializer is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83 passed to the :meth:`extend` method.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
43777
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
86 .. data:: typecodes
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
87
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
88 A string with all available type codes.
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
89
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 Array objects support the ordinary sequence operations of indexing, slicing,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 concatenation, and multiplication. When using slice assignment, the assigned
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 value must be an array object with the same type code; in all other cases,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 :exc:`TypeError` is raised. Array objects also implement the buffer interface,
83605
003e4eb92683 #16518: use "bytes-like object" throughout the docs.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 78748
diff changeset
94 and may be used wherever :term:`bytes-like object`\ s are supported.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 The following data items and methods are also supported:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 .. attribute:: array.typecode
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 The typecode character used to create the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 .. attribute:: array.itemsize
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 The length in bytes of one array item in the internal representation.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 .. method:: array.append(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110 Append a new item with value *x* to the end of the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 .. method:: array.buffer_info()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 Return a tuple ``(address, length)`` giving the current memory address and the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 length in elements of the buffer used to hold array's contents. The size of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 memory buffer in bytes can be computed as ``array.buffer_info()[1] *
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 array.itemsize``. This is occasionally useful when working with low-level (and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 inherently unsafe) I/O interfaces that require memory addresses, such as certain
65137
521eac31a893 Migrate to Sphinx 1.0 C language constructs.
Georg Brandl <georg@python.org>
parents: 64763
diff changeset
120 :c:func:`ioctl` operations. The returned numbers are valid as long as the array
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 exists and no length-changing operations are applied to it.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 .. note::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 When using array objects from code written in C or C++ (the only way to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 effectively make use of this information), it makes more sense to use the buffer
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 interface supported by array objects. This method is maintained for backward
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 compatibility and should be avoided in new code. The buffer interface is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 documented in :ref:`bufferobjects`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 .. method:: array.byteswap()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 "Byteswap" all items of the array. This is only supported for values which are
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 1, 2, 4, or 8 bytes in size; for other types of values, :exc:`RuntimeError` is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 raised. It is useful when reading data from a file written on a machine with a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 different byte order.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 .. method:: array.count(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142 Return the number of occurrences of *x* in the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 .. method:: array.extend(iterable)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 Append items from *iterable* to the end of the array. If *iterable* is another
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 array, it must have *exactly* the same type code; if not, :exc:`TypeError` will
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 be raised. If *iterable* is not an array, it must be iterable and its elements
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 must be the right type to be appended to the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
153 .. method:: array.frombytes(s)
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
154
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
155 Appends items from the string, interpreting the string as an array of machine
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
156 values (as if it had been read from a file using the :meth:`fromfile` method).
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
157
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
158 .. versionadded:: 3.2
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
159 :meth:`fromstring` is renamed to :meth:`frombytes` for clarity.
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
160
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
161
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 .. method:: array.fromfile(f, n)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
64767
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
164 Read *n* items (as machine values) from the :term:`file object` *f* and append
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
165 them to the end of the array. If less than *n* items are available,
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
166 :exc:`EOFError` is raised, but the items that were available are still
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
167 inserted into the array. *f* must be a real built-in file object; something
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
168 else with a :meth:`read` method won't do.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 .. method:: array.fromlist(list)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 Append items from the list. This is equivalent to ``for x in list:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 a.append(x)`` except that if there is a type error, the array is unchanged.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
177 .. method:: array.fromstring()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
179 Deprecated alias for :meth:`frombytes`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182 .. method:: array.fromunicode(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 Extends this array with data from the given unicode string. The array must
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 be a type ``'u'`` array; otherwise a :exc:`ValueError` is raised. Use
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
186 ``array.frombytes(unicodestring.encode(enc))`` to append Unicode data to an
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 array of some other type.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 .. method:: array.index(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 Return the smallest *i* such that *i* is the index of the first occurrence of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 *x* in the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 .. method:: array.insert(i, x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 Insert a new item with value *x* in the array before position *i*. Negative
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 values are treated as being relative to the end of the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 .. method:: array.pop([i])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 Removes the item with the index *i* from the array and returns it. The optional
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205 argument defaults to ``-1``, so that by default the last item is removed and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 returned.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 .. method:: array.remove(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 Remove the first occurrence of *x* from the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214 .. method:: array.reverse()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 Reverse the order of the items in the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
217
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
219 .. method:: array.tobytes()
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
220
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
221 Convert the array to an array of machine values and return the bytes
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
222 representation (the same sequence of bytes that would be written to a file by
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
223 the :meth:`tofile` method.)
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
224
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
225 .. versionadded:: 3.2
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
226 :meth:`tostring` is renamed to :meth:`tobytes` for clarity.
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
227
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
228
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229 .. method:: array.tofile(f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230
64767
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
231 Write all items (as machine values) to the :term:`file object` *f*.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234 .. method:: array.tolist()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236 Convert the array to an ordinary list with the same items.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
238
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
239 .. method:: array.tostring()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
241 Deprecated alias for :meth:`tobytes`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
242
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 .. method:: array.tounicode()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246 Convert the array to a unicode string. The array must be a type ``'u'`` array;
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
247 otherwise a :exc:`ValueError` is raised. Use ``array.tobytes().decode(enc)`` to
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 obtain a unicode string from an array of some other type.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
249
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
250
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251 When an array object is printed or converted to a string, it is represented as
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
252 ``array(typecode, initializer)``. The *initializer* is omitted if the array is
50076
c7abfab4dcdb Merged revisions 67525-67527,67529,67548-67549,67551-67552,67555,67578,67586,67593-67594,67596,67605-67606,67609,67612,67616-67617,67632,67635,67638 via svnmerge from
Georg Brandl <georg@python.org>
parents: 46222
diff changeset
253 empty, otherwise it is a string if the *typecode* is ``'u'``, otherwise it is a
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 list of numbers. The string is guaranteed to be able to be converted back to an
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255 array with the same type and value using :func:`eval`, so long as the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 :func:`array` function has been imported using ``from array import array``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 Examples::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
258
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259 array('l')
50076
c7abfab4dcdb Merged revisions 67525-67527,67529,67548-67549,67551-67552,67555,67578,67586,67593-67594,67596,67605-67606,67609,67612,67616-67617,67632,67635,67638 via svnmerge from
Georg Brandl <georg@python.org>
parents: 46222
diff changeset
260 array('u', 'hello \u2641')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261 array('l', [1, 2, 3, 4, 5])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
262 array('d', [1.0, 2.0, 3.14])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
263
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
264
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
266
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
267 Module :mod:`struct`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
268 Packing and unpacking of heterogeneous binary data.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
269
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
270 Module :mod:`xdrlib`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
271 Packing and unpacking of External Data Representation (XDR) data as used in some
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
272 remote procedure call systems.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
273
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
274 `The Numerical Python Manual <http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm>`_
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
275 The Numeric Python extension (NumPy) defines another array type; see
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
276 http://numpy.sourceforge.net/ for further information about Numerical Python.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
277 (A PDF version of the NumPy manual is available at
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
278 http://numpy.sourceforge.net/numdoc/numdoc.pdf).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
279