mirror of
https://github.com/python/cpython.git
synced 2024-11-30 13:24:13 +08:00
122 lines
4.3 KiB
TeX
122 lines
4.3 KiB
TeX
\section{Built-in Module \sectcode{array}}
|
|
\bimodindex{array}
|
|
\index{arrays}
|
|
|
|
This module defines a new object type which can efficiently represent
|
|
an array of basic values: characters, integers, floating point
|
|
numbers. Arrays are sequence types and behave very much like lists,
|
|
except that the type of objects stored in them is constrained. The
|
|
type is specified at object creation time by using a \dfn{type code},
|
|
which is a single character. The following type codes are defined:
|
|
|
|
\begin{tableiii}{|c|c|c|}{code}{Typecode}{Type}{Minimal size in bytes}
|
|
\lineiii{'c'}{character}{1}
|
|
\lineiii{'b'}{signed integer}{1}
|
|
\lineiii{'B'}{unsigned integer}{1}
|
|
\lineiii{'h'}{signed integer}{2}
|
|
\lineiii{'H'}{unsigned integer}{2}
|
|
\lineiii{'i'}{signed integer}{2}
|
|
\lineiii{'I'}{unsigned integer}{2}
|
|
\lineiii{'l'}{signed integer}{4}
|
|
\lineiii{'L'}{unsigned integer}{4}
|
|
\lineiii{'f'}{floating point}{4}
|
|
\lineiii{'d'}{floating point}{8}
|
|
\end{tableiii}
|
|
|
|
The actual representation of values is determined by the machine
|
|
architecture (strictly speaking, by the C implementation). The actual
|
|
size can be accessed through the \var{itemsize} attribute. The values
|
|
stored for \code{'L'} and \code{'I'} items will be represented as
|
|
Python long integers when retrieved, because Python's plain integer
|
|
type can't represent the full range of C's unsigned (long) integers.
|
|
|
|
See also built-in module \code{struct}.
|
|
\bimodindex{struct}
|
|
|
|
The module defines the following function:
|
|
|
|
\renewcommand{\indexsubitem}{(in module array)}
|
|
|
|
\begin{funcdesc}{array}{typecode\optional{\, initializer}}
|
|
Return a new array whose items are restricted by \var{typecode}, and
|
|
initialized from the optional \var{initializer} value, which must be a
|
|
list or a string. The list or string is passed to the new array's
|
|
\code{fromlist()} or \code{fromstring()} method (see below) to add
|
|
initial items to the array.
|
|
\end{funcdesc}
|
|
|
|
Array objects support the following data items and methods:
|
|
|
|
\begin{datadesc}{typecode}
|
|
The typecode character used to create the array.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{itemsize}
|
|
The length in bytes of one array item in the internal representation.
|
|
\end{datadesc}
|
|
|
|
\begin{funcdesc}{append}{x}
|
|
Append a new item with value \var{x} to the end of the array.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{byteswap}{x}
|
|
``Byteswap'' all items of the array. This is only supported for
|
|
integer values. It is useful when reading data from a file written
|
|
on a machine with a different byte order.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fromfile}{f\, n}
|
|
Read \var{n} items (as machine values) from the file object \var{f}
|
|
and append them to the end of the array. If less than \var{n} items
|
|
are available, \code{EOFError} is raised, but the items that were
|
|
available are still inserted into the array. \var{f} must be a real
|
|
built-in file object; something else with a \code{read()} method won't
|
|
do.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fromlist}{list}
|
|
Append items from the list. This is equivalent to
|
|
\code{for x in \var{list}:\ a.append(x)}
|
|
except that if there is a type error, the array is unchanged.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{fromstring}{s}
|
|
Appends items from the string, interpreting the string as an
|
|
array of machine values (i.e. as if it had been read from a
|
|
file using the \code{fromfile()} method).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{insert}{i\, x}
|
|
Insert a new item with value \var{x} in the array before position
|
|
\var{i}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tofile}{f}
|
|
Write all items (as machine values) to the file object \var{f}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tolist}{}
|
|
Convert the array to an ordinary list with the same items.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tostring}{}
|
|
Convert the array to an array of machine values and return the
|
|
string representation (the same sequence of bytes that would
|
|
be written to a file by the \code{tofile()} method.)
|
|
\end{funcdesc}
|
|
|
|
When an array object is printed or converted to a string, it is
|
|
represented as \code{array(\var{typecode}, \var{initializer})}. The
|
|
\var{initializer} is omitted if the array is empty, otherwise it is a
|
|
string if the \var{typecode} is \code{'c'}, otherwise it is a list of
|
|
numbers. The string is guaranteed to be able to be converted back to
|
|
an array with the same type and value using reverse quotes
|
|
(\code{``}). Examples:
|
|
|
|
\bcode\begin{verbatim}
|
|
array('l')
|
|
array('c', 'hello world')
|
|
array('l', [1, 2, 3, 4, 5])
|
|
array('d', [1.0, 2.0, 3.14])
|
|
\end{verbatim}\ecode
|