#22237: document that sorted() is guaranteed to be stable. Initial patch by Martin...

diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
index 8b69b62aff5c1edcd5b2f5373fecc1b9c95c2b69..3766d43da26d484c40372f3801219b65af4f825d 100644 (file)
--- a/Doc/library/functions.rst
+++ b/Doc/library/functions.rst
@@ -1286,6 +1286,11 @@ are always available.  They are listed here in alphabetical order.
    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
index 4f1a682a875b65d3b9dd2796fbd33291d4d6dbf8..6a6148025b5c0e89837e3efa0f1850112d534e9d 100644 (file)
--- a/Doc/library/heapq.rst
+++ b/Doc/library/heapq.rst
@@ -123,7 +123,6 @@ pushing all values onto a heap and then popping off the smallest values one at a
 time::
 
    >>> def heapsort(iterable):
-   ...     'Equivalent to sorted(iterable)'
    ...     h = []
    ...     for value in iterable:
    ...         heappush(h, value)
@@ -132,6 +131,9 @@ time::
    >>> 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::