mirror of https://github.com/python/cpython
242 lines
9.7 KiB
TeX
242 lines
9.7 KiB
TeX
\section{\module{array} ---
|
|
Efficient arrays of numeric values}
|
|
|
|
\declaremodule{builtin}{array}
|
|
\modulesynopsis{Efficient arrays of uniformly typed numeric values.}
|
|
|
|
|
|
This module defines an 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:
|
|
|
|
\begin{tableiv}{c|l|l|c}{code}{Type code}{C Type}{Python Type}{Minimum size in bytes}
|
|
\lineiv{'c'}{char} {character} {1}
|
|
\lineiv{'b'}{signed char} {int} {1}
|
|
\lineiv{'B'}{unsigned char} {int} {1}
|
|
\lineiv{'u'}{Py_UNICODE} {Unicode character}{2}
|
|
\lineiv{'h'}{signed short} {int} {2}
|
|
\lineiv{'H'}{unsigned short}{int} {2}
|
|
\lineiv{'i'}{signed int} {int} {2}
|
|
\lineiv{'I'}{unsigned int} {long} {2}
|
|
\lineiv{'l'}{signed long} {int} {4}
|
|
\lineiv{'L'}{unsigned long} {long} {4}
|
|
\lineiv{'f'}{float} {float} {4}
|
|
\lineiv{'d'}{double} {float} {8}
|
|
\end{tableiv}
|
|
|
|
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 \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.
|
|
|
|
|
|
The module defines the following type:
|
|
|
|
\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, string, or iterable over elements of the
|
|
appropriate type.
|
|
\versionchanged[Formerly, only lists or strings were accepted]{2.4}
|
|
If given a list or string, the initializer is passed to the
|
|
new array's \method{fromlist()}, \method{fromstring()}, or
|
|
\method{fromunicode()} method (see below) to add initial items to
|
|
the array. Otherwise, the iterable initializer is passed to the
|
|
\method{extend()} method.
|
|
\end{funcdesc}
|
|
|
|
\begin{datadesc}{ArrayType}
|
|
Obsolete alias for \function{array}.
|
|
\end{datadesc}
|
|
|
|
|
|
Array objects support the ordinary sequence operations of
|
|
indexing, slicing, concatenation, and multiplication. When using
|
|
slice assignment, the assigned value must be an array object with the
|
|
same type code; in all other cases, \exception{TypeError} is raised.
|
|
Array objects also implement the buffer interface, and may be used
|
|
wherever buffer objects are supported.
|
|
|
|
The following data items and methods are also supported:
|
|
|
|
\begin{memberdesc}[array]{typecode}
|
|
The typecode character used to create the array.
|
|
\end{memberdesc}
|
|
|
|
\begin{memberdesc}[array]{itemsize}
|
|
The length in bytes of one array item in the internal representation.
|
|
\end{memberdesc}
|
|
|
|
|
|
\begin{methoddesc}[array]{append}{x}
|
|
Append a new item with value \var{x} to the end of the array.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{buffer_info}{}
|
|
Return a tuple \code{(\var{address}, \var{length})} giving the current
|
|
memory address and the length in elements of the buffer used to hold
|
|
array's contents. The size of the memory buffer in bytes can be
|
|
computed as \code{\var{array}.buffer_info()[1] *
|
|
\var{array}.itemsize}. 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 numbers are valid as long as the array exists and no
|
|
length-changing operations are applied to it.
|
|
|
|
\note{When using array objects from code written in C or
|
|
\Cpp{} (the only way to effectively make use of this information), it
|
|
makes more sense to use the buffer interface supported by array
|
|
objects. This method is maintained for backward compatibility and
|
|
should be avoided in new code. The buffer interface is documented in
|
|
the \citetitle[../api/newTypes.html]{Python/C API Reference Manual}.}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{byteswap}{}
|
|
``Byteswap'' all items of the array. This is only supported for
|
|
values which are 1, 2, 4, or 8 bytes in size; 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}
|
|
|
|
\begin{methoddesc}[array]{count}{x}
|
|
Return the number of occurrences of \var{x} in the array.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{extend}{iterable}
|
|
Append items from \var{iterable} to the end of the array. If
|
|
\var{iterable} is another array, it must have \emph{exactly} the same
|
|
type code; if not, \exception{TypeError} will be raised. If
|
|
\var{iterable} is not an array, it must be iterable and its
|
|
elements must be the right type to be appended to the array.
|
|
\versionchanged[Formerly, the argument could only be another array]{2.4}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{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, \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]{fromlist}{list}
|
|
Append items from the list. This is equivalent to
|
|
\samp{for x in \var{list}:\ a.append(x)}
|
|
except that if there is a type error, the array is unchanged.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{fromstring}{s}
|
|
Appends items from the string, interpreting the string as an
|
|
array of machine values (as if it had been read from a
|
|
file using the \method{fromfile()} method).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{fromunicode}{s}
|
|
Extends this array with data from the given unicode string.
|
|
The array must be a type 'u' array; otherwise a ValueError
|
|
is raised. Use \samp{array.fromstring(ustr.decode(enc))} to
|
|
append Unicode data to an array of some other type.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{index}{x}
|
|
Return the smallest \var{i} such that \var{i} is the index of
|
|
the first occurrence of \var{x} in the array.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{insert}{i, x}
|
|
Insert a new item with value \var{x} in the array before position
|
|
\var{i}. Negative values are treated as being relative to the end
|
|
of the array.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{pop}{\optional{i}}
|
|
Removes the item with the index \var{i} from the array and returns
|
|
it. The optional argument defaults to \code{-1}, so that by default
|
|
the last item is removed and returned.
|
|
\end{methoddesc}
|
|
|
|
\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]{remove}{x}
|
|
Remove the first occurrence of \var{x} from the array.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{reverse}{}
|
|
Reverse the order of the items in the array.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{tofile}{f}
|
|
Write all items (as machine values) to the file object \var{f}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{tolist}{}
|
|
Convert the array to an ordinary list with the same items.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{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 \method{tofile()} method.)
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[array]{tounicode}{}
|
|
Convert the array to a unicode string. The array must be
|
|
a type 'u' array; otherwise a ValueError is raised. Use
|
|
array.tostring().decode(enc) to obtain a unicode string
|
|
from an array of some other type.
|
|
\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}
|
|
|
|
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{``}), so long as the \function{array()} function has been
|
|
imported using \code{from array import array}. Examples:
|
|
|
|
\begin{verbatim}
|
|
array('l')
|
|
array('c', 'hello world')
|
|
array('u', u'hello \textbackslash u2641')
|
|
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.}
|
|
\seemodule{xdrlib}{Packing and unpacking of External Data
|
|
Representation (XDR) data as used in some remote
|
|
procedure call systems.}
|
|
\seetitle[http://numpy.sourceforge.net/numdoc/HTML/numdoc.htm]{The
|
|
Numerical Python Manual}{The Numeric Python extension
|
|
(NumPy) defines another array type; see
|
|
\url{http://numpy.sourceforge.net/} for further information
|
|
about Numerical Python. (A PDF version of the NumPy manual
|
|
is available at
|
|
\url{http://numpy.sourceforge.net/numdoc/numdoc.pdf}).}
|
|
\end{seealso}
|