xoroshiro256_full/

lib.rs

#![forbid(unsafe_code)]
#![deny(clippy::all, clippy::cargo)]
#![warn(clippy::pedantic, clippy::nursery)]
#![allow(
    clippy::module_name_repetitions,
    clippy::doc_markdown,
    clippy::missing_panics_doc
)]
#![doc = r#"
# xoroshiro256** PRNG (fast, non-cryptographic)

A tiny, fast implementation of **xoroshiro256** without bit waste, intended for simulations,
 games, and other **deterministic** workloads. This generator is **not
cryptographically secure**. If you need CSPRNG, enable the `"crypto"`
feature and use `CryptoRng256` (ChaCha20).

## Features

- `rand_core` — implements `rand_core::RngCore` and `SeedableRng`.
- `serde` — enables `Serialize`/`Deserialize` for `Xoroshiro256State`.
- `crypto` — provides `CryptoRng256` (ChaCha20) for cryptographic use.

## Examples

### Fast deterministic numbers (no features required)
```rust
use xoroshiro256_full::Xoroshiro256State;

let mut rng = Xoroshiro256State::init([1, 2, 3, 4], 4);
let x = rng.next_u64(); // fast, deterministic
```

### Integrate with `rand` ecosystem (enable `rand_core`)
```rust
# #[cfg(feature="rand_core")] {
use rand_core::{RngCore, SeedableRng};
use xoroshiro256_full::Xoroshiro256State;

let mut rng = Xoroshiro256State::seed_from_u64(42);
let _ = rng.next_u32();
# }
```

### Cryptographically secure RNG (enable `crypto`)
```rust
# #[cfg(feature="crypto")] {
use xoroshiro256_full::CryptoRng256;

let mut crng = CryptoRng256::from_os();
let x = crng.next_u64();
# }
```

## Notes

- This crate uses **wrapping arithmetic** to match the original reference.
- Endianness: byte conversions use **little-endian** (`to_le_bytes`).

### No bit waste (implementation detail)
When the `rand_core` feature is enabled, this implementation avoids bit waste in two places:

- `next_u32()` caches the unused 32 bits from a generated `u64` and returns them on the next call.
- `fill_bytes()` caches any unused tail bytes (up to 7) from a generated `u64` and uses them at the start of the next call.

These caches are **not** part of the algorithmic state and are skipped during `serde` serialization; only the 256-bit xoroshiro state is serialized.

"#]

#[cfg(feature = "rand_core")]
use rand_core::{Error, RngCore, SeedableRng};

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

/// Internal state for xoroshiro256** (4 × 64-bit words).
///
/// This type is **not cryptographically secure**. See [`crypto_rng::CryptoRng256`] with the
/// `"crypto"` feature for secure randomness.
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[derive(Clone, Copy, Debug)]
pub struct Xoroshiro256State {
    parts: [u64; 4],

    // --- Bit-waste-avoidance caches (only when rand_core is enabled) ---
    // These are skipped in serde so externalized state remains the 256-bit core only.
    #[cfg(feature = "rand_core")]
    #[cfg_attr(feature = "serde", serde(skip))]
    u32_spare: Option<u32>,
    #[cfg(feature = "rand_core")]
    #[cfg_attr(feature = "serde", serde(skip))]
    byte_spare: [u8; 8],
    #[cfg(feature = "rand_core")]
    #[cfg_attr(feature = "serde", serde(skip))]
    byte_spare_len: u8,
}

impl Default for Xoroshiro256State {
    #[inline]
    fn default() -> Self {
        Self {
            parts: [0; 4],
            #[cfg(feature = "rand_core")]
            u32_spare: None,
            #[cfg(feature = "rand_core")]
            byte_spare: [0; 8],
            #[cfg(feature = "rand_core")]
            byte_spare_len: 0,
        }
    }
}

impl Xoroshiro256State {
    /// Initialize with up to **4×64-bit** seeds.
    ///
    /// - `key_length` must be in `1..=4`.
    /// - If fewer than 4 keys are provided, remaining words are derived via a
    ///   simple **LCG** step to avoid trivially weak all-zero tails.
    /// - If the resulting state is all zeros, we force a non-zero constant in
    ///   `parts[0]`.
    ///
    /// # Panics
    /// Panics if `key_length` is not in `1..=4`.
    ///
    /// # Examples
    /// ```
    /// # use xoroshiro256_full::Xoroshiro256State;
    /// let mut rng = Xoroshiro256State::init([1,2,3,4], 4);
    /// let _ = rng.next_u64();
    /// ```
    #[must_use]
    pub fn init(init_key: [u64; 4], key_length: usize) -> Self {
        assert!((1..=4).contains(&key_length), "key_length must be 1..=4");

        let mut state = Self::default();
        let mut last = 0u64;
        for (i, slot) in state.parts.iter_mut().enumerate() {
            let val = if i < key_length {
                init_key[i]
            } else {
                // LCG step: wraps on overflow (matches C semantics)
                last.wrapping_mul(6_364_136_223_846_793_005_u64)
                    .wrapping_add(1)
            };
            *slot = val;
            last = val;
        }

        // Avoid the forbidden all-zero state (degenerate).
        if state.parts.iter().all(|&p| p == 0) {
            state.parts[0] = 0x9E37_79B9_7F4A_7C15; // golden-ratio-ish odd constant
        }

        state
    }

    #[inline]
    const fn rotl(x: u64, k: u32) -> u64 {
        x.rotate_left(k)
    }

    /// One step of xoroshiro256** → returns a **64-bit** output.
    ///
    /// This is the fast, non-crypto output function.
    #[inline]
    pub const fn next_u64(&mut self) -> u64 {
        // starstar output function
        let result = Self::rotl(self.parts[1].wrapping_mul(5), 7).wrapping_mul(9);
        let t = self.parts[1] << 17;

        self.parts[2] ^= self.parts[0];
        self.parts[3] ^= self.parts[1];
        self.parts[1] ^= self.parts[2];
        self.parts[0] ^= self.parts[3];

        self.parts[2] ^= t;
        self.parts[3] = Self::rotl(self.parts[3], 45);

        result
    }

    /// Write the **current** internal 256-bit state into `buf` (little-endian).
    ///
    /// Does **not** advance the PRNG state; it just exposes the current state.
    ///
    /// # Panics
    /// Panics if `buf.len() < 32`.
    #[inline]
    pub fn genrand_uint256_to_buf(&self, buf: &mut [u8]) {
        assert!(buf.len() >= 32, "Buffer must have at least 32 bytes");
        for (i, &x) in self.parts.iter().enumerate() {
            buf[i * 8..(i + 1) * 8].copy_from_slice(&x.to_le_bytes());
        }
    }
}

/* --------------------------- rand_core integration -------------------------- */

#[cfg(feature = "rand_core")]
impl RngCore for Xoroshiro256State {
    #[inline]
    fn next_u32(&mut self) -> u32 {
        // Use cached low 32 if available; otherwise generate once and split.
        if let Some(lo) = self.u32_spare.take() {
            return lo;
        }
        let x = self.next_u64();
        let hi = (x >> 32) as u32;
        let lo = (x & 0xFFFF_FFFF) as u32;
        self.u32_spare = Some(lo);
        hi
    }

    #[inline]
    fn next_u64(&mut self) -> u64 {
        Self::next_u64(self)
    }

    fn fill_bytes(&mut self, dest: &mut [u8]) {
        let mut written = 0;

        // 1) consume spare bytes from previous call
        if self.byte_spare_len > 0 {
            let n = self.byte_spare_len as usize;
            let take = n.min(dest.len());
            dest[..take].copy_from_slice(&self.byte_spare[..take]);
            if take < n {
                // shift remaining spare down
                self.byte_spare.copy_within(take..n, 0);
                self.byte_spare_len = u8::try_from(n - take).expect("spare len <= 8");
                return; // dest satisfied entirely from spare
            }
            self.byte_spare_len = 0;
            written += take;
        }

        // 2) write as many full u64s as possible
        let mut chunks = dest[written..].chunks_exact_mut(8);
        for chunk in &mut chunks {
            chunk.copy_from_slice(&self.next_u64().to_le_bytes());
        }

        // 3) handle tail and cache leftover
        let rem = chunks.into_remainder();
        if !rem.is_empty() {
            let r = self.next_u64().to_le_bytes();
            let need = rem.len();
            rem.copy_from_slice(&r[..need]);
            let leftover = 8 - need;
            if leftover > 0 {
                self.byte_spare[..leftover].copy_from_slice(&r[need..]);
                self.byte_spare_len = u8::try_from(leftover).expect("leftover <= 8");
            }
        }
    }

    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
        self.fill_bytes(dest);
        Ok(())
    }
}

#[cfg(feature = "rand_core")]
impl SeedableRng for Xoroshiro256State {
    type Seed = [u8; 32];

    /// Seeds from a 32-byte array (little-endian chunks).
    fn from_seed(seed: Self::Seed) -> Self {
        let mut parts = [0u64; 4];
        for i in 0..4 {
            parts[i] = u64::from_le_bytes(seed[i * 8..(i + 1) * 8].try_into().unwrap());
        }
        Self::init(parts, 4)
    }

    /// Expands a single `u64` using a SplitMix64-like mixer into 256 bits.
    fn seed_from_u64(mut x: u64) -> Self {
        let mut parts = [0u64; 4];
        // SplitMix64-ish expansion into 256 bits
        for slot in &mut parts {
            x ^= x >> 12;
            x ^= x << 25;
            x ^= x >> 27;
            *slot = x.wrapping_mul(2_685_821_657_736_338_717);
        }
        Self::init(parts, 4)
    }
}

/* ---------------------- CRYPTO RNG (feature = "crypto") --------------------- */

/// Cryptographically secure RNG wrapper (ChaCha20).
///
/// Available with the `"crypto"` feature. This type intentionally **does not**
/// implement `serde` because the underlying `ChaCha20Rng` does not expose a
/// stable, serializable state.
///
/// Prefer `CryptoRng256::from_os()` for production seeding.
///
/// # Examples
/// ```
/// # #[cfg(feature="crypto")] {
/// use xoroshiro256_full::CryptoRng256;
/// let mut r = CryptoRng256::from_os();
/// let x = r.next_u64();
/// # }
/// ```
#[cfg(feature = "crypto")]
pub use crypto_rng::CryptoRng256;

#[cfg(feature = "crypto")]
mod crypto_rng {
    use getrandom::getrandom;
    use rand_chacha::ChaCha20Rng;
    use rand_core::{CryptoRng, RngCore, SeedableRng};

    #[derive(Clone, Debug)]
    pub struct CryptoRng256 {
        pub(crate) inner: ChaCha20Rng,
    }

    impl CryptoRng256 {
        /// Seed from OS entropy (recommended).
        #[must_use]
        pub fn from_os() -> Self {
            let mut seed = <ChaCha20Rng as SeedableRng>::Seed::default(); // [u8; 32]
            getrandom(&mut seed).expect("OS randomness unavailable");
            Self {
                inner: ChaCha20Rng::from_seed(seed),
            }
        }

        /// Seed from a user-provided 32-byte seed (deterministic).
        #[must_use]
        pub fn from_seed(seed: [u8; 32]) -> Self {
            Self {
                inner: ChaCha20Rng::from_seed(seed),
            }
        }

        /// Fill `buf` with CSPRNG output.
        #[inline]
        pub fn fill_bytes(&mut self, buf: &mut [u8]) {
            self.inner.fill_bytes(buf);
        }

        /// Next `u64` from CSPRNG.
        #[inline]
        pub fn next_u64(&mut self) -> u64 {
            self.inner.next_u64()
        }
    }

    impl RngCore for CryptoRng256 {
        #[inline]
        fn next_u32(&mut self) -> u32 {
            self.inner.next_u32()
        }
        #[inline]
        fn next_u64(&mut self) -> u64 {
            self.inner.next_u64()
        }
        fn fill_bytes(&mut self, dest: &mut [u8]) {
            self.inner.fill_bytes(dest);
        }
        fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), rand_core::Error> {
            self.inner.try_fill_bytes(dest)
        }
    }
    impl CryptoRng for CryptoRng256 {}
}

/* ---------------------------------- TESTS ---------------------------------- */

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::HashSet;

    /* ---- init / seeding ---- */

    #[test]
    fn init_1_key_derives_rest_and_nonzero() {
        let s = Xoroshiro256State::init([0xDEAD_BEEF_CAFE_BABE, 0, 0, 0], 1);
        // derived words must not all be zero
        assert!(s.parts.iter().any(|&p| p != 0));
    }

    #[test]
    #[should_panic(expected = "key_length must be 1..=4")]
    fn init_panics_on_zero_length() {
        let _ = Xoroshiro256State::init([0; 4], 0);
    }

    #[test]
    #[should_panic(expected = "key_length must be 1..=4")]
    fn init_panics_on_too_long() {
        let _ = Xoroshiro256State::init([0; 4], 5);
    }

    #[test]
    fn init_all_zero_forced_nonzero() {
        let s = Xoroshiro256State::init([0, 0, 0, 0], 4);
        assert!(s.parts.iter().any(|&p| p != 0));
    }

    /* ---- core stepping ---- */

    #[test]
    fn next_u64_progresses() {
        let mut r = Xoroshiro256State::init([1, 2, 3, 4], 4);
        let a = r.next_u64();
        let b = r.next_u64();
        assert_ne!(a, b);
    }

    #[test]
    fn determinism_same_seed_same_sequence() {
        let seed = [
            0xAABB_CCDD_EEFF_0011,
            0x1122_3344_5566_7788,
            0x99AA_BBCC_DDEE_FF00,
            0x1234_5678_90AB_CDEF,
        ];
        let mut r1 = Xoroshiro256State::init(seed, 4);
        let mut r2 = Xoroshiro256State::init(seed, 4);
        for _ in 0..64 {
            assert_eq!(r1.next_u64(), r2.next_u64());
        }
    }

    /* ---- state dump / buffer handling ---- */

    #[test]
    #[should_panic(expected = "Buffer must have at least 32 bytes")]
    fn dump_panics_on_small_buffer() {
        let r = Xoroshiro256State::init([1, 2, 3, 4], 4);
        let mut buf = [0u8; 31];
        r.genrand_uint256_to_buf(&mut buf);
    }

    #[test]
    fn dump_writes_exact_32_bytes_little_endian() {
        let r = Xoroshiro256State::init([1, 2, 3, 4], 4);
        let mut buf = [0u8; 32];
        r.genrand_uint256_to_buf(&mut buf);
        // reconstruct parts and compare
        for i in 0..4 {
            let mut le = [0u8; 8];
            le.copy_from_slice(&buf[i * 8..(i + 1) * 8]);
            assert_eq!(u64::from_le_bytes(le), r.parts[i]);
        }
    }

    /* ---- rand_core integration (optional) ---- */

    #[cfg(feature = "rand_core")]
    #[test]
    fn rand_core_fill_bytes_various_lengths() {
        use rand_core::RngCore;
        let mut r = Xoroshiro256State::seed_from_u64(42);
        for &len in &[0usize, 1, 7, 8, 9, 15, 16, 31, 32, 33, 64, 65] {
            let mut buf = vec![0u8; len];
            r.fill_bytes(&mut buf);
            if len > 0 {
                assert!(buf.iter().any(|&b| b != 0));
            }
        }
    }

    #[cfg(feature = "rand_core")]
    #[test]
    fn seedable_from_seed_roundtrip() {
        let seed = [7u8; 32];
        let mut r1 = Xoroshiro256State::from_seed(seed);
        let mut r2 = Xoroshiro256State::from_seed(seed);
        for _ in 0..16 {
            assert_eq!(r1.next_u64(), r2.next_u64());
        }
    }

    #[cfg(feature = "rand_core")]
    #[test]
    fn seed_from_u64_reproducible() {
        let mut r1 = Xoroshiro256State::seed_from_u64(123_456_789);
        let mut r2 = Xoroshiro256State::seed_from_u64(123_456_789);
        for _ in 0..16 {
            assert_eq!(r1.next_u64(), r2.next_u64());
        }
    }

    /* ---- basic distribution sanity (non-rigorous) ---- */

    #[test]
    fn basic_spread_low_collision() {
        let mut r = Xoroshiro256State::init([1, 2, 3, 4], 4);
        let mut set = HashSet::new();
        for _ in 0..100 {
            set.insert(r.next_u64());
        }
        assert!(set.len() > 95, "too many collisions for 100 samples");
    }

    /* ---- crypto RNG (optional) ---- */

    #[cfg(feature = "crypto")]
    #[test]
    fn crypto_rng_basic() {
        let mut r = super::CryptoRng256::from_os();
        let a = r.next_u64();
        let b = r.next_u64();
        assert_ne!(a, b);
        let mut buf = [0u8; 64];
        r.fill_bytes(&mut buf);
        assert!(buf.iter().any(|&b| b != 0));
    }

    #[cfg(feature = "crypto")]
    #[test]
    fn crypto_rng_reproducible_seed() {
        let seed = [7u8; 32];
        let mut r1 = super::CryptoRng256::from_seed(seed);
        let mut r2 = super::CryptoRng256::from_seed(seed);
        for _ in 0..8 {
            assert_eq!(r1.next_u64(), r2.next_u64());
        }
    }

    /* ---- anti-waste correctness checks (rand_core) ---- */

    #[cfg(feature = "rand_core")]
    #[test]
    fn next_u32_consumes_full_u64_in_pairs() {
        use rand_core::RngCore;
        let mut a = Xoroshiro256State::seed_from_u64(9999);
        let mut b = Xoroshiro256State::seed_from_u64(9999);
        let x = a.next_u64();
        let hi = u64::from(b.next_u32());
        let lo = u64::from(b.next_u32());
        assert_eq!((hi << 32) | lo, x);
    }

    #[cfg(feature = "rand_core")]
    #[test]
    fn fill_bytes_tail_is_reused_across_calls() {
        use rand_core::RngCore;
        let mut a = Xoroshiro256State::seed_from_u64(2024);
        let mut b = Xoroshiro256State::seed_from_u64(2024);
        let mut buf8 = [0u8; 8];
        b.fill_bytes(&mut buf8);

        let mut buf3 = [0u8; 3];
        a.fill_bytes(&mut buf3);
        let mut buf5 = [0u8; 5];
        a.fill_bytes(&mut buf5); // should reuse tail from previous call

        let mut joined = [0u8; 8];
        joined[..3].copy_from_slice(&buf3);
        joined[3..].copy_from_slice(&buf5);

        assert_eq!(joined, buf8);
    }
}