Auto merge of #53918 - Havvy:doc-sort-by, r=GuillaumeGomez
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. r? @GuillaumeGomez
This commit is contained in:
commit
f3adec65dd
2 changed files with 32 additions and 0 deletions
|
@ -213,6 +213,22 @@ impl<T> [T] {
|
|||
///
|
||||
/// 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 >.
|
||||
///
|
||||
/// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use
|
||||
/// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
|
||||
///
|
||||
/// ```
|
||||
/// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
|
||||
/// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
|
||||
/// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
|
||||
/// ```
|
||||
///
|
||||
/// 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).
|
||||
|
|
|
@ -1510,6 +1510,22 @@ impl<T> [T] {
|
|||
/// 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 >.
|
||||
///
|
||||
/// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use
|
||||
/// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`.
|
||||
///
|
||||
/// ```
|
||||
/// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
|
||||
/// floats.sort_by(|a, b| a.partial_cmp(b).unwrap());
|
||||
/// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
|
||||
/// ```
|
||||
///
|
||||
/// # Current implementation
|
||||
///
|
||||
/// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters,
|
||||
|
|
Loading…
Reference in a new issue