From b5c64e2e261ab2d3a009ccf1630d532202400009 Mon Sep 17 00:00:00 2001 From: Corey Farwell Date: Sun, 30 Sep 2018 12:28:34 -0400 Subject: [PATCH] Clarify docs for when binary_search has many matches. Fixes https://github.com/rust-lang/rust/issues/51817. --- src/libcore/slice/mod.rs | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/src/libcore/slice/mod.rs b/src/libcore/slice/mod.rs index 05027bbe898..fb8f2e3e84a 100644 --- a/src/libcore/slice/mod.rs +++ b/src/libcore/slice/mod.rs @@ -1174,9 +1174,10 @@ pub fn ends_with(&self, needle: &[T]) -> bool /// Binary searches this sorted slice for a given element. /// - /// If the value is found then `Ok` is returned, containing the - /// index of the matching element; if the value is not found then - /// `Err` is returned, containing the index where a matching + /// If the value is found then [`Result::Ok`] is returned, containing the + /// index of the matching element. If there are multiple matches, then any + /// one of the matches could be returned. If the value is not found then + /// [`Result::Err`] is returned, containing the index where a matching /// element could be inserted while maintaining sorted order. /// /// # Examples @@ -1208,9 +1209,10 @@ pub fn binary_search(&self, x: &T) -> Result /// order code that indicates whether its argument is `Less`, /// `Equal` or `Greater` the desired target. /// - /// If a matching value is found then returns `Ok`, containing - /// the index for the matched element; if no match is found then - /// `Err` is returned, containing the index where a matching + /// If the value is found then [`Result::Ok`] is returned, containing the + /// index of the matching element. If there are multiple matches, then any + /// one of the matches could be returned. If the value is not found then + /// [`Result::Err`] is returned, containing the index where a matching /// element could be inserted while maintaining sorted order. /// /// # Examples @@ -1264,10 +1266,11 @@ pub fn binary_search_by<'a, F>(&'a self, mut f: F) -> Result /// Assumes that the slice is sorted by the key, for instance with /// [`sort_by_key`] using the same key extraction function. /// - /// If a matching value is found then returns `Ok`, containing the - /// index for the matched element; if no match is found then `Err` - /// is returned, containing the index where a matching element could - /// be inserted while maintaining sorted order. + /// If the value is found then [`Result::Ok`] is returned, containing the + /// index of the matching element. If there are multiple matches, then any + /// one of the matches could be returned. If the value is not found then + /// [`Result::Err`] is returned, containing the index where a matching + /// element could be inserted while maintaining sorted order. /// /// [`sort_by_key`]: #method.sort_by_key /// -- 2.44.0