Mercurial > cpython-lru_cache-weakref

comparison Doc/lib/libarray.tex @ 7501:d17db3ebfbc2 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updates by AMK. Markup corrected, logical markup.
author Fred Drake <fdrake@acm.org>
date Fri, 27 Feb 1998 15:19:42 +0000
parents bf4e790bd61a
children ef980e17b593
comparison
equal deleted inserted replaced
7500:9de3cad50905 7501:d17db3ebfbc2
8 numbers. Arrays are sequence types and behave very much like lists, 8 numbers. Arrays are sequence types and behave very much like lists,
9 except that the type of objects stored in them is constrained. The 9 except that the type of objects stored in them is constrained. The
10 type is specified at object creation time by using a \dfn{type code}, 10 type is specified at object creation time by using a \dfn{type code},
11 which is a single character. The following type codes are defined: 11 which is a single character. The following type codes are defined:
12 12
13 \begin{tableiii}{|c|c|c|}{code}{Typecode}{Type}{Minimal size in bytes} 13 \begin{tableiii}{|c|c|c|}{code}{Type code}{Type}{Minimum size in bytes}
14 \lineiii{'c'}{character}{1} 14 \lineiii{'c'}{character}{1}
15 \lineiii{'b'}{signed integer}{1} 15 \lineiii{'b'}{signed integer}{1}
16 \lineiii{'B'}{unsigned integer}{1} 16 \lineiii{'B'}{unsigned integer}{1}
17 \lineiii{'h'}{signed integer}{2} 17 \lineiii{'h'}{signed integer}{2}
18 \lineiii{'H'}{unsigned integer}{2} 18 \lineiii{'H'}{unsigned integer}{2}
23 \lineiii{'f'}{floating point}{4} 23 \lineiii{'f'}{floating point}{4}
24 \lineiii{'d'}{floating point}{8} 24 \lineiii{'d'}{floating point}{8}
25 \end{tableiii} 25 \end{tableiii}
26 26
27 The actual representation of values is determined by the machine 27 The actual representation of values is determined by the machine
28 architecture (strictly speaking, by the C implementation). The actual 28 architecture (strictly speaking, by the \C{} implementation). The actual
29 size can be accessed through the \var{itemsize} attribute. The values 29 size can be accessed through the \var{itemsize} attribute. The values
30 stored for \code{'L'} and \code{'I'} items will be represented as 30 stored for \code{'L'} and \code{'I'} items will be represented as
31 Python long integers when retrieved, because Python's plain integer 31 Python long integers when retrieved, because Python's plain integer
32 type can't represent the full range of C's unsigned (long) integers. 32 type can't represent the full range of \C{}'s unsigned (long) integers.
33 33
34 See also built-in module \code{struct}. 34 See also built-in module \module{struct}\refbimodindex{struct}.
35 \refbimodindex{struct}
36 35
37 The module defines the following function: 36 The module defines the following function:
38
39 \setindexsubitem{(in module array)}
40 37
41 \begin{funcdesc}{array}{typecode\optional{\, initializer}} 38 \begin{funcdesc}{array}{typecode\optional{\, initializer}}
42 Return a new array whose items are restricted by \var{typecode}, and 39 Return a new array whose items are restricted by \var{typecode}, and
43 initialized from the optional \var{initializer} value, which must be a 40 initialized from the optional \var{initializer} value, which must be a
44 list or a string. The list or string is passed to the new array's 41 list or a string. The list or string is passed to the new array's
45 \code{fromlist()} or \code{fromstring()} method (see below) to add 42 \method{fromlist()} or \method{fromstring()} method (see below) to add
46 initial items to the array. 43 initial items to the array.
47 \end{funcdesc} 44 \end{funcdesc}
48 45
49 Array objects support the following data items and methods: 46 Array objects support the following data items and methods:
47
48 \setindexsubitem{(array attribute)}
50 49
51 \begin{datadesc}{typecode} 50 \begin{datadesc}{typecode}
52 The typecode character used to create the array. 51 The typecode character used to create the array.
53 \end{datadesc} 52 \end{datadesc}
54 53
55 \begin{datadesc}{itemsize} 54 \begin{datadesc}{itemsize}
56 The length in bytes of one array item in the internal representation. 55 The length in bytes of one array item in the internal representation.
57 \end{datadesc} 56 \end{datadesc}
57
58 \setindexsubitem{(array method)}
58 59
59 \begin{funcdesc}{append}{x} 60 \begin{funcdesc}{append}{x}
60 Append a new item with value \var{x} to the end of the array. 61 Append a new item with value \var{x} to the end of the array.
61 \end{funcdesc} 62 \end{funcdesc}
62 63
63 \begin{funcdesc}{buffer_info}{} 64 \begin{funcdesc}{buffer_info}{}
64 Return a tuple \code{(\var{address}, \var{length})} giving the current 65 Return a tuple \code{(\var{address}, \var{length})} giving the current
65 memory address and the length in bytes of the buffer used to hold 66 memory address and the length in bytes of the buffer used to hold
66 array's contents. This is occasionally useful when working with 67 array's contents. This is occasionally useful when working with
67 low-level (and inherently unsafe) I/O interfaces that require memory 68 low-level (and inherently unsafe) I/O interfaces that require memory
68 addresses, such as certain \code{ioctl} operations. The returned 69 addresses, such as certain \cfunction{ioctl()} operations. The returned
69 numbers are valid as long as the array exists and no length-changing 70 numbers are valid as long as the array exists and no length-changing
70 operations are applied to it. 71 operations are applied to it.
71 \end{funcdesc} 72 \end{funcdesc}
72 73
73 \begin{funcdesc}{byteswap}{x} 74 \begin{funcdesc}{byteswap}{x}
77 \end{funcdesc} 78 \end{funcdesc}
78 79
79 \begin{funcdesc}{fromfile}{f\, n} 80 \begin{funcdesc}{fromfile}{f\, n}
80 Read \var{n} items (as machine values) from the file object \var{f} 81 Read \var{n} items (as machine values) from the file object \var{f}
81 and append them to the end of the array. If less than \var{n} items 82 and append them to the end of the array. If less than \var{n} items
82 are available, \code{EOFError} is raised, but the items that were 83 are available, \exception{EOFError} is raised, but the items that were
83 available are still inserted into the array. \var{f} must be a real 84 available are still inserted into the array. \var{f} must be a real
84 built-in file object; something else with a \code{read()} method won't 85 built-in file object; something else with a \code{read()} method won't
85 do. 86 do.
87
88 Also available as the \method{read()} method.
86 \end{funcdesc} 89 \end{funcdesc}
87 90
88 \begin{funcdesc}{fromlist}{list} 91 \begin{funcdesc}{fromlist}{list}
89 Append items from the list. This is equivalent to 92 Append items from the list. This is equivalent to
90 \code{for x in \var{list}:\ a.append(x)} 93 \samp{for x in \var{list}:\ a.append(x)}
91 except that if there is a type error, the array is unchanged. 94 except that if there is a type error, the array is unchanged.
92 \end{funcdesc} 95 \end{funcdesc}
93 96
94 \begin{funcdesc}{fromstring}{s} 97 \begin{funcdesc}{fromstring}{s}
95 Appends items from the string, interpreting the string as an 98 Appends items from the string, interpreting the string as an
96 array of machine values (i.e. as if it had been read from a 99 array of machine values (i.e. as if it had been read from a
97 file using the \code{fromfile()} method). 100 file using the \method{fromfile()} method).
98 \end{funcdesc} 101 \end{funcdesc}
99 102
100 \begin{funcdesc}{insert}{i\, x} 103 \begin{funcdesc}{insert}{i\, x}
101 Insert a new item with value \var{x} in the array before position 104 Insert a new item with value \var{x} in the array before position
102 \var{i}. 105 \var{i}.
103 \end{funcdesc} 106 \end{funcdesc}
104 107
108 \begin{funcdesc}{read}{f\, n}
109 Read \var{n} items (as machine values) from the file object \var{f}
110 and append them to the end of the array. If less than \var{n} items
111 are available, \exception{EOFError} is raised, but the items that were
112 available are still inserted into the array. \var{f} must be a real
113 built-in file object; something else with a \method{read()} method won't
114 do.
115
116 Also available as the \method{fromfile()} method.
117 \end{funcdesc}
118
119 \begin{funcdesc}{reverse}{}
120 Reverse the order of the items in the array.
121 \end{funcdesc}
122
105 \begin{funcdesc}{tofile}{f} 123 \begin{funcdesc}{tofile}{f}
106 Write all items (as machine values) to the file object \var{f}. 124 Write all items (as machine values) to the file object \var{f}.
125
126 Also available as the \function{write()} function.
107 \end{funcdesc} 127 \end{funcdesc}
108 128
109 \begin{funcdesc}{tolist}{} 129 \begin{funcdesc}{tolist}{}
110 Convert the array to an ordinary list with the same items. 130 Convert the array to an ordinary list with the same items.
111 \end{funcdesc} 131 \end{funcdesc}
112 132
113 \begin{funcdesc}{tostring}{} 133 \begin{funcdesc}{tostring}{}
114 Convert the array to an array of machine values and return the 134 Convert the array to an array of machine values and return the
115 string representation (the same sequence of bytes that would 135 string representation (the same sequence of bytes that would
116 be written to a file by the \code{tofile()} method.) 136 be written to a file by the \method{tofile()} method.)
137 \end{funcdesc}
138
139 \begin{funcdesc}{write}{f}
140 Write all items (as machine values) to the file object \var{f}.
141
142 Also available as the \function{write()} function.
117 \end{funcdesc} 143 \end{funcdesc}
118 144
119 When an array object is printed or converted to a string, it is 145 When an array object is printed or converted to a string, it is
120 represented as \code{array(\var{typecode}, \var{initializer})}. The 146 represented as \code{array(\var{typecode}, \var{initializer})}. The
121 \var{initializer} is omitted if the array is empty, otherwise it is a 147 \var{initializer} is omitted if the array is empty, otherwise it is a