Rename fns IteratorRandom::choose_multiple* -> sample*

Author: dhardy

benches/benches/seq_choose.rs

@@ -77,21 +77,21 @@ pub fn bench(c: &mut Criterion) {
         });
     }
 
-    c.bench_function("seq_iter_choose_multiple_10_of_100", |b| {
+    c.bench_function("seq_iter_sample_10_of_100", |b| {
         let mut rng = Pcg32::from_rng(&mut rand::rng());
         let mut buf = [0i32; 100];
         rng.fill(&mut buf);
         let x = black_box(&buf);
-        b.iter(|| x.iter().cloned().choose_multiple(&mut rng, 10))
+        b.iter(|| x.iter().cloned().sample(&mut rng, 10))
     });
 
-    c.bench_function("seq_iter_choose_multiple_fill_10_of_100", |b| {
+    c.bench_function("seq_iter_sample_fill_10_of_100", |b| {
         let mut rng = Pcg32::from_rng(&mut rand::rng());
         let mut buf = [0i32; 100];
         rng.fill(&mut buf);
         let x = black_box(&buf);
         let mut buf = [0; 10];
-        b.iter(|| x.iter().cloned().choose_multiple_fill(&mut rng, &mut buf))
+        b.iter(|| x.iter().cloned().sample_fill(&mut rng, &mut buf))
     });
 
     bench_rng::<rand_chacha::ChaCha20Rng>(c, "ChaCha20");

src/seq/iterator.rs

@@ -195,8 +195,8 @@ pub trait IteratorRandom: Iterator + Sized {
     /// case this equals the number of elements available.
     ///
     /// Complexity is `O(n)` where `n` is the length of the iterator.
-    /// For slices, prefer [`IndexedRandom::choose_multiple`].
-    fn choose_multiple_fill<R>(mut self, rng: &mut R, buf: &mut [Self::Item]) -> usize
+    /// For slices, prefer [`IndexedRandom::sample`].
+    fn sample_fill<R>(mut self, rng: &mut R, buf: &mut [Self::Item]) -> usize
     where
         R: Rng + ?Sized,
     {
@@ -224,7 +224,7 @@ pub trait IteratorRandom: Iterator + Sized {
 
     /// Uniformly sample `amount` distinct elements into a [`Vec`]
     ///
-    /// This is equivalent to `choose_multiple_fill` except for the result type.
+    /// This is equivalent to `sample_fill` except for the result type.
     ///
     /// Although the elements are selected randomly, the order of elements in
     /// the buffer is neither stable nor fully random. If random ordering is
@@ -235,9 +235,9 @@ pub trait IteratorRandom: Iterator + Sized {
     /// elements available.
     ///
     /// Complexity is `O(n)` where `n` is the length of the iterator.
-    /// For slices, prefer [`IndexedRandom::choose_multiple`].
+    /// For slices, prefer [`IndexedRandom::sample`].
     #[cfg(feature = "alloc")]
-    fn choose_multiple<R>(mut self, rng: &mut R, amount: usize) -> Vec<Self::Item>
+    fn sample<R>(mut self, rng: &mut R, amount: usize) -> Vec<Self::Item>
     where
         R: Rng + ?Sized,
     {
@@ -538,8 +538,8 @@ mod test {
 
         let mut r = crate::test::rng(401);
         let vals = (min_val..max_val).collect::<Vec<i32>>();
-        let small_sample = vals.iter().choose_multiple(&mut r, 5);
-        let large_sample = vals.iter().choose_multiple(&mut r, vals.len() + 5);
+        let small_sample = vals.iter().sample(&mut r, 5);
+        let large_sample = vals.iter().sample(&mut r, vals.len() + 5);
 
         assert_eq!(small_sample.len(), 5);
         assert_eq!(large_sample.len(), vals.len());
@@ -644,20 +644,17 @@ mod test {
     }
 
     #[test]
-    fn value_stability_choose_multiple() {
+    fn value_stability_sample() {
         fn do_test<I: Clone + Iterator<Item = u32>>(iter: I, v: &[u32]) {
             let mut rng = crate::test::rng(412);
             let mut buf = [0u32; 8];
-            assert_eq!(
-                iter.clone().choose_multiple_fill(&mut rng, &mut buf),
-                v.len()
-            );
+            assert_eq!(iter.clone().sample_fill(&mut rng, &mut buf), v.len());
             assert_eq!(&buf[0..v.len()], v);
 
             #[cfg(feature = "alloc")]
             {
                 let mut rng = crate::test::rng(412);
-                assert_eq!(iter.choose_multiple(&mut rng, v.len()), v);
+                assert_eq!(iter.sample(&mut rng, v.len()), v);
             }
         }