Rename fns choose_multiple* → sample*; add choose*_iter (#1632)

Author: dhardy

CHANGELOG.md

@@ -10,10 +10,12 @@ You may also find the [Upgrade Guide](https://rust-random.github.io/book/update.
 
 ## [0.10.0 — Unreleased]
 ### Changes
+- Rename fns `IndexedRandom::choose_multiple` -> `sample`, `choose_multiple_array` -> `sample_array`, `choose_multiple_weighted` -> `sample_weighted`, struct `SliceChooseIter` -> `IndexedSamples` and fns `IteratorRandom::choose_multiple` -> `sample`, `choose_multiple_fill` -> `sample_fill` (#1632)
 - Use Edition 2024 and MSRV 1.85 (#1653)
 - Let `Fill` be implemented for element types, not sliceable types (#1652)
 
 ### Additions
+- Add fns `IndexedRandom::choose_iter`, `choose_weighted_iter` (#1632)
 - Pub export `Xoshiro128PlusPlus`, `Xoshiro256PlusPlus` prngs (#1649)
 
 ## [0.9.2 — 2025-07-20]

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_{amount}_of_{len}");
+        let name = format!("seq_slice_sample_{amount}_of_{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_{amount}_of_{len}");
+        let name = format!("seq_slice_sample_weighted_{amount}_of_{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;
                 }
@@ -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

@@ -199,8 +199,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,
     {
@@ -228,7 +228,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
@@ -239,9 +239,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,
     {
@@ -266,6 +266,25 @@ pub trait IteratorRandom: Iterator + Sized {
         }
         reservoir
     }
+
+    /// Deprecated: use [`Self::sample_fill`] instead
+    #[deprecated(since = "0.9.2", note = "Renamed to `sample_fill`")]
+    fn choose_multiple_fill<R>(self, rng: &mut R, buf: &mut [Self::Item]) -> usize
+    where
+        R: Rng + ?Sized,
+    {
+        self.sample_fill(rng, buf)
+    }
+
+    /// Deprecated: use [`Self::sample`] instead
+    #[cfg(feature = "alloc")]
+    #[deprecated(since = "0.9.2", note = "Renamed to `sample`")]
+    fn choose_multiple<R>(self, rng: &mut R, amount: usize) -> Vec<Self::Item>
+    where
+        R: Rng + ?Sized,
+    {
+        self.sample(rng, amount)
+    }
 }
 
 impl<I> IteratorRandom for I where I: Iterator + Sized {}
@@ -542,8 +561,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());
@@ -650,20 +669,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);
             }
         }
 

src/seq/mod.rs

@@ -40,6 +40,9 @@ mod index_;
 pub use crate::distr::weighted::Error as WeightError;
 pub use iterator::IteratorRandom;
 #[cfg(feature = "alloc")]
+pub use slice::IndexedSamples;
+#[allow(deprecated)]
+#[cfg(feature = "alloc")]
 pub use slice::SliceChooseIter;
 pub use slice::{IndexedMutRandom, IndexedRandom, SliceRandom};