Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

resolve #130122: reword 'sort-by' edge-conditions documentation #130416

Merged
merged 1 commit into from
Sep 29, 2024
Merged

resolve #130122: reword 'sort-by' edge-conditions documentation #130416

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 47 additions & 20 deletions library/alloc/src/slice.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -180,10 +180,9 @@ impl<T> [T] {
/// This sort is stable (i.e., does not reorder equal elements) and *O*(*n* \* log(*n*))
/// worst-case.
///
/// If the implementation of [`Ord`] for `T` does not implement a [total order] the resulting
/// order of elements in the slice is unspecified. All original elements will remain in the
/// slice and any possible modifications via interior mutability are observed in the input. Same
/// is true if the implementation of [`Ord`] for `T` panics.
/// If the implementation of [`Ord`] for `T` does not implement a [total order], the function
/// may panic; even if the function exits normally, the resulting order of elements in the slice
/// is unspecified. See also the note on panicking below.
///
/// When applicable, unstable sorting is preferred because it is generally faster than stable
/// sorting and it doesn't allocate auxiliary memory. See
Expand Down Expand Up @@ -212,7 +211,15 @@ impl<T> [T] {
///
/// # Panics
///
/// May panic if the implementation of [`Ord`] for `T` does not implement a [total order].
/// May panic if the implementation of [`Ord`] for `T` does not implement a [total order], or if
/// the [`Ord`] implementation itself panics.
///
/// All safe functions on slices preserve the invariant that even if the function panics, all
/// original elements will remain in the slice and any possible modifications via interior
/// mutability are observed in the input. This ensures that recovery code (for instance inside
/// of a `Drop` or following a `catch_unwind`) will still have access to all the original
/// elements. For instance, if the slice belongs to a `Vec`, the `Vec::drop` method will be able
/// to dispose of all contained elements.
///
/// # Examples
///
Expand Down Expand Up @@ -241,10 +248,9 @@ impl<T> [T] {
/// This sort is stable (i.e., does not reorder equal elements) and *O*(*n* \* log(*n*))
/// worst-case.
///
/// If the comparison function `compare` does not implement a [total order] the resulting order
/// of elements in the slice is unspecified. All original elements will remain in the slice and
/// any possible modifications via interior mutability are observed in the input. Same is true
/// if `compare` panics.
/// If the comparison function `compare` does not implement a [total order], the function may
/// panic; even if the function exits normally, the resulting order of elements in the slice is
/// unspecified. See also the note on panicking below.
///
/// For example `|a, b| (a - b).cmp(a)` is a comparison function that is neither transitive nor
/// reflexive nor total, `a < b < c < a` with `a = 1, b = 2, c = 3`. For more information and
Expand All @@ -263,7 +269,14 @@ impl<T> [T] {
///
/// # Panics
///
/// May panic if `compare` does not implement a [total order].
/// May panic if `compare` does not implement a [total order], or if `compare` itself panics.
///
/// All safe functions on slices preserve the invariant that even if the function panics, all
/// original elements will remain in the slice and any possible modifications via interior
/// mutability are observed in the input. This ensures that recovery code (for instance inside
/// of a `Drop` or following a `catch_unwind`) will still have access to all the original
/// elements. For instance, if the slice belongs to a `Vec`, the `Vec::drop` method will be able
/// to dispose of all contained elements.
///
/// # Examples
///
Expand Down Expand Up @@ -295,10 +308,9 @@ impl<T> [T] {
/// This sort is stable (i.e., does not reorder equal elements) and *O*(*m* \* *n* \* log(*n*))
/// worst-case, where the key function is *O*(*m*).
///
/// If the implementation of [`Ord`] for `K` does not implement a [total order] the resulting
/// order of elements in the slice is unspecified. All original elements will remain in the
/// slice and any possible modifications via interior mutability are observed in the input. Same
/// is true if the implementation of [`Ord`] for `K` panics.
/// If the implementation of [`Ord`] for `K` does not implement a [total order], the function
/// may panic; even if the function exits normally, the resulting order of elements in the slice
/// is unspecified. See also the note on panicking below.
///
/// # Current implementation
///
Expand All @@ -313,7 +325,15 @@ impl<T> [T] {
///
/// # Panics
///
/// May panic if the implementation of [`Ord`] for `K` does not implement a [total order].
/// May panic if the implementation of [`Ord`] for `K` does not implement a [total order], or if
/// the [`Ord`] implementation or the key-function `f` panics.
///
/// All safe functions on slices preserve the invariant that even if the function panics, all
/// original elements will remain in the slice and any possible modifications via interior
/// mutability are observed in the input. This ensures that recovery code (for instance inside
/// of a `Drop` or following a `catch_unwind`) will still have access to all the original
/// elements. For instance, if the slice belongs to a `Vec`, the `Vec::drop` method will be able
/// to dispose of all contained elements.
///
/// # Examples
///
Expand Down Expand Up @@ -347,10 +367,9 @@ impl<T> [T] {
/// storage to remember the results of key evaluation. The order of calls to the key function is
/// unspecified and may change in future versions of the standard library.
///
/// If the implementation of [`Ord`] for `K` does not implement a [total order] the resulting
/// order of elements in the slice is unspecified. All original elements will remain in the
/// slice and any possible modifications via interior mutability are observed in the input. Same
/// is true if the implementation of [`Ord`] for `K` panics.
/// If the implementation of [`Ord`] for `K` does not implement a [total order], the function
/// may panic; even if the function exits normally, the resulting order of elements in the slice
/// is unspecified. See also the note on panicking below.
///
/// For simple key functions (e.g., functions that are property accesses or basic operations),
/// [`sort_by_key`](slice::sort_by_key) is likely to be faster.
Expand All @@ -369,7 +388,15 @@ impl<T> [T] {
///
/// # Panics
///
/// May panic if the implementation of [`Ord`] for `K` does not implement a [total order].
/// May panic if the implementation of [`Ord`] for `K` does not implement a [total order], or if
/// the [`Ord`] implementation panics.
///
/// All safe functions on slices preserve the invariant that even if the function panics, all
/// original elements will remain in the slice and any possible modifications via interior
/// mutability are observed in the input. This ensures that recovery code (for instance inside
/// of a `Drop` or following a `catch_unwind`) will still have access to all the original
/// elements. For instance, if the slice belongs to a `Vec`, the `Vec::drop` method will be able
/// to dispose of all contained elements.
///
/// # Examples
///
Expand Down
Loading