add must_use to partial_shuffle

benches/benches/shuffle.rs

@@ -52,7 +52,7 @@ fn bench_rng<R: Rng + SeedableRng>(c: &mut Criterion, rng_name: &'static str) {
                 let mut rng = R::seed_from_u64(123);
                 let mut vec: Vec<usize> = (0..length).collect();
                 b.iter(|| {
-                    vec.partial_shuffle(&mut rng, length / 2);
+                    let _ = vec.partial_shuffle(&mut rng, length / 2);
                     vec[0]
                 })
             });

src/seq/slice.rs

@@ -437,6 +437,23 @@ pub trait SliceRandom: IndexedMutRandom {
     /// will perform a full shuffle.
     ///
     /// For slices, complexity is `O(m)` where `m = amount`.
+    ///
+    /// # Warning
+    ///
+    /// The position of the returned slices within the original slice is not guaranteed.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use rand::seq::SliceRandom;
+    ///
+    /// let mut rng = rand::rng();
+    /// let mut y = [1, 2, 3, 4, 5];
+    /// let (shuffled, rest) = y.partial_shuffle(&mut rng, 3);
+    /// assert_eq!(shuffled.len(), 3);
+    /// assert_eq!(rest.len(), 2);
+    /// ```
+    #[must_use = "the returned subslices should be used to access the shuffled elements; their position within the original slice is an implementation detail"]
     fn partial_shuffle<R>(
         &mut self,
         rng: &mut R,
@@ -464,7 +481,7 @@ impl<T> SliceRandom for [T] {
             // There is no need to shuffle an empty or single element slice
             return;
         }
-        self.partial_shuffle(rng, self.len());
+        let _ = self.partial_shuffle(rng, self.len());
     }
 
     fn partial_shuffle<R>(&mut self, rng: &mut R, amount: usize) -> (&mut [T], &mut [T])