From 017778332f7be58df770302a3ad7627faec2842c Mon Sep 17 00:00:00 2001
From: Fred Drake <fdrake@acm.org>
Date: Mon, 19 Aug 2002 21:58:58 +0000
Subject: [PATCH] Extend some comments on the order of values in the returns
 from dict.items/keys/values/iteritems/iterkeys/itervalues().

---
 Doc/lib/libstdtypes.tex | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex
index d3e0079d96e..9f23cdf3fe7 100644
--- a/Doc/lib/libstdtypes.tex
+++ b/Doc/lib/libstdtypes.tex
@@ -1049,13 +1049,13 @@ arbitrary objects):
           {(6)}
   \lineiii{\var{a}.iteritems()}
           {return an iterator over (\var{key}, \var{value}) pairs}
-          {(2)}
+          {(2), (3)}
   \lineiii{\var{a}.iterkeys()}
           {return an iterator over the mapping's keys}
-          {(2)}
+          {(2), (3)}
   \lineiii{\var{a}.itervalues()}
           {return an iterator over the mapping's values}
-          {(2)}
+          {(2), (3)}
 \end{tableiii}
 
 \noindent
@@ -1067,11 +1067,17 @@ in the map.
 \item[(2)] \versionadded{2.2}
 
 \item[(3)] Keys and values are listed in random order.  If
-\method{keys()} and \method{values()} are called with no intervening
-modifications to the dictionary, the two lists will directly
-correspond.  This allows the creation of \code{(\var{value},
-\var{key})} pairs using \function{zip()}: \samp{pairs =
-zip(\var{a}.values(), \var{a}.keys())}.
+\method{items()}, \method{keys()}, \method{values()},
+\method{iteritems()}, \method{iterkeys()}, and \method{itervalues()}
+are called with no intervening modifications to the dictionary, the
+lists will directly correspond.  This allows the creation of
+\code{(\var{value}, \var{key})} pairs using \function{zip()}:
+\samp{pairs = zip(\var{a}.values(), \var{a}.keys())}.  The same
+relationship holds for the \method{iterkeys()} and
+\method{itervalues()} methods: \samp{pairs = zip(\var{a}.itervalues(),
+\var{a}.iterkeys())} provides the same value for \code{pairs}.
+Another way to create the same list is \samp{pairs = [(v, k) for (k,
+v) in \var{a}.iteritems()]}.
 
 \item[(4)] Never raises an exception if \var{k} is not in the map,
 instead it returns \var{x}.  \var{x} is optional; when \var{x} is not