Add more docs for generator expressions.

* Put in a brief, example driven tutorial entry.
* Use better examples in whatsnew24.tex.

diff --git a/Doc/tut/tut.tex b/Doc/tut/tut.tex
index 87bc424f672557b6fd11f89c16ffae08023e3e97..c8c5afee8e9e9bbd1aac4f674620f5fd3d1d6204 100644 (file)
--- a/Doc/tut/tut.tex
+++ b/Doc/tut/tut.tex
@@ -4399,6 +4399,39 @@ generators terminate, they automatically raise \exception{StopIteration}.
 In combination, these features make it easy to create iterators with no
 more effort than writing a regular function.
 
+\section{Generator Expressions\label{genexps}}
+
+Some simple generators can be coded succinctly as expressions using a syntax
+like list comprehensions but with parentheses instead of brackets.  These
+expressions are designed for situations where the generator is used right
+away by an enclosing function.  Generator expressions are more compact but
+less versatile than full generator definitions and the tend to be more memory
+friendly than equivalent list comprehensions.
+
+Examples:
+
+\begin{verbatim}
+>>> sum(i*i for i in range(10))                 # sum of squares
+285
+
+>>> xvec = [10, 20, 30]
+>>> yvec = [7, 5, 3]
+>>> sum(x*y for x,y in zip(xvec, yvec))         # dot product
+260
+
+>>> from math import pi, sin
+>>> sine_table = dict((x, sin(x*pi/180)) for x in range(0, 91))
+
+>>> unique_words = set(word  for line in page  for word in line.split())
+
+>>> valedictorian = max((student.gpa, student.name) for student in graduates)
+
+>>> data = 'golf'
+>>> list(data[i] for i in range(len(data)-1,-1,-1))
+['f', 'l', 'o', 'g']
+
+\end{verbatim}
+
 
 
 \chapter{Brief Tour of the Standard Library \label{briefTour}}

diff --git a/Doc/whatsnew/whatsnew24.tex b/Doc/whatsnew/whatsnew24.tex
index c60f28a07895ca3b837c03d8064e1c2ac0728895..b25caeabba53215997aa2c488a7ec1d6f44c1e22 100644 (file)
--- a/Doc/whatsnew/whatsnew24.tex
+++ b/Doc/whatsnew/whatsnew24.tex
@@ -125,25 +125,28 @@ Generator expressions are intended to be used inside functions
 such as \function{sum()}, \function{min()}, \function{set()}, and
 \function{dict()}.  These functions consume their data all at once
 and would not benefit from having a full list instead of a generator
-an input:
+as an input:
 
 \begin{verbatim}
 >>> sum(i*i for i in range(10))
 285
 
->>> sorted(set(i*i for i in xrange(-10, 11)))
-[0, 1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
-
->>> words = "Adam apple baker Bill Nancy NASA nut".split()
->>> dict((word.lower(), word) for word in words)
-{'apple': 'apple', 'baker': 'baker', 'bill': 'Bill', 'nasa': 'NASA',
- 'adam': 'Adam', 'nancy': 'Nancy', 'nut': 'nut'}
+>>> sorted(set(i*i for i in xrange(-20, 20) if i%2==1)) # odd squares
+[1, 9, 25, 49, 81, 121, 169, 225, 289, 361]
 
+>>> from itertools import izip
 >>> xvec = [10, 20, 30]
 >>> yvec = [7, 5, 3]
->>> sum(x*y for x,y in itertools.izip(xvec, yvec))     # dot product
+>>> sum(x*y for x,y in izip(xvec, yvec))                # dot product
 260
 
+>>> from math import pi, sin
+>>> sine_table = dict((x, sin(x*pi/180)) for x in xrange(0, 91))
+
+>>> unique_words = set(word  for line in page  for word in line.split())
+
+>>> valedictorian = max((student.gpa, student.name) for student in graduates)
+
 \end{verbatim}     
 
 These examples show the intended use for generator expressions