Skip to content

Enhanced doucmentation of binary search methods for slice and VecDeque for unsorted instances #106985

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

Merged
merged 2 commits into from
Mar 30, 2023
Merged

Enhanced doucmentation of binary search methods for slice and VecDeque for unsorted instances #106985

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
37ed3ce
enhanced documentation of binary search methods for slice and VecDequ…
jofas Mar 29, 2023
b085007
removed deprecated markdown links from documentation
jofas Mar 30, 2023
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
20 changes: 10 additions & 10 deletions library/alloc/src/collections/vec_deque/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2378,7 +2378,8 @@ impl<T, A: Allocator> VecDeque<T, A> {
}

/// Binary searches this `VecDeque` for a given element.
/// This behaves similarly to [`contains`] if this `VecDeque` is sorted.
/// If the `VecDeque` is not sorted, the returned result is unspecified and
/// meaningless.
///
/// If the value is found then [`Result::Ok`] is returned, containing the
/// index of the matching element. If there are multiple matches, then any
Expand All @@ -2388,7 +2389,6 @@ impl<T, A: Allocator> VecDeque<T, A> {
///
/// See also [`binary_search_by`], [`binary_search_by_key`], and [`partition_point`].
///
/// [`contains`]: VecDeque::contains
/// [`binary_search_by`]: VecDeque::binary_search_by
/// [`binary_search_by_key`]: VecDeque::binary_search_by_key
/// [`partition_point`]: VecDeque::partition_point
Expand Down Expand Up @@ -2434,12 +2434,13 @@ impl<T, A: Allocator> VecDeque<T, A> {
}

/// Binary searches this `VecDeque` with a comparator function.
/// This behaves similarly to [`contains`] if this `VecDeque` is sorted.
///
/// The comparator function should implement an order consistent
/// with the sort order of the deque, returning an order code that
/// indicates whether its argument is `Less`, `Equal` or `Greater`
/// than the desired target.
/// The comparator function should return an order code that indicates
/// whether its argument is `Less`, `Equal` or `Greater` the desired
/// target.
/// If the `VecDeque` is not sorted or if the comparator function does not
/// implement an order consistent with the sort order of the underlying
/// `VecDeque`, the returned result is unspecified and meaningless.
///
/// If the value is found then [`Result::Ok`] is returned, containing the
/// index of the matching element. If there are multiple matches, then any
Expand All @@ -2449,7 +2450,6 @@ impl<T, A: Allocator> VecDeque<T, A> {
///
/// See also [`binary_search`], [`binary_search_by_key`], and [`partition_point`].
///
/// [`contains`]: VecDeque::contains
/// [`binary_search`]: VecDeque::binary_search
/// [`binary_search_by_key`]: VecDeque::binary_search_by_key
/// [`partition_point`]: VecDeque::partition_point
Expand Down Expand Up @@ -2489,10 +2489,11 @@ impl<T, A: Allocator> VecDeque<T, A> {
}

/// Binary searches this `VecDeque` with a key extraction function.
/// This behaves similarly to [`contains`] if this `VecDeque` is sorted.
///
/// Assumes that the deque is sorted by the key, for instance with
/// [`make_contiguous().sort_by_key()`] using the same key extraction function.
/// If the deque is not sorted by the key, the returned result is
/// unspecified and meaningless.
///
/// If the value is found then [`Result::Ok`] is returned, containing the
/// index of the matching element. If there are multiple matches, then any
Expand All @@ -2502,7 +2503,6 @@ impl<T, A: Allocator> VecDeque<T, A> {
///
/// See also [`binary_search`], [`binary_search_by`], and [`partition_point`].
///
/// [`contains`]: VecDeque::contains
/// [`make_contiguous().sort_by_key()`]: VecDeque::make_contiguous
/// [`binary_search`]: VecDeque::binary_search
/// [`binary_search_by`]: VecDeque::binary_search_by
Expand Down
20 changes: 10 additions & 10 deletions library/core/src/slice/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2343,7 +2343,8 @@ impl<T> [T] {
}

/// Binary searches this slice for a given element.
/// This behaves similarly to [`contains`] if this slice is sorted.
/// If the slice is not sorted, the returned result is unspecified and
/// meaningless.
///
/// If the value is found then [`Result::Ok`] is returned, containing the
/// index of the matching element. If there are multiple matches, then any
Expand All @@ -2355,7 +2356,6 @@ impl<T> [T] {
///
/// See also [`binary_search_by`], [`binary_search_by_key`], and [`partition_point`].
///
/// [`contains`]: slice::contains
/// [`binary_search_by`]: slice::binary_search_by
/// [`binary_search_by_key`]: slice::binary_search_by_key
/// [`partition_point`]: slice::partition_point
Expand Down Expand Up @@ -2418,12 +2418,13 @@ impl<T> [T] {
}

/// Binary searches this slice with a comparator function.
/// This behaves similarly to [`contains`] if this slice is sorted.
///
/// The comparator function should implement an order consistent
/// with the sort order of the underlying slice, returning an
/// order code that indicates whether its argument is `Less`,
/// `Equal` or `Greater` the desired target.
/// The comparator function should return an order code that indicates
/// whether its argument is `Less`, `Equal` or `Greater` the desired
/// target.
/// If the slice is not sorted or if the comparator function does not
/// implement an order consistent with the sort order of the underlying
/// slice, the returned result is unspecified and meaningless.
///
/// If the value is found then [`Result::Ok`] is returned, containing the
/// index of the matching element. If there are multiple matches, then any
Expand All @@ -2435,7 +2436,6 @@ impl<T> [T] {
///
/// See also [`binary_search`], [`binary_search_by_key`], and [`partition_point`].
///
/// [`contains`]: slice::contains
/// [`binary_search`]: slice::binary_search
/// [`binary_search_by_key`]: slice::binary_search_by_key
/// [`partition_point`]: slice::partition_point
Expand Down Expand Up @@ -2504,10 +2504,11 @@ impl<T> [T] {
}

/// Binary searches this slice with a key extraction function.
/// This behaves similarly to [`contains`] if this slice is sorted.
///
/// Assumes that the slice is sorted by the key, for instance with
/// [`sort_by_key`] using the same key extraction function.
/// If the slice is not sorted by the key, the returned result is
/// unspecified and meaningless.
///
/// If the value is found then [`Result::Ok`] is returned, containing the
/// index of the matching element. If there are multiple matches, then any
Expand All @@ -2519,7 +2520,6 @@ impl<T> [T] {
///
/// See also [`binary_search`], [`binary_search_by`], and [`partition_point`].
///
/// [`contains`]: slice::contains
/// [`sort_by_key`]: slice::sort_by_key
/// [`binary_search`]: slice::binary_search
/// [`binary_search_by`]: slice::binary_search_by
Expand Down