pure_rng/

lib.rs

//! PureRng is a [`rand`](https://crates.io/crates/rand)-compatible RNG library
//! for generating repeatable, controlled random values, designed primarily for
//! use in games. It uses a hash function to generate exactly one random value
//! per seed. A convenient API is provided to distribute seed values throughout
//! your program in a hierarchical fashion.
//!
//! # Usage
//!
//! ```rust
//! use pure_rng::prelude::*;
//!
//! // Create the root rng using an initial seed, typically from an external source.
//! let rng = PureRng::new(1234);
//!
//! // Seed two more RNGs with arbitrary labels.
//! // These effectively have their seed appended to that of the parent.
//! let rng_a = rng.seed("a convenient label");
//! let rng_b = rng.seed("a different label");
//!
//! // Generate a value from the first RNG, consuming it.
//! let value_a: u32 = rng_a.random();
//!
//! // Create two more forks of the second RNG, and generate values from them inline.
//! let value_b1: i64 = rng_b.seed(1).random();
//! let value_b2: f64 = rng_b.seed(2).random();
//!
//! // Use your custom types
//! #[derive(Hash)]
//! struct Point { x: i32, y: i32 }
//!
//! let value_from_point: u64 = rng
//!     .seed(Point { x: 10, y: 12 })
//!     .random();
//!
//! // Use the all the usual `rand` API features
//! let character = rng
//!     .seed("character")
//!     .sample(rand::distr::Alphanumeric) as char;
//! ```
//!
//! For more information see the README, the
//! [accompanying blog post](https://jcd.pub/2025/03/14/pure-rng/), and the examples
pub mod prelude;
mod rng_core;
pub mod seq;

use rand::distr::uniform::SampleRange;
use rand::distr::uniform::SampleUniform;
use rand::distr::Distribution;
use rand::distr::StandardUniform;
use rand::Fill;
use rand::Rng;
use std::hash::{Hash, Hasher};

/// Default generator using Rapidhash
#[cfg(feature = "rapidhash")]
pub type PureRng = PureRandomGenerator<rapidhash::RapidHasher>;

/// Generic RNG type over any Hasher
///
/// Typically you would use [`PureRng`] for the default Rapidhash algorithm, or
/// redefine that alias with your choice of hasher, rather than using this type
/// directly.
#[derive(Debug, Copy, Clone, Default, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct PureRandomGenerator<H>
where
    H: Hasher + Default + Clone,
{
    hasher: H,
}

impl<H> PureRandomGenerator<H>
where
    H: Hasher + Default + Clone,
{
    /// Creates a new generator with the given hashable value as the seed. In a
    /// game this might be the world seed, or just the system time etc.
    ///
    /// # Examples
    ///
    /// ```
    /// use pure_rng::PureRng;
    ///
    /// let rng = PureRng::new("initial seed");
    /// ```
    pub fn new(hashable: impl Hash) -> Self {
        Self::default().seed(hashable)
    }

    /// Forks the generator, and advances the fork's state by hashing the given
    /// value.
    ///
    /// This is the core of the API - sometimes called "splitting" or "forking"
    /// an RNG. The difference is that with PureRng you split every time you
    /// generate a new value.
    ///  
    /// # Examples
    ///
    /// ```
    /// use pure_rng::PureRng;
    ///
    /// let rng = PureRng::new("initial seed");
    /// let sub_rng = rng.seed("a convenient label to differentiate");
    /// let ten_values: Vec<u64> = (0..10).map(|i| sub_rng.seed(i).random()).collect();
    ///
    /// #[derive(Hash)]
    /// struct Point { x: i32, y: i32 }
    ///
    /// let value_from_point: u64 = rng
    ///     .seed(Point { x: 10, y: 12 })
    ///     .random();
    /// ```
    ///
    /// More usage example in the readme, and in `examples/complex.rs`
    #[inline]
    pub fn seed(&self, hashable: impl Hash) -> Self {
        let mut fork = self.clone();
        hashable.hash(&mut fork.hasher);

        fork
    }
}
/// Wrappers for the [`Rng`] trait functions.
impl<H> PureRandomGenerator<H>
where
    H: Hasher + Default + Clone,
{
    /// Return a random value via the [`StandardUniform`] distribution.
    ///
    /// See [`Rng::random`].
    ///
    /// [`StandardUniform`]: rand::distr::StandardUniform
    #[inline]
    pub fn random<T>(mut self) -> T
    where
        StandardUniform: Distribution<T>,
    {
        Rng::random(&mut self)
    }

    /// Generate a random value in the given range.
    ///
    /// See [`Rng::random_range`].
    #[track_caller]
    pub fn random_range<T, Q>(mut self, range: Q) -> T
    where
        T: SampleUniform,
        Q: SampleRange<T>,
    {
        Rng::random_range(&mut self, range)
    }

    /// Sample a new value, using the given distribution.
    ///
    /// See [`Rng::sample`].
    pub fn sample<T, D: Distribution<T>>(mut self, distr: D) -> T {
        Rng::sample(&mut self, distr)
    }

    /// Create an iterator that generates values using the given distribution.
    ///
    /// See [`Rng::sample_iter`].
    pub fn sample_iter<T, D>(self, distr: D) -> rand::distr::Iter<D, Self, T>
    where
        D: Distribution<T>,
        Self: Sized,
    {
        Rng::sample_iter(self, distr)
    }

    /// Fill any type implementing [`Fill`] with random data.
    ///
    /// See [`Rng::fill`].
    #[track_caller]
    pub fn fill<T: Fill + ?Sized>(mut self, dest: &mut T) {
        Rng::fill(&mut self, dest)
    }

    /// Return a bool with a probability `p` of being true.
    ///
    /// See [`Rng::random_bool`].
    #[inline]
    #[track_caller]
    pub fn random_bool(mut self, p: f64) -> bool {
        Rng::random_bool(&mut self, p)
    }

    /// Return a bool with a probability of `numerator/denominator` of being
    /// true.
    ///
    /// See [`Rng::random_ratio`].
    #[inline]
    #[track_caller]
    pub fn random_ratio(mut self, numerator: u32, denominator: u32) -> bool {
        Rng::random_ratio(&mut self, numerator, denominator)
    }
}

#[cfg(test)]
pub(crate) mod tests {
    use crate::PureRng;

    #[test]
    fn test_repeatable() {
        let rng = PureRng::default();

        let val_1: u64 = rng.seed("lol").random();
        let val_2: u64 = rng.seed("lol").random();
        assert_eq!(val_1, val_2);

        let rng_2 = rng.seed("foo");

        let val_3: u64 = rng_2.seed("lol").random();
        let val_4: u64 = rng_2.seed("lol").random();
        assert_eq!(val_3, val_4);

        assert_ne!(val_1, val_3);

        let rng_3 = rng_2.seed("bar");

        let val_5: u64 = rng_3.seed("lol").random();
        let val_6: u64 = rng_3.seed("lol").random();
        assert_eq!(val_5, val_6);

        assert_ne!(val_3, val_5);
        assert_ne!(val_2, val_5);
    }
}