From 3c48ef7de8706835640441b821010001f35f41eb Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Tue, 9 Jan 2001 22:47:46 +0000
Subject: [PATCH] Added documentation for the xreadlines module & related
 changes.  The documentation was written by Jeff Epler (thanks!).

---
 Doc/ACKS                  |  1 +
 Doc/Makefile.deps         |  1 +
 Doc/lib/lib.tex           |  1 +
 Doc/lib/libstdtypes.tex   | 18 +++++++++-----
 Doc/lib/libxreadlines.tex | 52 +++++++++++++++++++++++++++++++++++++++
 5 files changed, 67 insertions(+), 6 deletions(-)
 create mode 100644 Doc/lib/libxreadlines.tex

diff --git a/Doc/ACKS b/Doc/ACKS
index b4bbc3fbcd4..577a0033294 100644
--- a/Doc/ACKS
+++ b/Doc/ACKS
@@ -38,6 +38,7 @@ Andrew Dalke
 Ben Darnell
 Robert Donohue
 Fred L. Drake, Jr.
+Jeff Epler
 Michael Ernst
 Blame Andy Eskilsson
 Martijn Faassen
diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps
index 8e02a948163..2fe792e9741 100644
--- a/Doc/Makefile.deps
+++ b/Doc/Makefile.deps
@@ -190,6 +190,7 @@ LIBFILES= $(MANSTYLES) $(COMMONTEX) \
 	../lib/libuu.tex \
 	../lib/libsunaudio.tex \
 	../lib/libfileinput.tex \
+	../lib/libxreadlines.tex \
 	../lib/libimaplib.tex \
 	../lib/libpoplib.tex \
 	../lib/libcalendar.tex \
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 1792d1824ac..d0b44b57ce9 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -121,6 +121,7 @@ and how to embed it in other applications.
 \input{libarray}
 \input{libcfgparser}
 \input{libfileinput}
+\input{libxreadlines}
 \input{libcalendar}
 \input{libcmd}
 \input{libshlex}
diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index 0cb82640a5e..fe535999a62 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -1101,15 +1101,21 @@ Files have the following methods:
 \end{methoddesc}
 
 \begin{methoddesc}[file]{write}{str}
-Write a string to the file.  There is no return value.  Note: Due to
-buffering, the string may not actually show up in the file until
-the \method{flush()} or \method{close()} method is called.
+  Write a string to the file.  There is no return value.  Note: Due to
+  buffering, the string may not actually show up in the file until
+  the \method{flush()} or \method{close()} method is called.
 \end{methoddesc}
 
 \begin{methoddesc}[file]{writelines}{list}
-Write a list of strings to the file.  There is no return value.
-(The name is intended to match \method{readlines()};
-\method{writelines()} does not add line separators.)
+  Write a list of strings to the file.  There is no return value.
+  (The name is intended to match \method{readlines()};
+  \method{writelines()} does not add line separators.)
+\end{methoddesc}
+
+\begin{methoddesc}[file]{xreadlines}{}
+  Equivalent to
+  \function{xreadlines.xreadlines(\var{file})}.\refstmodindex{xreadlines}
+  (See the \refmodule{xreadlines} module for more information.)
 \end{methoddesc}
 
 
diff --git a/Doc/lib/libxreadlines.tex b/Doc/lib/libxreadlines.tex
new file mode 100644
index 00000000000..0285f03ac6e
--- /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}.