# slice.rs - source
Source of the Rust file `/home/key/.cargo/registry/src/github.com-1ecc6299db9ec823/rand-0.8.5/src/distributions/slice.rs`.
Keywords: rust, rustlang, rust-lang

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117

    // Copyright 2021 Developers of the Rand project.
    //
    // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
    // https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
    // <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
    // option. This file may not be copied, modified, or distributed
    // except according to those terms.

    use crate::distributions::{Distribution, Uniform};

    /// A distribution to sample items uniformly from a slice.
    ///
    /// [`Slice::new`] constructs a distribution referencing a slice and uniformly
    /// samples references from the items in the slice. It may do extra work up
    /// front to make sampling of multiple values faster; if only one sample from
    /// the slice is required, [`SliceRandom::choose`] can be more efficient.
    ///
    /// Steps are taken to avoid bias which might be present in naive
    /// implementations; for example `slice[rng.gen() % slice.len()]` samples from
    /// the slice, but may be more likely to select numbers in the low range than
    /// other values.
    ///
    /// This distribution samples with replacement; each sample is independent.
    /// Sampling without replacement requires state to be retained, and therefore
    /// cannot be handled by a distribution; you should instead consider methods
    /// on [`SliceRandom`], such as [`SliceRandom::choose_multiple`].
    ///
    /// # Example
    ///
    /// ```
    /// use rand::Rng;
    /// use rand::distributions::Slice;
    ///
    /// let vowels = ['a', 'e', 'i', 'o', 'u'];
    /// let vowels_dist = Slice::new(&vowels).unwrap();
    /// let rng = rand::thread_rng();
    ///
    /// // build a string of 10 vowels
    /// let vowel_string: String = rng
    ///     .sample_iter(&vowels_dist)
    ///     .take(10)
    ///     .collect();
    ///
    /// println!("{}", vowel_string);
    /// assert_eq!(vowel_string.len(), 10);
    /// assert!(vowel_string.chars().all(|c| vowels.contains(&c)));
    /// ```
    ///
    /// For a single sample, [`SliceRandom::choose`][crate::seq::SliceRandom::choose]
    /// may be preferred:
    ///
    /// ```
    /// use rand::seq::SliceRandom;
    ///
    /// let vowels = ['a', 'e', 'i', 'o', 'u'];
    /// let mut rng = rand::thread_rng();
    ///
    /// println!("{}", vowels.choose(&mut rng).unwrap())
    /// ```
    ///
    /// [`SliceRandom`]: crate::seq::SliceRandom
    /// [`SliceRandom::choose`]: crate::seq::SliceRandom::choose
    /// [`SliceRandom::choose_multiple`]: crate::seq::SliceRandom::choose_multiple
    #[derive(Debug, Clone, Copy)]
    pub struct Slice<'a, T> {
        slice: &'a [T],
        range: Uniform<usize>,
    }

    impl<'a, T> Slice<'a, T> {
        /// Create a new `Slice` instance which samples uniformly from the slice.
        /// Returns `Err` if the slice is empty.
        pub fn new(slice: &'a [T]) -> Result<Self, EmptySlice> {
            match slice.len() {
                0 => Err(EmptySlice),
                len => Ok(Self {
                    slice,
                    range: Uniform::new(0, len),
                }),
            }
        }
    }

    impl<'a, T> Distribution<&'a T> for Slice<'a, T> {
        fn sample<R: crate::Rng + ?Sized>(&self, rng: &mut R) -> &'a T {
            let idx = self.range.sample(rng);

            debug_assert!(
                idx < self.slice.len(),
                "Uniform::new(0, {}) somehow returned {}",
                self.slice.len(),
                idx
            );

            // Safety: at construction time, it was ensured that the slice was
            // non-empty, and that the `Uniform` range produces values in range
            // for the slice
            unsafe { self.slice.get_unchecked(idx) }
        }
    }

    /// Error type indicating that a [`Slice`] distribution was improperly
    /// constructed with an empty slice.
    #[derive(Debug, Clone, Copy)]
    pub struct EmptySlice;

    impl core::fmt::Display for EmptySlice {
        fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
            write!(
                f,
                "Tried to create a `distributions::Slice` with an empty slice"
            )
        }
    }

    #[cfg(feature = "std")]
    impl std::error::Error for EmptySlice {}