Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libarray.tex @ 37064:64c83e0f683e legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
More \exception fixes.
author Georg Brandl <georg@python.org>
date Fri, 17 Mar 2006 16:26:31 +0000
parents 016d7016c6c6
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{array} ---
10647
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
2 Efficient arrays of numeric values}
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
4 \declaremodule{builtin}{array}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
5 \modulesynopsis{Efficient arrays of uniformly typed numeric values.}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 8018
diff changeset
6
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
8 This module defines an object type which can efficiently represent
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
9 an array of basic values: characters, integers, floating point
10647
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
10 numbers. Arrays\index{arrays} are sequence types and behave very much
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
11 like lists, except that the type of objects stored in them is
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
12 constrained. The type is specified at object creation time by using a
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
13 \dfn{type code}, which is a single character. The following type
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
14 codes are defined:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
22759
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
16 \begin{tableiv}{c|l|l|c}{code}{Type code}{C Type}{Python Type}{Minimum size in bytes}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
17 \lineiv{'c'}{char} {character} {1}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
18 \lineiv{'b'}{signed char} {int} {1}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
19 \lineiv{'B'}{unsigned char} {int} {1}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
20 \lineiv{'u'}{Py_UNICODE} {Unicode character}{2}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
21 \lineiv{'h'}{signed short} {int} {2}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
22 \lineiv{'H'}{unsigned short}{int} {2}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
23 \lineiv{'i'}{signed int} {int} {2}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
24 \lineiv{'I'}{unsigned int} {long} {2}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
25 \lineiv{'l'}{signed long} {int} {4}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
26 \lineiv{'L'}{unsigned long} {long} {4}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
27 \lineiv{'f'}{float} {float} {4}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
28 \lineiv{'d'}{double} {float} {8}
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
29 \end{tableiv}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
30
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 The actual representation of values is determined by the machine
10647
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
32 architecture (strictly speaking, by the C implementation). The actual
9618
Fred Drake <fdrake@acm.org>
parents: 8918
diff changeset
33 size can be accessed through the \member{itemsize} attribute. The values
4877
e57a8de5aeb3 Added unsigned data formats (B, H, I, L).
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
34 stored for \code{'L'} and \code{'I'} items will be represented as
e57a8de5aeb3 Added unsigned data formats (B, H, I, L).
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
35 Python long integers when retrieved, because Python's plain integer
10647
c7470b14dec7 Added "See also" reference to xdrlib.
Fred Drake <fdrake@acm.org>
parents: 9618
diff changeset
36 type cannot represent the full range of C's unsigned (long) integers.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
37
2609
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
38
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
39 The module defines the following type:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
40
7712
0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain,
Fred Drake <fdrake@acm.org>
parents: 7505
diff changeset
41 \begin{funcdesc}{array}{typecode\optional{, initializer}}
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
42 Return a new array whose items are restricted by \var{typecode},
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
43 and initialized from the optional \var{initializer} value, which
33316
0b181bf230c9 SF feature request #992967: array.array objects should support sequences.
Raymond Hettinger <python@rcn.com>
parents: 31660
diff changeset
44 must be a list, string, or iterable over elements of the
0b181bf230c9 SF feature request #992967: array.array objects should support sequences.
Raymond Hettinger <python@rcn.com>
parents: 31660
diff changeset
45 appropriate type.
0b181bf230c9 SF feature request #992967: array.array objects should support sequences.
Raymond Hettinger <python@rcn.com>
parents: 31660
diff changeset
46 \versionchanged[Formerly, only lists or strings were accepted]{2.4}
0b181bf230c9 SF feature request #992967: array.array objects should support sequences.
Raymond Hettinger <python@rcn.com>
parents: 31660
diff changeset
47 If given a list or string, the initializer is passed to the
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
48 new array's \method{fromlist()}, \method{fromstring()}, or
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
49 \method{fromunicode()} method (see below) to add initial items to
33316
0b181bf230c9 SF feature request #992967: array.array objects should support sequences.
Raymond Hettinger <python@rcn.com>
parents: 31660
diff changeset
50 the array. Otherwise, the iterable initializer is passed to the
0b181bf230c9 SF feature request #992967: array.array objects should support sequences.
Raymond Hettinger <python@rcn.com>
parents: 31660
diff changeset
51 \method{extend()} method.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \end{funcdesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
53
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
54 \begin{datadesc}{ArrayType}
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
55 Obsolete alias for \function{array}.
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 \end{datadesc}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
57
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
58
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
59 Array objects support the ordinary sequence operations of
22759
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
60 indexing, slicing, concatenation, and multiplication. When using
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
61 slice assignment, the assigned value must be an array object with the
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
62 same type code; in all other cases, \exception{TypeError} is raised.
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
63 Array objects also implement the buffer interface, and may be used
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
64 wherever buffer objects are supported.
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
65
8719866014ab Fix up the documentation of the type codes to give both the C and Python
Fred Drake <fdrake@acm.org>
parents: 22098
diff changeset
66 The following data items and methods are also supported:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
67
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
68 \begin{memberdesc}[array]{typecode}
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
69 The typecode character used to create the array.
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
70 \end{memberdesc}
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
71
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
72 \begin{memberdesc}[array]{itemsize}
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
73 The length in bytes of one array item in the internal representation.
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
74 \end{memberdesc}
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
75
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
76
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
77 \begin{methoddesc}[array]{append}{x}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 Append a new item with value \var{x} to the end of the array.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
79 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
80
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
81 \begin{methoddesc}[array]{buffer_info}{}
6965
dce838cd42c1 Added missing "\" to "\var{address}, var{length}" in buffer_info() description.
Fred Drake <fdrake@acm.org>
parents: 6875
diff changeset
82 Return a tuple \code{(\var{address}, \var{length})} giving the current
18922
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
83 memory address and the length in elements of the buffer used to hold
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
84 array's contents. The size of the memory buffer in bytes can be
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
85 computed as \code{\var{array}.buffer_info()[1] *
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
86 \var{array}.itemsize}. This is occasionally useful when working with
6022
802470c7a50f Added buffer_info() docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
87 low-level (and inherently unsafe) I/O interfaces that require memory
18922
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
88 addresses, such as certain \cfunction{ioctl()} operations. The
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
89 returned numbers are valid as long as the array exists and no
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
90 length-changing operations are applied to it.
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
91
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 18922
diff changeset
92 \note{When using array objects from code written in C or
18922
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
93 \Cpp{} (the only way to effectively make use of this information), it
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
94 makes more sense to use the buffer interface supported by array
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
95 objects. This method is maintained for backward compatibility and
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
96 should be avoided in new code. The buffer interface is documented in
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 18922
diff changeset
97 the \citetitle[../api/newTypes.html]{Python/C API Reference Manual}.}
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
98 \end{methoddesc}
6022
802470c7a50f Added buffer_info() docs.
Guido van Rossum <guido@python.org>
parents: 5818
diff changeset
99
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11075
diff changeset
100 \begin{methoddesc}[array]{byteswap}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 ``Byteswap'' all items of the array. This is only supported for
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11075
diff changeset
102 values which are 1, 2, 4, or 8 bytes in size; for other types of
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11075
diff changeset
103 values, \exception{RuntimeError} is raised. It is useful when reading
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11075
diff changeset
104 data from a file written on a machine with a different byte order.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
105 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
106
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
107 \begin{methoddesc}[array]{count}{x}
33457
016d7016c6c6 Patch #1026384: fix two common typo's:
Johannes Gijsbers <jlg@dds.nl>
parents: 33316
diff changeset
108 Return the number of occurrences of \var{x} in the array.
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
109 \end{methoddesc}
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
110
31660
35f56e08727f SF feature request #686323: Minor array module enhancements
Raymond Hettinger <python@rcn.com>
parents: 29163
diff changeset
111 \begin{methoddesc}[array]{extend}{iterable}
35f56e08727f SF feature request #686323: Minor array module enhancements
Raymond Hettinger <python@rcn.com>
parents: 29163
diff changeset
112 Append items from \var{iterable} to the end of the array. If
35f56e08727f SF feature request #686323: Minor array module enhancements
Raymond Hettinger <python@rcn.com>
parents: 29163
diff changeset
113 \var{iterable} is another array, it must have \emph{exactly} the same
35f56e08727f SF feature request #686323: Minor array module enhancements
Raymond Hettinger <python@rcn.com>
parents: 29163
diff changeset
114 type code; if not, \exception{TypeError} will be raised. If
35f56e08727f SF feature request #686323: Minor array module enhancements
Raymond Hettinger <python@rcn.com>
parents: 29163
diff changeset
115 \var{iterable} is not an array, it must be iterable and its
35f56e08727f SF feature request #686323: Minor array module enhancements
Raymond Hettinger <python@rcn.com>
parents: 29163
diff changeset
116 elements must be the right type to be appended to the array.
35f56e08727f SF feature request #686323: Minor array module enhancements
Raymond Hettinger <python@rcn.com>
parents: 29163
diff changeset
117 \versionchanged[Formerly, the argument could only be another array]{2.4}
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
118 \end{methoddesc}
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
119
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
120 \begin{methoddesc}[array]{fromfile}{f, n}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 Read \var{n} items (as machine values) from the file object \var{f}
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 and append them to the end of the array. If less than \var{n} items
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
123 are available, \exception{EOFError} is raised, but the items that were
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
124 available are still inserted into the array. \var{f} must be a real
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
125 built-in file object; something else with a \method{read()} method won't
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
126 do.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
127 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
128
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
129 \begin{methoddesc}[array]{fromlist}{list}
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 1767
diff changeset
130 Append items from the list. This is equivalent to
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
131 \samp{for x in \var{list}:\ a.append(x)}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 except that if there is a type error, the array is unchanged.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
133 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
134
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
135 \begin{methoddesc}[array]{fromstring}{s}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 Appends items from the string, interpreting the string as an
18411
eeb2e77c5bad Fix up a few style nits -- avoid "e.g." and "i.e." -- these make
Fred Drake <fdrake@acm.org>
parents: 15505
diff changeset
137 array of machine values (as if it had been read from a
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
138 file using the \method{fromfile()} method).
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
139 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
140
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
141 \begin{methoddesc}[array]{fromunicode}{s}
37064
64c83e0f683e More \exception fixes.
Georg Brandl <georg@python.org>
parents: 33457
diff changeset
142 Extends this array with data from the given unicode string. The array
64c83e0f683e More \exception fixes.
Georg Brandl <georg@python.org>
parents: 33457
diff changeset
143 must be a type \code{'u'} array; otherwise a \exception{ValueError}
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
144 is raised. Use \samp{array.fromstring(ustr.decode(enc))} to
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
145 append Unicode data to an array of some other type.
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
146 \end{methoddesc}
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
147
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
148 \begin{methoddesc}[array]{index}{x}
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
149 Return the smallest \var{i} such that \var{i} is the index of
33457
016d7016c6c6 Patch #1026384: fix two common typo's:
Johannes Gijsbers <jlg@dds.nl>
parents: 33316
diff changeset
150 the first occurrence of \var{x} in the array.
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
151 \end{methoddesc}
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
152
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
153 \begin{methoddesc}[array]{insert}{i, x}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
154 Insert a new item with value \var{x} in the array before position
29163
2bb5ceef9ac3 Fix array.array.insert(), so that it treats negative indices as
Walter Dörwald <walter@livinglogic.de>
parents: 29062
diff changeset
155 \var{i}. Negative values are treated as being relative to the end
2bb5ceef9ac3 Fix array.array.insert(), so that it treats negative indices as
Walter Dörwald <walter@livinglogic.de>
parents: 29062
diff changeset
156 of the array.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
157 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
158
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
159 \begin{methoddesc}[array]{pop}{\optional{i}}
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
160 Removes the item with the index \var{i} from the array and returns
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
161 it. The optional argument defaults to \code{-1}, so that by default
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
162 the last item is removed and returned.
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
163 \end{methoddesc}
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
164
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
165 \begin{methoddesc}[array]{read}{f, n}
7505
ef980e17b593 Deprecate the read() and write() methods.
Fred Drake <fdrake@acm.org>
parents: 7501
diff changeset
166 \deprecated {1.5.1}
ef980e17b593 Deprecate the read() and write() methods.
Fred Drake <fdrake@acm.org>
parents: 7501
diff changeset
167 {Use the \method{fromfile()} method.}
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
168 Read \var{n} items (as machine values) from the file object \var{f}
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
169 and append them to the end of the array. If less than \var{n} items
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
170 are available, \exception{EOFError} is raised, but the items that were
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
171 available are still inserted into the array. \var{f} must be a real
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
172 built-in file object; something else with a \method{read()} method won't
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
173 do.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
174 \end{methoddesc}
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
175
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
176 \begin{methoddesc}[array]{remove}{x}
33457
016d7016c6c6 Patch #1026384: fix two common typo's:
Johannes Gijsbers <jlg@dds.nl>
parents: 33316
diff changeset
177 Remove the first occurrence of \var{x} from the array.
13772
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
178 \end{methoddesc}
eea51275acbf added count, extend, index, pop and remove to arraymodule
Peter Schneider-Kamp <nowonder@nowonder.de>
parents: 12223
diff changeset
179
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
180 \begin{methoddesc}[array]{reverse}{}
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
181 Reverse the order of the items in the array.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
182 \end{methoddesc}
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
183
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
184 \begin{methoddesc}[array]{tofile}{f}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
185 Write all items (as machine values) to the file object \var{f}.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
186 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
187
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
188 \begin{methoddesc}[array]{tolist}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
189 Convert the array to an ordinary list with the same items.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
190 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
191
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
192 \begin{methoddesc}[array]{tostring}{}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
193 Convert the array to an array of machine values and return the
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
194 string representation (the same sequence of bytes that would
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
195 be written to a file by the \method{tofile()} method.)
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
196 \end{methoddesc}
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
197
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
198 \begin{methoddesc}[array]{tounicode}{}
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
199 Convert the array to a unicode string. The array must be
37064
64c83e0f683e More \exception fixes.
Georg Brandl <georg@python.org>
parents: 33457
diff changeset
200 a type \code{'u'} array; otherwise a \exception{ValueError} is raised.
64c83e0f683e More \exception fixes.
Georg Brandl <georg@python.org>
parents: 33457
diff changeset
201 Use \samp{array.tostring().decode(enc)} to obtain a unicode string
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
202 from an array of some other type.
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
203 \end{methoddesc}
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
204
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
205 \begin{methoddesc}[array]{write}{f}
7505
ef980e17b593 Deprecate the read() and write() methods.
Fred Drake <fdrake@acm.org>
parents: 7501
diff changeset
206 \deprecated {1.5.1}
ef980e17b593 Deprecate the read() and write() methods.
Fred Drake <fdrake@acm.org>
parents: 7501
diff changeset
207 {Use the \method{tofile()} method.}
7501
d17db3ebfbc2 Updates by AMK.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
208 Write all items (as machine values) to the file object \var{f}.
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
209 \end{methoddesc}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
210
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
211 When an array object is printed or converted to a string, it is
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
212 represented as \code{array(\var{typecode}, \var{initializer})}. The
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
213 \var{initializer} is omitted if the array is empty, otherwise it is a
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
214 string if the \var{typecode} is \code{'c'}, otherwise it is a list of
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
215 numbers. The string is guaranteed to be able to be converted back to
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
216 an array with the same type and value using reverse quotes
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 11075
diff changeset
217 (\code{``}), so long as the \function{array()} function has been
18922
2f27838d8fc5 Fix description of buffer_info(), and add a note that there is a better
Fred Drake <fdrake@acm.org>
parents: 18411
diff changeset
218 imported using \code{from array import array}. Examples:
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
219
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 6965
diff changeset
220 \begin{verbatim}
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 array('l')
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 array('c', 'hello world')
22098
966725095854 Patch 520694: arraymodule.c improvements:
Martin v. Löwis <martin@v.loewis.de>
parents: 20580
diff changeset
223 array('u', u'hello \textbackslash u2641')
1471
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 array('l', [1, 2, 3, 4, 5])
2ec96140a36b Restructured library documentation
Guido van Rossum <guido@python.org>
parents:
diff changeset
225 array('d', [1.0, 2.0, 3.14])
7277
bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous
Fred Drake <fdrake@acm.org>
parents: 6965
diff changeset
226 \end{verbatim}
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
227
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
228
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
229 \begin{seealso}
15261
bc4f89eefb04 Make all the \seemodule explanations consistent: start with a capitalized
Fred Drake <fdrake@acm.org>
parents: 15256
diff changeset
230 \seemodule{struct}{Packing and unpacking of heterogeneous binary data.}
bc4f89eefb04 Make all the \seemodule explanations consistent: start with a capitalized
Fred Drake <fdrake@acm.org>
parents: 15256
diff changeset
231 \seemodule{xdrlib}{Packing and unpacking of External Data
bc4f89eefb04 Make all the \seemodule explanations consistent: start with a capitalized
Fred Drake <fdrake@acm.org>
parents: 15256
diff changeset
232 Representation (XDR) data as used in some remote
bc4f89eefb04 Make all the \seemodule explanations consistent: start with a capitalized
Fred Drake <fdrake@acm.org>
parents: 15256
diff changeset
233 procedure call systems.}
22796
ac5e1d9029b7 SF 539024, Fix broken link to numpy
Neal Norwitz <nnorwitz@gmail.com>
parents: 22759
diff changeset
234 \seetitle[http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm]{The
15256
bd4cd73cb0d6 Update the links to the NumPy website and documentation, based on a
Fred Drake <fdrake@acm.org>
parents: 13772
diff changeset
235 Numerical Python Manual}{The Numeric Python extension
bd4cd73cb0d6 Update the links to the NumPy website and documentation, based on a
Fred Drake <fdrake@acm.org>
parents: 13772
diff changeset
236 (NumPy) defines another array type; see
bd4cd73cb0d6 Update the links to the NumPy website and documentation, based on a
Fred Drake <fdrake@acm.org>
parents: 13772
diff changeset
237 \url{http://numpy.sourceforge.net/} for further information
15505
5e9d0127ace9 Added link to HTML version of the NumPy documentation.
Fred Drake <fdrake@acm.org>
parents: 15261
diff changeset
238 about Numerical Python. (A PDF version of the NumPy manual
5e9d0127ace9 Added link to HTML version of the NumPy documentation.
Fred Drake <fdrake@acm.org>
parents: 15261
diff changeset
239 is available at
29062
c019aa827f86 Fixed spacing and unbalanced brackets or parenthesis.
Raymond Hettinger <python@rcn.com>
parents: 22796
diff changeset
240 \url{http://numpy.sourceforge.net/numdoc/numdoc.pdf}).}
7804
6d04e8c817fb Use {seealso} environment to refer to the struct module.
Fred Drake <fdrake@acm.org>
parents: 7712
diff changeset
241 \end{seealso}