rng-pack 0.2.5

use crate::rng32::Rng32;
/// A Twisted Generalized Feedback Shift Register (TGFSR) generator.
///
/// # Examples
///
/// ```
/// use rng_pack::twisted_gfsr::TwistedGFSR;
///
/// let seed = TwistedGFSR::new_seed();
/// let mut rng = TwistedGFSR::new(seed);
/// let val = rng.nextf();
/// ```
#[repr(C)]
pub struct TwistedGFSR {
    seed: [u64; N],
    index: usize,
}

const N: usize = 25;
const M: usize = 7;

impl TwistedGFSR {
    /// Provides a default seed array.
    pub const fn new_seed() -> [u64; N] {
        [
            0x95f24dab, 0x0b685215, 0xe76ccae7, 0xaf3ec239, 0x715fad23, 0x24a590ad, 0x69e4b5ef,
            0xbf456141, 0x96bc1b7b, 0xa7bdf825, 0xc1de75b7, 0x8858a9c9, 0x2da87693, 0xb657f9dd,
            0xffdc8a9f, 0x8121da71, 0x8b823ecb, 0x885d05f5, 0x4e20cd47, 0x5a9ad5d9, 0x512c0c03,
            0xea857ccd, 0x4cc1d30f, 0x8891a8a1, 0xa6b7aadb,
        ]
    }

    const fn mag01() -> [u64; 2] {
        [0x0, 0x8ebfd028]
    }

    /// Creates a new `TwistedGFSR` instance.
    ///
    /// # Arguments
    ///
    /// * `seed` - The initial state array.
    pub fn new(seed: [u64; N]) -> Self {
        Self { seed, index: N }
    }

    fn twist(&mut self) {
        for k in 0..(N - M) {
            self.seed[k] =
                self.seed[k + M] ^ (self.seed[k] >> 1) ^ Self::mag01()[(self.seed[k] & 1) as usize];
        }
        for k in (N - M)..N {
            self.seed[k] = self.seed[k + M - N]
                ^ (self.seed[k] >> 1)
                ^ Self::mag01()[(self.seed[k] & 1) as usize];
        }
        self.index = 0;
    }

    /// Generates the next random `u32` value.
    ///
    /// # Examples
    ///
    /// ```
    /// use rng_pack::twisted_gfsr::TwistedGFSR;
    ///
    /// let mut rng = TwistedGFSR::new(TwistedGFSR::new_seed());
    /// let val = rng.nextu();
    /// ```
    #[inline]
    pub fn nextu(&mut self) -> u32 {
        if self.index >= N {
            self.twist();
        }

        let mut y = self.seed[self.index];
        y ^= (y << 7) & 0x2b5b2500;
        y ^= (y << 15) & 0xdb8b0000;
        y &= 0xffffffff;
        y ^= y >> 16;

        self.index += 1;

        y as u32
    }

    /// Generates the next random `f64` value in the range [0, 1).
    ///
    /// # Examples
    ///
    /// ```
    /// use rng_pack::twisted_gfsr::TwistedGFSR;
    ///
    /// let mut rng = TwistedGFSR::new(TwistedGFSR::new_seed());
    /// let val = rng.nextf();
    /// assert!(val >= 0.0 && val < 1.0);
    /// ```
    #[inline]
    pub fn nextf(&mut self) -> f64 {
        self.nextu() as f64 * (1.0 / 4294967296.0)
    }

    /// Generates a random `i32` value in the range [min, max].
    ///
    /// # Arguments
    ///
    /// * `min` - The lower bound (inclusive).
    /// * `max` - The upper bound (inclusive).
    ///
    /// # Examples
    ///
    /// ```
    /// use rng_pack::twisted_gfsr::TwistedGFSR;
    ///
    /// let mut rng = TwistedGFSR::new(TwistedGFSR::new_seed());
    /// let val = rng.randi(1, 10);
    /// assert!(val >= 1 && val <= 10);
    /// ```
    #[inline]
    pub fn randi(&mut self, min: i32, max: i32) -> i32 {
        let range = (max as i64 - min as i64 + 1) as u64;
        let x = self.nextu();
        ((x as u64 * range) >> 32) as i32 + min
    }

    /// Generates a random `f64` value in the range [min, max).
    ///
    /// # Arguments
    ///
    /// * `min` - The lower bound (inclusive).
    /// * `max` - The upper bound (exclusive).
    ///
    /// # Examples
    ///
    /// ```
    /// use rng_pack::twisted_gfsr::TwistedGFSR;
    ///
    /// let mut rng = TwistedGFSR::new(TwistedGFSR::new_seed());
    /// let val = rng.randf(1.0, 10.0);
    /// assert!(val >= 1.0 && val < 10.0);
    /// ```
    #[inline]
    pub fn randf(&mut self, min: f64, max: f64) -> f64 {
        let range = max - min;
        self.nextf() * range + min
    }

    /// Returns a random element from a slice.
    ///
    /// # Arguments
    ///
    /// * `choices` - The slice to choose from.
    ///
    /// # Examples
    ///
    /// ```
    /// use rng_pack::twisted_gfsr::TwistedGFSR;
    ///
    /// let mut rng = TwistedGFSR::new(TwistedGFSR::new_seed());
    /// let choices = [1, 2, 3, 4, 5];
    /// let val = rng.choice(&choices);
    /// assert!(choices.contains(val));
    /// ```
    #[inline]
    pub fn choice<'a, T>(&mut self, choices: &'a [T]) -> &'a T {
        let index = self.randi(0, choices.len() as i32 - 1);
        &choices[index as usize]
    }
}

impl Rng32 for TwistedGFSR {
    #[inline]
    fn randi(&mut self, min: i32, max: i32) -> i32 {
        self.randi(min, max)
    }

    #[inline]
    fn randf(&mut self, min: f32, max: f32) -> f32 {
        self.randf(min as f64, max as f64) as f32
    }

    #[inline]
    fn choice<'a, T>(&'a mut self, choices: &'a [T]) -> &'a T {
        self.choice(choices)
    }
}

#[cfg(test)]
mod tests {
    use crate::twisted_gfsr::TwistedGFSR;

    #[test]
    fn it_works() {
        let mut rng = TwistedGFSR::new(TwistedGFSR::new_seed());

        assert_eq!(rng.nextu(), 868393086);
        assert_eq!(rng.nextf(), 0.33567164628766477);
        assert_eq!(rng.randi(10, 20), 12);
        assert_eq!(rng.randf(10.0, 20.0), 14.423478092066944);
        assert_eq!(*rng.choice(&[0, 1, 2, 3, 4]), 4);
        assert_eq!(*rng.choice(&[1, 2, 3, 4, 5]), 3);
        assert_eq!(*rng.choice(&[2, 3, 4, 5, 6]), 5);
        assert_eq!(*rng.choice(&[3, 4, 5, 6, 7]), 4);
    }
}