blob: 8490fc8e00d20c137a42bb8077ee9879fbaaea53 [file] [log] [blame]
Guido van Rossum470be141995-03-17 16:07:09 +00001\section{Built-in Module \sectcode{array}}
Guido van Rossume47da0a1997-07-17 16:34:52 +00002\label{module-array}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +00003\bimodindex{array}
4\index{arrays}
5
6This module defines a new object type which can efficiently represent
7an array of basic values: characters, integers, floating point
8numbers. Arrays are sequence types and behave very much like lists,
9except that the type of objects stored in them is constrained. The
10type is specified at object creation time by using a \dfn{type code},
11which is a single character. The following type codes are defined:
12
13\begin{tableiii}{|c|c|c|}{code}{Typecode}{Type}{Minimal size in bytes}
14\lineiii{'c'}{character}{1}
15\lineiii{'b'}{signed integer}{1}
Guido van Rossumb0b81811997-01-03 19:20:52 +000016\lineiii{'B'}{unsigned integer}{1}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000017\lineiii{'h'}{signed integer}{2}
Guido van Rossumb0b81811997-01-03 19:20:52 +000018\lineiii{'H'}{unsigned integer}{2}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000019\lineiii{'i'}{signed integer}{2}
Guido van Rossumb0b81811997-01-03 19:20:52 +000020\lineiii{'I'}{unsigned integer}{2}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000021\lineiii{'l'}{signed integer}{4}
Guido van Rossumb0b81811997-01-03 19:20:52 +000022\lineiii{'L'}{unsigned integer}{4}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000023\lineiii{'f'}{floating point}{4}
24\lineiii{'d'}{floating point}{8}
25\end{tableiii}
26
27The actual representation of values is determined by the machine
Guido van Rossum16d6e711994-08-08 12:30:22 +000028architecture (strictly speaking, by the C implementation). The actual
Guido van Rossumb0b81811997-01-03 19:20:52 +000029size can be accessed through the \var{itemsize} attribute. The values
30stored for \code{'L'} and \code{'I'} items will be represented as
31Python long integers when retrieved, because Python's plain integer
32type can't represent the full range of C's unsigned (long) integers.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000033
Guido van Rossumecde7811995-03-28 13:35:14 +000034See also built-in module \code{struct}.
Fred Drake4f496cc1997-12-16 04:08:24 +000035\refbimodindex{struct}
Guido van Rossumecde7811995-03-28 13:35:14 +000036
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000037The module defines the following function:
38
39\renewcommand{\indexsubitem}{(in module array)}
40
Guido van Rossum16d6e711994-08-08 12:30:22 +000041\begin{funcdesc}{array}{typecode\optional{\, initializer}}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000042Return a new array whose items are restricted by \var{typecode}, and
43initialized from the optional \var{initializer} value, which must be a
44list 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
46initial items to the array.
47\end{funcdesc}
48
49Array objects support the following data items and methods:
50
51\begin{datadesc}{typecode}
52The typecode character used to create the array.
53\end{datadesc}
54
55\begin{datadesc}{itemsize}
56The length in bytes of one array item in the internal representation.
57\end{datadesc}
58
59\begin{funcdesc}{append}{x}
60Append a new item with value \var{x} to the end of the array.
61\end{funcdesc}
62
Guido van Rossum8f062471997-08-14 19:50:37 +000063\begin{funcdesc}{buffer_info}{}
Fred Drakebef9b0b1997-12-29 19:33:45 +000064Return a tuple \code{(\var{address}, \var{length})} giving the current
Guido van Rossum8f062471997-08-14 19:50:37 +000065memory address and the length in bytes of the buffer used to hold
66array's contents. This is occasionally useful when working with
67low-level (and inherently unsafe) I/O interfaces that require memory
68addresses, such as certain \code{ioctl} operations. The returned
69numbers are valid as long as the array exists and no length-changing
70operations are applied to it.
71\end{funcdesc}
72
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000073\begin{funcdesc}{byteswap}{x}
74``Byteswap'' all items of the array. This is only supported for
Guido van Rossum16d6e711994-08-08 12:30:22 +000075integer values. It is useful when reading data from a file written
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000076on a machine with a different byte order.
77\end{funcdesc}
78
79\begin{funcdesc}{fromfile}{f\, n}
80Read \var{n} items (as machine values) from the file object \var{f}
81and append them to the end of the array. If less than \var{n} items
82are available, \code{EOFError} is raised, but the items that were
Guido van Rossum470be141995-03-17 16:07:09 +000083available are still inserted into the array. \var{f} must be a real
84built-in file object; something else with a \code{read()} method won't
85do.
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000086\end{funcdesc}
87
88\begin{funcdesc}{fromlist}{list}
Guido van Rossum6c4f0031995-03-07 10:14:09 +000089Append items from the list. This is equivalent to
90\code{for x in \var{list}:\ a.append(x)}
Guido van Rossum5fdeeea1994-01-02 01:22:07 +000091except that if there is a type error, the array is unchanged.
92\end{funcdesc}
93
94\begin{funcdesc}{fromstring}{s}
95Appends items from the string, interpreting the string as an
96array of machine values (i.e. as if it had been read from a
97file using the \code{fromfile()} method).
98\end{funcdesc}
99
100\begin{funcdesc}{insert}{i\, x}
101Insert a new item with value \var{x} in the array before position
102\var{i}.
103\end{funcdesc}
104
105\begin{funcdesc}{tofile}{f}
106Write all items (as machine values) to the file object \var{f}.
107\end{funcdesc}
108
109\begin{funcdesc}{tolist}{}
110Convert the array to an ordinary list with the same items.
111\end{funcdesc}
112
113\begin{funcdesc}{tostring}{}
114Convert the array to an array of machine values and return the
115string representation (the same sequence of bytes that would
116be written to a file by the \code{tofile()} method.)
117\end{funcdesc}
118
119When an array object is printed or converted to a string, it is
120represented as \code{array(\var{typecode}, \var{initializer})}. The
121\var{initializer} is omitted if the array is empty, otherwise it is a
122string if the \var{typecode} is \code{'c'}, otherwise it is a list of
123numbers. The string is guaranteed to be able to be converted back to
124an array with the same type and value using reverse quotes
125(\code{``}). Examples:
126
127\bcode\begin{verbatim}
128array('l')
129array('c', 'hello world')
130array('l', [1, 2, 3, 4, 5])
131array('d', [1.0, 2.0, 3.14])
132\end{verbatim}\ecode