diff options
Diffstat (limited to 'Doc/lib/libarray.tex')
| -rw-r--r-- | Doc/lib/libarray.tex | 241 |
1 files changed, 0 insertions, 241 deletions
diff --git a/Doc/lib/libarray.tex b/Doc/lib/libarray.tex deleted file mode 100644 index eaf5888..0000000 --- a/Doc/lib/libarray.tex +++ /dev/null @@ -1,241 +0,0 @@ -\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 \code{'u'} array; otherwise a \exception{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 \code{'u'} array; otherwise a \exception{ValueError} is raised. -Use \samp{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} |