[Python-checkins] python/dist/src/Doc/lib libitertools.tex,1.5,1.6

[rhettinger@users.sourceforge.net]

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

Modified Files:
	libitertools.tex 
Log Message:
User requested changes to the itertools module.
Subsumed times() into repeat().  
Added cycle() and chain().



Index: libitertools.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libitertools.tex,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** libitertools.tex	21 Feb 2003 01:45:34 -0000	1.5
--- libitertools.tex	23 Feb 2003 04:40:07 -0000	1.6
***************
*** 34,53 ****
  computer equivalent of ``inventory''.
  
! Some tools were omitted from the module because they offered no
! advantage over their pure python counterparts or because their behavior
! was too surprising.
! 
! For instance, SML provides a tool:  \code{cycle(\var{seq})} which
! loops over the sequence elements and then starts again when the
! sequence is exhausted.  The surprising behavior is the need for
! significant auxiliary storage (which is unusual for an iterator).
! If needed, the tool is readily constructible using pure Python.
! 
! Other tools are being considered for inclusion in future versions of the
! module.  For instance, the function
! \function{chain(\var{it0}, \var{it1}, ...)} would return elements from
! the first iterator until it was exhausted and then move on to each
! successive iterator.  The module author welcomes suggestions for other
! basic building blocks.
  
  \begin{seealso}
--- 34,39 ----
  computer equivalent of ``inventory''.
  
! The module author welcomes suggestions for other basic building blocks
! to be added to future versions of the module.
  
  \begin{seealso}
***************
*** 68,71 ****
--- 54,71 ----
  by functions or loops that truncate the stream.
  
+ \begin{funcdesc}{chain}{*iterables}
+   Make an iterator that returns elements from the first iterable until
+   it is exhausted, then proceeds to the next iterable, until all of the
+   iterables are exhausted.  Used for treating consecutive sequences as
+   a single sequence.  Equivalent to:
+ 
+   \begin{verbatim}
+      def chain(*iterables):
+          for it in iterables:
+              for element in it:
+                  yield element
+   \end{verbatim}
+ \end{funcdesc}
+ 
  \begin{funcdesc}{count}{\optional{n}}
    Make an iterator that returns consecutive integers starting with \var{n}.
***************
*** 86,89 ****
--- 86,112 ----
  \end{funcdesc}
  
+ \begin{funcdesc}{cycle}{iterable}
+   Make an iterator returning elements from the iterable and saving a
+   copy of each.  When the iterable is exhausted, return elements from
+   the saved copy.  Repeats indefinitely.  Equivalent to:
+ 
+   \begin{verbatim}
+      def cycle(iterable):
+          saved = []
+          for element in iterable:
+              yield element
+              saved.append(element)
+          if len(saved) == 0:
+              return
+          while True:
+              for element in saved:
+                    yield element
+   \end{verbatim}
+ 
+   Note, this is the only member of the toolkit that may require
+   significant auxiliary storage (depending on the length of the
+   iterable.
+ \end{funcdesc}
+ 
  \begin{funcdesc}{dropwhile}{predicate, iterable}
    Make an iterator that drops elements from the iterable as long as
***************
*** 208,213 ****
  \end{funcdesc}
  
! \begin{funcdesc}{repeat}{object}
    Make an iterator that returns \var{object} over and over again.
    Used as argument to \function{imap()} for invariant parameters
    to the called function.  Also used with \function{izip()} to create
--- 231,237 ----
  \end{funcdesc}
  
! \begin{funcdesc}{repeat}{object\optional{, times}}
    Make an iterator that returns \var{object} over and over again.
+   Runs indefinitely unless the \var{times} argument is specified.
    Used as argument to \function{imap()} for invariant parameters
    to the called function.  Also used with \function{izip()} to create
***************
*** 215,221 ****
  
    \begin{verbatim}
!      def repeat(object):
!          while True:
!              yield object
    \end{verbatim}
  \end{funcdesc}
--- 239,249 ----
  
    \begin{verbatim}
!      def repeat(object, times=None):
!          if times is None:
!              while True:
!                  yield object
!          else:
!              for i in xrange(times):
!                  yield object
    \end{verbatim}
  \end{funcdesc}
***************
*** 254,271 ****
  \end{funcdesc}
  
- \begin{funcdesc}{times}{n, \optional{object}}
-   Make an iterator that returns \var{object} \var{n} times.
-   \var{object} defaults to \code{None}.  Used for looping a specific
-   number of times without creating a number object on each pass.
-   Equivalent to:
- 
-   \begin{verbatim}
-      def times(n, object=None):
-          if n<0 : raise ValueError
-          for i in xrange(n):
-              yield object
-   \end{verbatim}
- \end{funcdesc}
- 
  
  \subsection{Examples \label{itertools-example}}
--- 282,285 ----
***************
*** 275,284 ****
  
  \begin{verbatim}
- >>> for i in times(3):
- ...     print "Hello"
- ...
- Hello
- Hello
- Hello
  
  >>> amounts = [120.15, 764.05, 823.14]
--- 289,292 ----
***************
*** 343,346 ****
--- 351,358 ----
  ...     "Returns True if pred(x) is False for every element in the iterable"
  ...     return not nth(ifilter(pred, seq), 0)
+ 
+ >>> def pairwise(seq):
+ ...     "s -> (s0,s1), (s1,s2), (s2, s3), ..."
+ ...     return izip(seq, islice(seq,1,len(seq)))
  
  \end{verbatim}