[Python-checkins] CVS: python/dist/src/Doc/lib libxreadlines.tex,NONE,1.1 lib.tex,1.174,1.175 libstdtypes.tex,1.46,1.47

[Fred L. Drake]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory usw-pr-cvs1:/tmp/cvs-serv26967/lib

Modified Files:
	lib.tex libstdtypes.tex 
Added Files:
	libxreadlines.tex 
Log Message:

Added documentation for the xreadlines module & related changes.  The
documentation was written by Jeff Epler (thanks!).


--- NEW FILE: libxreadlines.tex ---
\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}.

Index: lib.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/lib.tex,v
retrieving revision 1.174
retrieving revision 1.175
diff -C2 -r1.174 -r1.175
*** lib.tex	2001/01/09 20:52:49	1.174
--- lib.tex	2001/01/09 22:47:45	1.175
***************
*** 122,125 ****
--- 122,126 ----
  \input{libcfgparser}
  \input{libfileinput}
+ \input{libxreadlines}
  \input{libcalendar}
  \input{libcmd}

Index: libstdtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libstdtypes.tex,v
retrieving revision 1.46
retrieving revision 1.47
diff -C2 -r1.46 -r1.47
*** libstdtypes.tex	2001/01/04 05:16:39	1.46
--- libstdtypes.tex	2001/01/09 22:47:46	1.47
***************
*** 1102,1114 ****
  
  \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.
  \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.)
  \end{methoddesc}
  
--- 1102,1120 ----
  
  \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.
  \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.)
! \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}