Mercurial > cpython-lru_cache-weakref

annotate Doc/library/array.rst @ 70817:dd775b1561ba

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Fix markup.
author Georg Brandl <georg@python.org>
date Tue, 14 Jun 2011 21:09:55 +0200
parents 3c9232a684ae
children 15659e0e2b2e
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 | Type code | C Type | Python Type | Minimum size in bytes |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 +===========+================+===================+=======================+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20 | ``'b'`` | signed char | int | 1 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 | ``'B'`` | unsigned char | int | 1 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 +-----------+----------------+-------------------+-----------------------+
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
24 | ``'u'`` | Py_UNICODE | Unicode character | 2 (see note) |
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 | ``'h'`` | signed short | int | 2 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28 | ``'H'`` | unsigned short | int | 2 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30 | ``'i'`` | signed int | int | 2 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 +-----------+----------------+-------------------+-----------------------+
44053
f2385d98282a Remove further mentions of long integers.
Georg Brandl <georg@python.org>
parents: 44052
diff changeset
32 | ``'I'`` | unsigned int | int | 2 |
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 | ``'l'`` | signed long | int | 4 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 +-----------+----------------+-------------------+-----------------------+
44053
f2385d98282a Remove further mentions of long integers.
Georg Brandl <georg@python.org>
parents: 44052
diff changeset
36 | ``'L'`` | unsigned long | int | 4 |
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38 | ``'f'`` | float | float | 4 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 | ``'d'`` | double | float | 8 |
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41 +-----------+----------------+-------------------+-----------------------+
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42
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
43 .. note::
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
44
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
45 The ``'u'`` typecode corresponds to Python's unicode character. On narrow
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
46 Unicode builds this is 2-bytes, on wide builds this is 4-bytes.
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
47
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 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
49 (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
50 through the :attr:`itemsize` attribute.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 The module defines the following type:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
53
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
54
55617
a267c604465f Recorded merge of revisions 74057 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
55 .. class:: array(typecode[, initializer])
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
55617
a267c604465f Recorded merge of revisions 74057 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
57 A new array whose items are restricted by *typecode*, and initialized
43777
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
58 from the optional *initializer* value, which must be a list, object
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 50076
diff changeset
59 supporting the buffer interface, 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
60 appropriate type.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62 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
63 :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
64 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
65 passed to the :meth:`extend` method.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67
43777
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
68 .. data:: typecodes
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
69
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
70 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
71
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
72 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
73 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
74 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
75 :exc:`TypeError` is raised. Array objects also implement the buffer interface,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 and may be used wherever buffer objects are supported.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 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
79
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 .. attribute:: array.typecode
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 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
83
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 .. attribute:: array.itemsize
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 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
88
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 .. method:: array.append(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 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
93
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 .. method:: array.buffer_info()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 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
98 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
99 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
100 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
101 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
102 :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
103 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
104
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
105 .. note::
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 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
108 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
109 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
110 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
111 documented in :ref:`bufferobjects`.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 .. method:: array.byteswap()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 "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
117 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
118 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
119 different byte order.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 .. method:: array.count(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 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
125
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 .. method:: array.extend(iterable)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 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
130 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
131 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
132 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
133
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
135 .. method:: array.frombytes(s)
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
136
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
137 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
138 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
139
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
140 .. versionadded:: 3.2
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
141 :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
142
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
143
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 .. method:: array.fromfile(f, n)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145
64767
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
146 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
147 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
148 :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
149 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
150 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
151
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 .. method:: array.fromlist(list)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 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
156 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
157
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
159 .. method:: array.fromstring()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
161 Deprecated alias for :meth:`frombytes`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 .. method:: array.fromunicode(s)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 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
167 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
168 ``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
169 array of some other type.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 .. method:: array.index(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 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
175 *x* in the array.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 .. method:: array.insert(i, x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 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
181 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
182
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 .. method:: array.pop([i])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 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
187 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
188 returned.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191 .. method:: array.remove(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 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
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.reverse()
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 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
199
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
201 .. method:: array.tobytes()
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
202
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
203 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
204 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
205 the :meth:`tofile` method.)
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
206
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
207 .. versionadded:: 3.2
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
208 :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
209
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
210
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 .. method:: array.tofile(f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212
64767
61dfc79657d7 Merged revisions 84827-84829 via svnmerge from
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
213 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
214
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 .. method:: array.tolist()
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 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
219
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 .. method:: array.tostring()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
223 Deprecated alias for :meth:`tobytes`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226 .. method:: array.tounicode()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
227
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 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
229 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
230 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
231
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 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
234 ``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
235 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
236 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
237 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
238 :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
239 Examples::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
240
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
241 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
242 array('u', 'hello \u2641')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
243 array('l', [1, 2, 3, 4, 5])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244 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
245
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
246
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
249 Module :mod:`struct`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
250 Packing and unpacking of heterogeneous binary data.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
251
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
252 Module :mod:`xdrlib`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 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
254 remote procedure call systems.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
255
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
256 `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
257 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
258 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
259 (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
260 http://numpy.sourceforge.net/numdoc/numdoc.pdf).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
261