summaryrefslogtreecommitdiffstats
path: root/Doc/lib
diff options
context:
space:
mode:
authorFred Drake <fdrake@acm.org>2001-01-09 22:47:46 (GMT)
committerFred Drake <fdrake@acm.org>2001-01-09 22:47:46 (GMT)
commit3c48ef7de8706835640441b821010001f35f41eb (patch)
tree2d7dca2668cc5c1f469209dbd7e3ea589f1ff233 /Doc/lib
parent92f4b366cbbc0840ad4fca34e7dfceead66a90b4 (diff)
downloadcpython-3c48ef7de8706835640441b821010001f35f41eb.zip
cpython-3c48ef7de8706835640441b821010001f35f41eb.tar.gz
cpython-3c48ef7de8706835640441b821010001f35f41eb.tar.bz2
Added documentation for the xreadlines module & related changes. The
documentation was written by Jeff Epler (thanks!).
Diffstat (limited to 'Doc/lib')
-rw-r--r--Doc/lib/lib.tex1
-rw-r--r--Doc/lib/libstdtypes.tex18
-rw-r--r--Doc/lib/libxreadlines.tex52
3 files changed, 65 insertions, 6 deletions
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index 1792d18..d0b44b5 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 0cb8264..fe53599 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 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}.