cpython/Doc/lib/libarray.tex

167 lines
6.0 KiB
TeX
Raw Normal View History

\section{\module{array} ---
Efficient arrays of numeric values}
\declaremodule{builtin}{array}
\modulesynopsis{Efficient arrays of uniformly typed numeric values.}
1994-01-01 21:22:07 -04:00
This module defines a new object type which can efficiently represent
an array of basic values: characters, integers, floating point
numbers. Arrays\index{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:
1994-01-01 21:22:07 -04:00
1998-04-11 17:53:03 -03:00
\begin{tableiii}{c|l|c}{code}{Type code}{C Type}{Minimum size in bytes}
1994-01-01 21:22:07 -04:00
\lineiii{'c'}{character}{1}
1998-12-10 01:04:21 -04:00
\lineiii{'b'}{signed int}{1}
\lineiii{'B'}{unsigned int}{1}
\lineiii{'h'}{signed int}{2}
\lineiii{'H'}{unsigned int}{2}
\lineiii{'i'}{signed int}{2}
\lineiii{'I'}{unsigned int}{2}
\lineiii{'l'}{signed int}{4}
\lineiii{'L'}{unsigned int}{4}
\lineiii{'f'}{float}{4}
\lineiii{'d'}{double}{8}
1994-01-01 21:22:07 -04:00
\end{tableiii}
The actual representation of values is determined by the machine
architecture (strictly speaking, by the C implementation). The actual
1998-12-10 01:04:21 -04:00
size can be accessed through the \member{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 cannot represent the full range of C's unsigned (long) integers.
1994-01-01 21:22:07 -04:00
The module defines the following function and type object:
1994-01-01 21:22:07 -04:00
\begin{funcdesc}{array}{typecode\optional{, initializer}}
1994-01-01 21:22:07 -04:00
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
\method{fromlist()} or \method{fromstring()} method (see below) to add
1994-01-01 21:22:07 -04:00
initial items to the array.
\end{funcdesc}
\begin{datadesc}{ArrayType}
Type object corresponding to the objects returned by
\function{array()}.
\end{datadesc}
1994-01-01 21:22:07 -04:00
Array objects support the following data items and methods:
\begin{memberdesc}[array]{typecode}
1994-01-01 21:22:07 -04:00
The typecode character used to create the array.
\end{memberdesc}
1994-01-01 21:22:07 -04:00
\begin{memberdesc}[array]{itemsize}
1994-01-01 21:22:07 -04:00
The length in bytes of one array item in the internal representation.
\end{memberdesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{append}{x}
1994-01-01 21:22:07 -04:00
Append a new item with value \var{x} to the end of the array.
\end{methoddesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{buffer_info}{}
Return a tuple \code{(\var{address}, \var{length})} giving the current
1997-08-14 16:50:37 -03:00
memory address and the length in bytes of the buffer used to hold
array's contents. This is occasionally useful when working with
low-level (and inherently unsafe) I/O interfaces that require memory
addresses, such as certain \cfunction{ioctl()} operations. The returned
1997-08-14 16:50:37 -03:00
numbers are valid as long as the array exists and no length-changing
operations are applied to it.
\end{methoddesc}
1997-08-14 16:50:37 -03:00
\begin{methoddesc}[array]{byteswap}{x}
1994-01-01 21:22:07 -04:00
``Byteswap'' all items of the array. This is only supported for
integer values; for other types of values, \exception{RuntimeError} is
raised. It is useful when reading data from a file written on a
machine with a different byte order.
\end{methoddesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{fromfile}{f, n}
1994-01-01 21:22:07 -04:00
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, \exception{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 \method{read()} method won't
do.
\end{methoddesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{fromlist}{list}
1995-03-07 06:14:09 -04:00
Append items from the list. This is equivalent to
\samp{for x in \var{list}:\ a.append(x)}
1994-01-01 21:22:07 -04:00
except that if there is a type error, the array is unchanged.
\end{methoddesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{fromstring}{s}
1994-01-01 21:22:07 -04:00
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 \method{fromfile()} method).
\end{methoddesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{insert}{i, x}
1994-01-01 21:22:07 -04:00
Insert a new item with value \var{x} in the array before position
\var{i}.
\end{methoddesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{read}{f, n}
\deprecated {1.5.1}
{Use the \method{fromfile()} method.}
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, \exception{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 \method{read()} method won't
do.
\end{methoddesc}
\begin{methoddesc}[array]{reverse}{}
Reverse the order of the items in the array.
\end{methoddesc}
\begin{methoddesc}[array]{tofile}{f}
1994-01-01 21:22:07 -04:00
Write all items (as machine values) to the file object \var{f}.
\end{methoddesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{tolist}{}
1994-01-01 21:22:07 -04:00
Convert the array to an ordinary list with the same items.
\end{methoddesc}
1994-01-01 21:22:07 -04:00
\begin{methoddesc}[array]{tostring}{}
1994-01-01 21:22:07 -04:00
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 \method{tofile()} method.)
\end{methoddesc}
\begin{methoddesc}[array]{write}{f}
\deprecated {1.5.1}
{Use the \method{tofile()} method.}
Write all items (as machine values) to the file object \var{f}.
\end{methoddesc}
1994-01-01 21:22:07 -04:00
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:
\begin{verbatim}
1994-01-01 21:22:07 -04:00
array('l')
array('c', 'hello world')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])
\end{verbatim}
\begin{seealso}
\seemodule{struct}{packing and unpacking of heterogeneous binary data}
1999-04-21 18:33:24 -03:00
\seemodule{xdrlib}{packing and unpacking of XDR data}
\end{seealso}