Added documentation for the xreadlines module & related changes. The

documentation was written by Jeff Epler (thanks!).

1 files changed, 52 insertions, 0 deletions

diff --git a/Doc/lib/libxreadlines.tex b/Doc/lib/libxreadlines.tex
new file mode 100644
index 0000000..0285f03
--- /dev/null
+++ b/Doc/lib/libxreadlines.tex
@@ -0,0 +1,52 @@
+\section{\module{xreadlines} ---
+         Efficient iteration over a file}
+
+\declaremodule{extension}{xreadlines}
+\modulesynopsis{Efficient iteration over the lines of a file.}
+
+This module defines a new object type which can efficiently iterate
+over the lines of a file.  An xreadlines object is a sequence type
+which implements simple in-order indexing beginning at \code{0}, as
+required by \keyword{for} statement or the
+\function{filter()} function.
+
+Thus, the code
+
+\begin{verbatim}
+import xreadlines, sys
+
+for line in xreadlines.xreadlines(sys.stdin):
+    pass
+\end{verbatim}
+
+has approximately the same speed and memory consumption as
+
+\begin{verbatim}
+while 1:
+    lines = sys.stdin.readlines(8*1024)
+    if not lines: break
+    for line in lines:
+        pass
+\end{verbatim}
+
+except the clarity of the \keyword{for} statement is retained in the
+former case.
+
+\begin{funcdesc}{xreadlines}{fileobj}
+  Return a new xreadlines object which will iterate over the contents
+  of \var{fileobj}.  \var{fileobj} must have a \method{readlines()}
+  method that supports the \var{sizehint} parameter.
+\end{funcdesc}
+
+An xreadlines object \var{s} supports the following sequence
+operation:
+
+\begin{tableii}{c|l}{code}{Operation}{Result}
+ \lineii{\var{s}[\var{i}]}{\var{i}'th line of \var{s}}
+\end{tableii}
+
+If successive values of \var{i} are not sequential starting from
+\code{0}, this code will raise \exception{RuntimeError}.
+
+After the last line of the file is read, this code will raise an
+\exception{IndexError}.