Doc/libarray.tex

   1 \section{Built-in module \sectcode{array}}
   2 \bimodindex{array}
   3 \index{arrays}
   4
   5 This module defines a new object type which can efficiently represent
   6 an array of basic values: characters, integers, floating point
   7 numbers.  Arrays are sequence types and behave very much like lists,
   8 except that the type of objects stored in them is constrained.  The
   9 type is specified at object creation time by using a \dfn{type code},
  10 which is a single character.  The following type codes are defined:
  11
  12 \begin{tableiii}{|c|c|c|}{code}{Typecode}{Type}{Minimal size in bytes}
  13 \lineiii{'c'}{character}{1}
  14 \lineiii{'b'}{signed integer}{1}
  15 \lineiii{'h'}{signed integer}{2}
  16 \lineiii{'i'}{signed integer}{2}
  17 \lineiii{'l'}{signed integer}{4}
  18 \lineiii{'f'}{floating point}{4}
  19 \lineiii{'d'}{floating point}{8}
  20 \end{tableiii}
  21
  22 The actual representation of values is determined by the machine
  23 architecture (strictly speaking, by the C implementation).  The actual
  24 size can be accessed through the \var{typecode} attribute.
  25
  26 The module defines the following function:
  27
  28 \renewcommand{\indexsubitem}{(in module array)}
  29
  30 \begin{funcdesc}{array}{typecode\optional{\, initializer}}
  31 Return a new array whose items are restricted by \var{typecode}, and
  32 initialized from the optional \var{initializer} value, which must be a
  33 list or a string.  The list or string is passed to the new array's
  34 \code{fromlist()} or \code{fromstring()} method (see below) to add
  35 initial items to the array.
  36 \end{funcdesc}
  37
  38 Array objects support the following data items and methods:
  39
  40 \begin{datadesc}{typecode}
  41 The typecode character used to create the array.
  42 \end{datadesc}
  43
  44 \begin{datadesc}{itemsize}
  45 The length in bytes of one array item in the internal representation.
  46 \end{datadesc}
  47
  48 \begin{funcdesc}{append}{x}
  49 Append a new item with value \var{x} to the end of the array.
  50 \end{funcdesc}
  51
  52 \begin{funcdesc}{byteswap}{x}
  53 ``Byteswap'' all items of the array.  This is only supported for
  54 integer values.  It is useful when reading data from a file written
  55 on a machine with a different byte order.
  56 \end{funcdesc}
  57
  58 \begin{funcdesc}{fromfile}{f\, n}
  59 Read \var{n} items (as machine values) from the file object \var{f}
  60 and append them to the end of the array.  If less than \var{n} items
  61 are available, \code{EOFError} is raised, but the items that were
  62 available are still inserted into the array.
  63 \end{funcdesc}
  64
  65 \begin{funcdesc}{fromlist}{list}
  66 Appends items from the list.  This is equivalent to
  67 \code{for x in \var{list}: a.append(x)}
  68 except that if there is a type error, the array is unchanged.
  69 \end{funcdesc}
  70
  71 \begin{funcdesc}{fromstring}{s}
  72 Appends items from the string, interpreting the string as an
  73 array of machine values (i.e. as if it had been read from a
  74 file using the \code{fromfile()} method).
  75 \end{funcdesc}
  76
  77 \begin{funcdesc}{insert}{i\, x}
  78 Insert a new item with value \var{x} in the array before position
  79 \var{i}.
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{tofile}{f}
  83 Write all items (as machine values) to the file object \var{f}.
  84 \end{funcdesc}
  85
  86 \begin{funcdesc}{tolist}{}
  87 Convert the array to an ordinary list with the same items.
  88 \end{funcdesc}
  89
  90 \begin{funcdesc}{tostring}{}
  91 Convert the array to an array of machine values and return the
  92 string representation (the same sequence of bytes that would
  93 be written to a file by the \code{tofile()} method.)
  94 \end{funcdesc}
  95
  96 When an array object is printed or converted to a string, it is
  97 represented as \code{array(\var{typecode}, \var{initializer})}.  The
  98 \var{initializer} is omitted if the array is empty, otherwise it is a
  99 string if the \var{typecode} is \code{'c'}, otherwise it is a list of
 100 numbers.  The string is guaranteed to be able to be converted back to
 101 an array with the same type and value using reverse quotes
 102 (\code{``}).  Examples:
 103
 104 \bcode\begin{verbatim}
 105 array('l')
 106 array('c', 'hello world')
 107 array('l', [1, 2, 3, 4, 5])
 108 array('d', [1.0, 2.0, 3.14])
 109 \end{verbatim}\ecode