diff options
| -rw-r--r-- | Doc/ACKS | 1 | ||||
| -rw-r--r-- | Doc/Makefile.deps | 1 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libstdtypes.tex | 18 | ||||
| -rw-r--r-- | Doc/lib/libxreadlines.tex | 52 |
5 files changed, 67 insertions, 6 deletions
@@ -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 8e02a94..2fe792e 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 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}. |