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{itemsize} attribute.
  25
  26 See also built-in module \code{struct}.
  27 \bimodindex{struct}
  28
  29 The module defines the following function:
  30
  31 \renewcommand{\indexsubitem}{(in module array)}
  32
  33 \begin{funcdesc}{array}{typecode\optional{\, initializer}}
  34 Return a new array whose items are restricted by \var{typecode}, and
  35 initialized from the optional \var{initializer} value, which must be a
  36 list or a string.  The list or string is passed to the new array's
  37 \code{fromlist()} or \code{fromstring()} method (see below) to add
  38 initial items to the array.
  39 \end{funcdesc}
  40
  41 Array objects support the following data items and methods:
  42
  43 \begin{datadesc}{typecode}
  44 The typecode character used to create the array.
  45 \end{datadesc}
  46
  47 \begin{datadesc}{itemsize}
  48 The length in bytes of one array item in the internal representation.
  49 \end{datadesc}
  50
  51 \begin{funcdesc}{append}{x}
  52 Append a new item with value \var{x} to the end of the array.
  53 \end{funcdesc}
  54
  55 \begin{funcdesc}{byteswap}{x}
  56 ``Byteswap'' all items of the array.  This is only supported for
  57 integer values.  It is useful when reading data from a file written
  58 on a machine with a different byte order.
  59 \end{funcdesc}
  60
  61 \begin{funcdesc}{fromfile}{f\, n}
  62 Read \var{n} items (as machine values) from the file object \var{f}
  63 and append them to the end of the array.  If less than \var{n} items
  64 are available, \code{EOFError} is raised, but the items that were
  65 available are still inserted into the array.  \var{f} must be a real
  66 built-in file object; something else with a \code{read()} method won't
  67 do.
  68 \end{funcdesc}
  69
  70 \begin{funcdesc}{fromlist}{list}
  71 Append items from the list.  This is equivalent to
  72 \code{for x in \var{list}:\ a.append(x)}
  73 except that if there is a type error, the array is unchanged.
  74 \end{funcdesc}
  75
  76 \begin{funcdesc}{fromstring}{s}
  77 Appends items from the string, interpreting the string as an
  78 array of machine values (i.e. as if it had been read from a
  79 file using the \code{fromfile()} method).
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{insert}{i\, x}
  83 Insert a new item with value \var{x} in the array before position
  84 \var{i}.
  85 \end{funcdesc}
  86
  87 \begin{funcdesc}{tofile}{f}
  88 Write all items (as machine values) to the file object \var{f}.
  89 \end{funcdesc}
  90
  91 \begin{funcdesc}{tolist}{}
  92 Convert the array to an ordinary list with the same items.
  93 \end{funcdesc}
  94
  95 \begin{funcdesc}{tostring}{}
  96 Convert the array to an array of machine values and return the
  97 string representation (the same sequence of bytes that would
  98 be written to a file by the \code{tofile()} method.)
  99 \end{funcdesc}
 100
 101 When an array object is printed or converted to a string, it is
 102 represented as \code{array(\var{typecode}, \var{initializer})}.  The
 103 \var{initializer} is omitted if the array is empty, otherwise it is a
 104 string if the \var{typecode} is \code{'c'}, otherwise it is a list of
 105 numbers.  The string is guaranteed to be able to be converted back to
 106 an array with the same type and value using reverse quotes
 107 (\code{``}).  Examples:
 108
 109 \bcode\begin{verbatim}
 110 array('l')
 111 array('c', 'hello world')
 112 array('l', [1, 2, 3, 4, 5])
 113 array('d', [1.0, 2.0, 3.14])
 114 \end{verbatim}\ecode