Doc/lib/libxreadlines.tex

   1 \section{\module{xreadlines} ---
   2          Efficient iteration over a file}
   3
   4 \declaremodule{extension}{xreadlines}
   5 \modulesynopsis{Efficient iteration over the lines of a file.}
   6
   7 \versionadded{2.1}
   8
   9 \deprecated{2.3}{Use \code{for line in file} instead.}
  10
  11 This module defines a new object type which can efficiently iterate
  12 over the lines of a file.  An xreadlines object is a sequence type
  13 which implements simple in-order indexing beginning at \code{0}, as
  14 required by \keyword{for} statement or the
  15 \function{filter()} function.
  16
  17 Thus, the code
  18
  19 \begin{verbatim}
  20 import xreadlines, sys
  21
  22 for line in xreadlines.xreadlines(sys.stdin):
  23     pass
  24 \end{verbatim}
  25
  26 has approximately the same speed and memory consumption as
  27
  28 \begin{verbatim}
  29 while 1:
  30     lines = sys.stdin.readlines(8*1024)
  31     if not lines: break
  32     for line in lines:
  33         pass
  34 \end{verbatim}
  35
  36 except the clarity of the \keyword{for} statement is retained in the
  37 former case.
  38
  39 \begin{funcdesc}{xreadlines}{fileobj}
  40   Return a new xreadlines object which will iterate over the contents
  41   of \var{fileobj}.  \var{fileobj} must have a \method{readlines()}
  42   method that supports the \var{sizehint} parameter.  \note{Because
  43   the \method{readlines()} method buffers data, this effectively
  44   ignores the effects of setting the file object as unbuffered.}
  45 \end{funcdesc}
  46
  47 An xreadlines object \var{s} supports the following sequence
  48 operation:
  49
  50 \begin{tableii}{c|l}{code}{Operation}{Result}
  51  \lineii{\var{s}[\var{i}]}{\var{i}'th line of \var{s}}
  52 \end{tableii}
  53
  54 If successive values of \var{i} are not sequential starting from
  55 \code{0}, this code will raise \exception{RuntimeError}.
  56
  57 After the last line of the file is read, this code will raise an
  58 \exception{IndexError}.