| \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 speaking, 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\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. |
| \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 |