Restructured library documentation

Doc/lib/libarray.tex

@@ -0,0 +1,109 @@
+\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{'h'}{signed integer}{2}
+\lineiii{'i'}{signed integer}{2}
+\lineiii{'l'}{signed 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 spoken, by the C implementation).  The actual
+size can be accessed through the \var{typecode} attribute.
+
+The module defines the following function:
+
+\renewcommand{\indexsubitem}{(in module array)}
+
+\begin{funcdesc}{array}{typecode\, 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 ffrom 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.
+\end{funcdesc}
+
+\begin{funcdesc}{fromlist}{list}
+Appends 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