reservoir_sampling/
lib.rs

1#[cfg(feature = "unweighted")]
2pub mod unweighted {
3    pub mod core;
4
5    use rand::thread_rng;
6    
7    /// An implementation of Algorithm `L` (https://en.wikipedia.org/wiki/Reservoir_sampling#An_optimal_algorithm)
8    /// # Parameters:
9    /// - Type implementing `std::iter::Iterator` as *source*,
10    /// - Mutable array slice (i.e. `&mut [T]`) as *sample array (i.e. where sampled data is stored)*
11    /// # Notes:
12    /// - In case iterator yields less than sample amount, sample will be filled as much as possible, and returned.
13    /// - This uses `rand::thread_rng` to provide RNG. To use your own RNG which implements `rand::RNG`, see `reservoir_sampling::core`
14    
15    pub fn l <I, T>(stream: I, sample: &mut [T])
16    where
17        I: Iterator<Item=T>,
18    {
19        let mut rng = thread_rng();
20        core::l(stream, sample, &mut rng);
21    }
22
23    /// An implementation of algorithm `R` (https://en.wikipedia.org/wiki/Reservoir_sampling#Simple_algorithm)
24    /// # Parameters:
25    /// - Type implementing `std::iter::Iterator` as *source*,
26    /// - Mutable array slice (i.e. `&mut [T]`) as *sample array (i.e. where sampled data is stored)*
27    /// - Type implementing `rand::Rng` for random number generation.
28    /// In case iterator yields less than sample amount, sample will be filled as much as possible, and returned.
29
30    pub fn r <I, T>(stream: I, sample: &mut [T])
31    where
32        I: Iterator<Item=T>,
33    {
34        let mut rng = thread_rng();
35        core::r(stream, sample, &mut rng);
36    }
37}
38
39#[cfg(feature = "weighted")]
40pub mod weighted {
41    /*!
42    Provides weighted reservoir sampling, i.e. the
43    odds of a particular item occurring in the sampling
44    can be influenced.
45
46    Odds can be influenced via the `WeightedItem` struct,
47    which is a wrapper struct around your item and 
48    an associated weight which controls the frequency
49    of the item occurring in the resulting sampling.
50
51    The functions in this module take an iterator of `WeightedItem`,
52    so remember to wrap your types in that struct and then pass an iterator of them.
53    */
54
55    pub mod core;
56
57    use rand::thread_rng;
58    use self::core::WeightedItem;
59
60    /// An implementation of Algorithm `A-Res` (https://en.wikipedia.org/wiki/Reservoir_sampling#Algorithm_A-Res)
61    /// # Parameters:
62    /// - Iterator of `core::WeightedItem` as *source*,
63    /// - `sample_len`, the size of the sampled reservoir.
64    /// Returns a `Vec` of length `sample_len`
65    /// In case iterator yields less than sample amount, sample will be filled as much as possible, and returned.
66
67    pub fn a_res <I, T> (stream: I, sample_len: usize) -> Vec<T>
68    where
69        I: Iterator<Item=WeightedItem<T>>
70    {
71        let mut rng = thread_rng();
72        core::a_res(stream, sample_len, &mut rng)
73    }
74}
reservoir_sampling/lib.rs

reservoir_sampling/
lib.rs
