From ba8cfdad9427ba330bfa3ffbb97a2ec52360e95f Mon Sep 17 00:00:00 2001
From: Raymond Hettinger <python@rcn.com>
Date: Thu, 12 Nov 2009 17:42:47 +0000
Subject: [PATCH] Add examples to whatsnew entry for OrderedDict.

---
 Doc/whatsnew/3.1.rst | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Doc/whatsnew/3.1.rst b/Doc/whatsnew/3.1.rst
index c76fd6872f1..2179bf7f6f7 100644
--- a/Doc/whatsnew/3.1.rst
+++ b/Doc/whatsnew/3.1.rst
@@ -81,6 +81,28 @@ Support was also added for third-party tools like `PyYAML <http://pyyaml.org/>`_
       PEP written by Armin Ronacher and Raymond Hettinger.  Implementation
       written by Raymond Hettinger.
 
+Since an ordered dictionary remembers its insertion order, it can be used
+in conjuction with sorting to make a sorted dictionary::
+
+    >>> # regular unsorted dictionary
+    >>> d = {'banana': 3, 'apple':4, 'pear': 1, 'orange': 2}
+
+    >>> # dictionary sorted by key
+    >>> OrderedDict(sorted(d.items(), key=lambda t: t[0]))
+    OrderedDict([('apple', 4), ('banana', 3), ('orange', 2), ('pear', 1)])
+
+    >>> # dictionary sorted by value
+    >>> OrderedDict(sorted(d.items(), key=lambda t: t[1]))
+    OrderedDict([('pear', 1), ('orange', 2), ('banana', 3), ('apple', 4)])
+
+    >>> # dictionary sorted by length of the key string
+    >>> OrderedDict(sorted(d.items(), key=lambda t: len(t[0])))
+    OrderedDict([('pear', 1), ('apple', 4), ('orange', 2), ('banana', 3)])
+
+The new sorted dictionaries maintain their sort order when entries
+are deleted.  But when new keys are added, the keys are appended
+to the end and the sort is not maintained.
+
 
 PEP 378: Format Specifier for Thousands Separator
 =================================================