Doc total order requirement of sort(_unstable)_by

I took the definition of what a total order is from the Ord trait
docs. I specifically put "elements of the slice" because if you
have a slice of f64s, but know none are NaN, then sorting by
partial ord is total in this case. I'm not sure if I should give
such an example in the docs or not.

diff --git a/src/liballoc/slice.rs b/src/liballoc/slice.rs
index 33d28bef2d707fb618d9b50091ee14e5660cf58d..2ded376b395a7a23f6fae383711e2ba0f586723d 100644 (file)
--- a/src/liballoc/slice.rs
+++ b/src/liballoc/slice.rs
@@ -211,6 +211,13 @@ pub fn sort(&mut self)
     ///
     /// This sort is stable (i.e. does not reorder equal elements) and `O(n log n)` worst-case.
     ///
+    /// The comparator function must define a total ordering for the elements in the slice. If
+    /// the ordering is not total, the order of the elements is unspecified. An order is a
+    /// total order if it is (for all a, b and c):
+    ///
+    /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
+    /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
+    ///
     /// When applicable, unstable sorting is preferred because it is generally faster than stable
     /// sorting and it doesn't allocate auxiliary memory.
     /// See [`sort_unstable_by`](#method.sort_unstable_by).

diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs
index a50426ba886bb0e71b9d940f3c3cf28b39e8c01d..c22ea0a01f8e0fb1ea936c51c9117fa695ad60ec 100644 (file)
--- a/src/libcore/slice/mod.rs
+++ b/src/libcore/slice/mod.rs
@@ -1339,6 +1339,13 @@ pub fn sort_unstable(&mut self)
     /// This sort is unstable (i.e. may reorder equal elements), in-place (i.e. does not allocate),
     /// and `O(n log n)` worst-case.
     ///
+    /// The comparator function must define a total ordering for the elements in the slice. If
+    /// the ordering is not total, the order of the elements is unspecified. An order is a
+    /// total order if it is (for all a, b and c):
+    ///
+    /// * total and antisymmetric: exactly one of a < b, a == b or a > b is true; and
+    /// * transitive, a < b and b < c implies a < c. The same must hold for both == and >.
+    ///
     /// # Current implementation
     ///
     /// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters,