Rename fns IndexedRandom::choose_multiple* -> sample*

Author: dhardy

benches/benches/seq_choose.rs

@@ -30,7 +30,7 @@ pub fn bench(c: &mut Criterion) {
 
     let lens = [(1, 1000), (950, 1000), (10, 100), (90, 100)];
     for (amount, len) in lens {
-        let name = format!("seq_slice_choose_multiple_{}_of_{}", amount, len);
+        let name = format!("seq_slice_sample_{}_of_{}", amount, len);
         c.bench_function(name.as_str(), |b| {
             let mut rng = Pcg32::from_rng(&mut rand::rng());
             let mut buf = [0i32; 1000];
@@ -44,7 +44,7 @@ pub fn bench(c: &mut Criterion) {
             b.iter(|| {
                 // Collect full result to prevent unwanted shortcuts getting
                 // first element (in case sample_indices returns an iterator).
-                for (slot, sample) in y.iter_mut().zip(x.choose_multiple(&mut rng, amount)) {
+                for (slot, sample) in y.iter_mut().zip(x.sample(&mut rng, amount)) {
                     *slot = *sample;
                 }
                 y[amount - 1]
@@ -54,7 +54,7 @@ pub fn bench(c: &mut Criterion) {
 
     let lens = [(1, 1000), (950, 1000), (10, 100), (90, 100)];
     for (amount, len) in lens {
-        let name = format!("seq_slice_choose_multiple_weighted_{}_of_{}", amount, len);
+        let name = format!("seq_slice_sample_weighted_{}_of_{}", amount, len);
         c.bench_function(name.as_str(), |b| {
             let mut rng = Pcg32::from_rng(&mut rand::rng());
             let mut buf = [0i32; 1000];
@@ -68,7 +68,7 @@ pub fn bench(c: &mut Criterion) {
             b.iter(|| {
                 // Collect full result to prevent unwanted shortcuts getting
                 // first element (in case sample_indices returns an iterator).
-                let samples_iter = x.choose_multiple_weighted(&mut rng, amount, |_| 1.0).unwrap();
+                let samples_iter = x.sample_weighted(&mut rng, amount, |_| 1.0).unwrap();
                 for (slot, sample) in y.iter_mut().zip(samples_iter) {
                     *slot = *sample;
                 }

src/seq/slice.rs

@@ -78,16 +78,16 @@ pub trait IndexedRandom: Index<usize> {
     /// let sample = "Hello, audience!".as_bytes();
     ///
     /// // collect the results into a vector:
-    /// let v: Vec<u8> = sample.choose_multiple(&mut rng, 3).cloned().collect();
+    /// let v: Vec<u8> = sample.sample(&mut rng, 3).cloned().collect();
     ///
     /// // store in a buffer:
     /// let mut buf = [0u8; 5];
-    /// for (b, slot) in sample.choose_multiple(&mut rng, buf.len()).zip(buf.iter_mut()) {
+    /// for (b, slot) in sample.sample(&mut rng, buf.len()).zip(buf.iter_mut()) {
     ///     *slot = *b;
     /// }
     /// ```
     #[cfg(feature = "alloc")]
-    fn choose_multiple<R>(&self, rng: &mut R, amount: usize) -> SliceChooseIter<Self, Self::Output>
+    fn sample<R>(&self, rng: &mut R, amount: usize) -> SliceChooseIter<Self, Self::Output>
     where
         Self::Output: Sized,
         R: Rng + ?Sized,
@@ -114,9 +114,9 @@ pub trait IndexedRandom: Index<usize> {
     /// let mut rng = &mut rand::rng();
     /// let sample = "Hello, audience!".as_bytes();
     ///
-    /// let a: [u8; 3] = sample.choose_multiple_array(&mut rng).unwrap();
+    /// let a: [u8; 3] = sample.sample_array(&mut rng).unwrap();
     /// ```
-    fn choose_multiple_array<R, const N: usize>(&self, rng: &mut R) -> Option<[Self::Output; N]>
+    fn sample_array<R, const N: usize>(&self, rng: &mut R) -> Option<[Self::Output; N]>
     where
         Self::Output: Clone + Sized,
         R: Rng + ?Sized,
@@ -173,7 +173,7 @@ pub trait IndexedRandom: Index<usize> {
 
     /// Biased sampling of `amount` distinct elements
     ///
-    /// Similar to [`choose_multiple`], but where the likelihood of each
+    /// Similar to [`sample`], but where the likelihood of each
     /// element's inclusion in the output may be specified. Zero-weighted
     /// elements are never returned; the result may therefore contain fewer
     /// elements than `amount` even when `self.len() >= amount`. The elements
@@ -198,13 +198,13 @@ pub trait IndexedRandom: Index<usize> {
     /// // (50% * 50%) + (25% * 67%) = 41.7% chance that the output is `['a', 'b']` in some order.
     /// // (50% * 50%) + (25% * 67%) = 41.7% chance that the output is `['a', 'c']` in some order.
     /// // (25% * 33%) + (25% * 33%) = 16.6% chance that the output is `['b', 'c']` in some order.
-    /// println!("{:?}", choices.choose_multiple_weighted(&mut rng, 2, |item| item.1).unwrap().collect::<Vec<_>>());
+    /// println!("{:?}", choices.sample_weighted(&mut rng, 2, |item| item.1).unwrap().collect::<Vec<_>>());
     /// ```
-    /// [`choose_multiple`]: IndexedRandom::choose_multiple
+    /// [`sample`]: IndexedRandom::sample
     // Note: this is feature-gated on std due to usage of f64::powf.
     // If necessary, we may use alloc+libm as an alternative (see PR #1089).
     #[cfg(feature = "std")]
-    fn choose_multiple_weighted<R, F, X>(
+    fn sample_weighted<R, F, X>(
         &self,
         rng: &mut R,
         amount: usize,
@@ -412,7 +412,7 @@ impl<T> SliceRandom for [T] {
 /// An iterator over multiple slice elements.
 ///
 /// This struct is created by
-/// [`IndexedRandom::choose_multiple`](trait.IndexedRandom.html#tymethod.choose_multiple).
+/// [`IndexedRandom::sample`](trait.IndexedRandom.html#tymethod.sample).
 #[cfg(feature = "alloc")]
 #[derive(Debug)]
 pub struct SliceChooseIter<'a, S: ?Sized + 'a, T: 'a> {
@@ -492,16 +492,13 @@ mod test {
         assert_eq!(nums.choose_mut(&mut r), Some(&mut 3));
 
         assert_eq!(
-            &chars.choose_multiple_array(&mut r),
+            &chars.sample_array(&mut r),
             &Some(['f', 'i', 'd', 'b', 'c', 'm', 'j', 'k'])
         );
 
         #[cfg(feature = "alloc")]
         assert_eq!(
-            &chars
-                .choose_multiple(&mut r, 8)
-                .cloned()
-                .collect::<Vec<char>>(),
+            &chars.sample(&mut r, 8).cloned().collect::<Vec<char>>(),
             &['h', 'm', 'd', 'b', 'c', 'e', 'n', 'f']
         );
 
@@ -668,7 +665,7 @@ mod test {
         let choices = [('a', 2), ('b', 1), ('c', 0)];
         for _ in 0..100 {
             let result = choices
-                .choose_multiple_weighted(&mut rng, 2, |item| item.1)
+                .sample_weighted(&mut rng, 2, |item| item.1)
                 .unwrap()
                 .collect::<Vec<_>>();
 
@@ -678,29 +675,29 @@ mod test {
 
         // Case 2: All of the weights are 0
         let choices = [('a', 0), ('b', 0), ('c', 0)];
-        let r = choices.choose_multiple_weighted(&mut rng, 2, |item| item.1);
+        let r = choices.sample_weighted(&mut rng, 2, |item| item.1);
         assert_eq!(r.unwrap().len(), 0);
 
         // Case 3: Negative weights
         let choices = [('a', -1), ('b', 1), ('c', 1)];
-        let r = choices.choose_multiple_weighted(&mut rng, 2, |item| item.1);
+        let r = choices.sample_weighted(&mut rng, 2, |item| item.1);
         assert_eq!(r.unwrap_err(), WeightError::InvalidWeight);
 
         // Case 4: Empty list
         let choices = [];
-        let r = choices.choose_multiple_weighted(&mut rng, 0, |_: &()| 0);
+        let r = choices.sample_weighted(&mut rng, 0, |_: &()| 0);
         assert_eq!(r.unwrap().count(), 0);
 
         // Case 5: NaN weights
         let choices = [('a', f64::NAN), ('b', 1.0), ('c', 1.0)];
-        let r = choices.choose_multiple_weighted(&mut rng, 2, |item| item.1);
+        let r = choices.sample_weighted(&mut rng, 2, |item| item.1);
         assert_eq!(r.unwrap_err(), WeightError::InvalidWeight);
 
         // Case 6: +infinity weights
         let choices = [('a', f64::INFINITY), ('b', 1.0), ('c', 1.0)];
         for _ in 0..100 {
             let result = choices
-                .choose_multiple_weighted(&mut rng, 2, |item| item.1)
+                .sample_weighted(&mut rng, 2, |item| item.1)
                 .unwrap()
                 .collect::<Vec<_>>();
             assert_eq!(result.len(), 2);
@@ -709,12 +706,12 @@ mod test {
 
         // Case 7: -infinity weights
         let choices = [('a', f64::NEG_INFINITY), ('b', 1.0), ('c', 1.0)];
-        let r = choices.choose_multiple_weighted(&mut rng, 2, |item| item.1);
+        let r = choices.sample_weighted(&mut rng, 2, |item| item.1);
         assert_eq!(r.unwrap_err(), WeightError::InvalidWeight);
 
         // Case 8: -0 weights
         let choices = [('a', -0.0), ('b', 1.0), ('c', 1.0)];
-        let r = choices.choose_multiple_weighted(&mut rng, 2, |item| item.1);
+        let r = choices.sample_weighted(&mut rng, 2, |item| item.1);
         assert!(r.is_ok());
     }
 
@@ -737,7 +734,7 @@ mod test {
         let expected_results = [5833, 2667, 1500];
         for _ in 0..10000 {
             let result = choices
-                .choose_multiple_weighted(&mut rng, 2, |item| item.1)
+                .sample_weighted(&mut rng, 2, |item| item.1)
                 .unwrap()
                 .collect::<Vec<_>>();