[Python-checkins] cpython (2.7): #22237: document that sorted() is guaranteed to be stable. Initial patch by

ezio.melotti python-checkins at python.org
Tue Oct 28 12:59:50 CET 2014


https://hg.python.org/cpython/rev/d44f7d229e00
changeset:   93176:d44f7d229e00
branch:      2.7
parent:      93173:4391ab72dd7b
user:        Ezio Melotti <ezio.melotti at gmail.com>
date:        Tue Oct 28 12:57:11 2014 +0100
summary:
  #22237: document that sorted() is guaranteed to be stable.  Initial patch by Martin Panter.

files:
  Doc/library/functions.rst |  5 +++++
  Doc/library/heapq.rst     |  4 +++-
  Misc/ACKS                 |  1 +
  3 files changed, 9 insertions(+), 1 deletions(-)


diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1318,6 +1318,11 @@
    each element only once.  Use :func:`functools.cmp_to_key` to convert an
    old-style *cmp* function to a *key* function.
 
+   The built-in :func:`sorted` function is guaranteed to be stable. A sort is
+   stable if it guarantees not to change the relative order of elements that
+   compare equal --- this is helpful for sorting in multiple passes (for
+   example, sort by department, then by salary grade).
+
    For sorting examples and a brief sorting tutorial, see `Sorting HowTo
    <http://wiki.python.org/moin/HowTo/Sorting/>`_\.
 
diff --git a/Doc/library/heapq.rst b/Doc/library/heapq.rst
--- a/Doc/library/heapq.rst
+++ b/Doc/library/heapq.rst
@@ -136,7 +136,6 @@
 time::
 
    >>> def heapsort(iterable):
-   ...     'Equivalent to sorted(iterable)'
    ...     h = []
    ...     for value in iterable:
    ...         heappush(h, value)
@@ -145,6 +144,9 @@
    >>> heapsort([1, 3, 5, 7, 9, 2, 4, 6, 8, 0])
    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
 
+This is similar to ``sorted(iterable)``, but unlike :func:`sorted`, this
+implementation is not stable.
+
 Heap elements can be tuples.  This is useful for assigning comparison values
 (such as task priorities) alongside the main record being tracked::
 
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1008,6 +1008,7 @@
 Juan David Ibáñez Palomar
 Jan Palus
 Yongzhi Pan
+Martin Panter
 Mathias Panzenböck
 M. Papillon
 Peter Parente

-- 
Repository URL: https://hg.python.org/cpython


More information about the Python-checkins mailing list