Rollup merge of rust-lang#121187 - Takashiidobe:takashi/examples-for-…

…quickselect, r=Nilstrieb

Add examples to document the return type of quickselect functions

Currently, `select_nth_unstable`, `select_nth_unstable_by`, and `select_nth_unstable_by_key`'s examples do not show how to use the return values of the functions in an example, so this PR adds that in.

Note: I didn't know what to call the parameters, so I settled on lesser, median, greater because the example is used for median finding so I retained that naming for the pivot, but lesser and greater are poor names for the example that sorts in descending order, because lesser and greater are then flipped.

I think it's common to say "lo" and "hi" for low and high respectively, but that's also not great when the comparator flips the elements. Otherwise, "left" and "right" are also commonly used but I think that's poor naming because some languages read right to left so those names are also unintuitive.

Lesser and greater are also not that great but I found a test that used `less`, `equal`, `greater` so I took that: https://github.com/rust-lang/rust/blob/dfa88b328f969871d12dba3b2c0257ab3ea6703a/library/core/tests/slice.rs#L1962

library/core/src/slice/mod.rs

@@ -3016,8 +3016,13 @@ impl<T> [T] {
  /// ```
  /// let mut v = [-5i32, 4, 2, -3, 1];
  ///
- /// // Find the median
- /// v.select_nth_unstable(2);
+ /// // Find the items less than or equal to the median, the median, and greater than or equal to
+ /// // the median.
+ /// let (lesser, median, greater) = v.select_nth_unstable(2);
+ ///
+ /// assert!(lesser == [-3, -5] || lesser == [-5, -3]);
+ /// assert_eq!(median, &mut 1);
+ /// assert!(greater == [4, 2] || greater == [2, 4]);
  ///
  /// // We are only guaranteed the slice will be one of the following, based on the way we sort
  /// // about the specified index.
@@ -3067,8 +3072,13 @@ impl<T> [T] {
  /// ```
  /// let mut v = [-5i32, 4, 2, -3, 1];
  ///
- /// // Find the median as if the slice were sorted in descending order.
- /// v.select_nth_unstable_by(2, |a, b| b.cmp(a));
+ /// // Find the items less than or equal to the median, the median, and greater than or equal to
+ /// // the median as if the slice were sorted in descending order.
+ /// let (lesser, median, greater) = v.select_nth_unstable_by(2, |a, b| b.cmp(a));
+ ///
+ /// assert!(lesser == [4, 2] || lesser == [2, 4]);
+ /// assert_eq!(median, &mut 1);
+ /// assert!(greater == [-3, -5] || greater == [-5, -3]);
  ///
  /// // We are only guaranteed the slice will be one of the following, based on the way we sort
  /// // about the specified index.
@@ -3122,8 +3132,13 @@ impl<T> [T] {
  /// ```
  /// let mut v = [-5i32, 4, 1, -3, 2];
  ///
- /// // Return the median as if the array were sorted according to absolute value.
- /// v.select_nth_unstable_by_key(2, |a| a.abs());
+ /// // Find the items less than or equal to the median, the median, and greater than or equal to
+ /// // the median as if the slice were sorted according to absolute value.
+ /// let (lesser, median, greater) = v.select_nth_unstable_by_key(2, |a| a.abs());
+ ///
+ /// assert!(lesser == [1, 2] || lesser == [2, 1]);
+ /// assert_eq!(median, &mut -3);
+ /// assert!(greater == [4, -5] || greater == [-5, 4]);
  ///
  /// // We are only guaranteed the slice will be one of the following, based on the way we sort
  /// // about the specified index.