Mercurial > cpython-lru_cache-weakref

annotate Doc/library/array.rst @ 66807:d28126ebd60d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Entries for datetime, callable, and collections.Counter.
author Raymond Hettinger <python@rcn.com>
date Thu, 09 Dec 2010 16:41:54 +0000
parents 521eac31a893
children 999b1aa24678
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68 .. data:: ArrayType
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69
55617
a267c604465f Recorded merge of revisions 74057 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
70 Obsolete alias for :class:`array`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
43777
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
72 .. data:: typecodes
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
73
0d462d789b18 Merging the py3k-pep3137 branch back into the py3k branch.
Guido van Rossum <guido@python.org>
parents: 43176
diff changeset
74 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
75
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 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
77 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
78 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
79 :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
80 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
81
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 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
83
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 .. attribute:: array.typecode
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 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
87
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 .. attribute:: array.itemsize
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 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
92
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 .. method:: array.append(x)
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 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
97
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99 .. method:: array.buffer_info()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 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
102 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
103 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
104 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
105 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
106 :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
107 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
108
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109 .. note::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 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
112 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
113 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
114 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
115 documented in :ref:`bufferobjects`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 .. method:: array.byteswap()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 "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
121 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
122 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
123 different byte order.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126 .. method:: array.count(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 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
129
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 .. method:: array.extend(iterable)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 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
134 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
135 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
136 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
137
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
139 .. method:: array.frombytes(s)
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
140
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
141 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
142 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
143
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
144 .. versionadded:: 3.2
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
145 :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
146
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
147
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 .. method:: array.fromfile(f, n)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
64763
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 64355
diff changeset
150 Read *n* items (as machine values) from the :term:`file object` *f* and append
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 64355
diff changeset
151 them to the end of the array. If less than *n* items are available,
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 64355
diff changeset
152 :exc:`EOFError` is raised, but the items that were available are still
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 64355
diff changeset
153 inserted into the array. *f* must be a real built-in file object; something
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 64355
diff changeset
154 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
155
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 .. method:: array.fromlist(list)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 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
160 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
161
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
163 .. method:: array.fromstring()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
165 Deprecated alias for :meth:`frombytes`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 .. method:: array.fromunicode(s)
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 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
171 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
172 ``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
173 array of some other type.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
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 .. method:: array.index(x)
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 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
179 *x* in the array.
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.insert(i, x)
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 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
185 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
186
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 .. method:: array.pop([i])
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 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
191 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
192 returned.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193
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 .. method:: array.remove(x)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197 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
198
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 .. method:: array.reverse()
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 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
203
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
205 .. method:: array.tobytes()
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 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
208 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
209 the :meth:`tofile` method.)
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
210
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
211 .. versionadded:: 3.2
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
212 :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
213
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
214
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 .. method:: array.tofile(f)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216
64763
bed950cbd0c0 Add cross-references to the glossary entry for file objects.
Antoine Pitrou <solipsis@pitrou.net>
parents: 64355
diff changeset
217 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
218
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 .. method:: array.tolist()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 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
223
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 .. method:: array.tostring()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
64355
fa8b57f987c5 Issue #8990: array.fromstring() and array.tostring() get renamed to
Antoine Pitrou <solipsis@pitrou.net>
parents: 55617
diff changeset
227 Deprecated alias for :meth:`tobytes`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 .. method:: array.tounicode()
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 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
233 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
234 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
235
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237 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
238 ``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
239 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
240 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
241 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
242 :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
243 Examples::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
244
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
245 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
246 array('u', 'hello \u2641')
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
247 array('l', [1, 2, 3, 4, 5])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
248 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
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 .. seealso::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
252
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
253 Module :mod:`struct`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
254 Packing and unpacking of heterogeneous binary data.
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 Module :mod:`xdrlib`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
257 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
258 remote procedure call systems.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
259
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
260 `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
261 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
262 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
263 (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
264 http://numpy.sourceforge.net/numdoc/numdoc.pdf).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
265