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 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.  \var{f} must be a real
  63 built-in file object; something else with a \code{read()} method won't
  64 do.
  65 \end{funcdesc}
  66
  67 \begin{funcdesc}{fromlist}{list}
  68 Append items from the list.  This is equivalent to
  69 \code{for x in \var{list}:\ a.append(x)}
  70 except that if there is a type error, the array is unchanged.
  71 \end{funcdesc}
  72
  73 \begin{funcdesc}{fromstring}{s}
  74 Appends items from the string, interpreting the string as an
  75 array of machine values (i.e. as if it had been read from a
  76 file using the \code{fromfile()} method).
  77 \end{funcdesc}
  78
  79 \begin{funcdesc}{insert}{i\, x}
  80 Insert a new item with value \var{x} in the array before position
  81 \var{i}.
  82 \end{funcdesc}
  83
  84 \begin{funcdesc}{tofile}{f}
  85 Write all items (as machine values) to the file object \var{f}.
  86 \end{funcdesc}
  87
  88 \begin{funcdesc}{tolist}{}
  89 Convert the array to an ordinary list with the same items.
  90 \end{funcdesc}
  91
  92 \begin{funcdesc}{tostring}{}
  93 Convert the array to an array of machine values and return the
  94 string representation (the same sequence of bytes that would
  95 be written to a file by the \code{tofile()} method.)
  96 \end{funcdesc}
  97
  98 When an array object is printed or converted to a string, it is
  99 represented as \code{array(\var{typecode}, \var{initializer})}.  The
 100 \var{initializer} is omitted if the array is empty, otherwise it is a
 101 string if the \var{typecode} is \code{'c'}, otherwise it is a list of
 102 numbers.  The string is guaranteed to be able to be converted back to
 103 an array with the same type and value using reverse quotes
 104 (\code{``}).  Examples:
 105
 106 \bcode\begin{verbatim}
 107 array('l')
 108 array('c', 'hello world')
 109 array('l', [1, 2, 3, 4, 5])
 110 array('d', [1.0, 2.0, 3.14])
 111 \end{verbatim}\ecode