spinoso_random/random/
mod.rs

1use alloc::vec::Vec;
2use core::fmt;
3use core::mem::size_of;
4
5use rand_mt::Mt;
6
7use crate::{InitializeError, NewSeedError};
8
9#[cfg(feature = "rand_core")]
10mod rand;
11
12const DEFAULT_SEED_CNT: usize = 4;
13const DEFAULT_SEED_BYTES: usize = size_of::<u32>() * DEFAULT_SEED_CNT;
14
15const DEFAULT_SEED: u32 = 5489_u32;
16
17/// Random provides an interface to Ruby's pseudo-random number generator, or
18/// PRNG.
19///
20/// The PRNG produces a deterministic sequence of bits which approximate true
21/// randomness. The sequence may be represented by integers, floats, or binary
22/// strings.
23///
24/// The generator may be initialized with either a system-generated or
25/// user-supplied seed value.
26///
27/// PRNGs are currently implemented as a modified Mersenne Twister with a period
28/// of 2**19937-1.
29///
30/// This RNG reproduces the same random bytes and floats as MRI. It may differ
31/// when returning elements confined to a distribution.
32///
33/// # Examples
34///
35/// Create an RNG with a random seed:
36///
37/// ```
38/// use spinoso_random::{Error, Random};
39///
40/// # fn example() -> Result<(), Error> {
41/// let mut random = Random::new()?;
42/// let next = random.next_int32();
43/// # Ok(())
44/// # }
45/// # example().unwrap();
46/// ```
47///
48/// Create a RNG with a fixed seed:
49///
50/// ```
51/// use spinoso_random::Random;
52///
53/// let seed = 5489_u32;
54/// let mut random = Random::with_seed(seed);
55/// let rand = random.next_int32();
56///
57/// let seed = [627457_u32, 697550, 16438, 41926];
58/// let mut random = Random::with_array_seed(seed);
59/// let rand = random.next_int32();
60/// ```
61#[derive(Clone, Hash, PartialEq, Eq)]
62pub struct Random {
63    mt: Mt,
64    seed: Vec<u32>,
65}
66
67impl Default for Random {
68    #[inline]
69    fn default() -> Self {
70        if let Ok(random) = Random::new() {
71            random
72        } else {
73            Random::with_seed(DEFAULT_SEED)
74        }
75    }
76}
77
78impl fmt::Debug for Random {
79    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
80        f.write_str("Random {}")
81    }
82}
83
84impl From<u32> for Random {
85    #[inline]
86    fn from(seed: u32) -> Self {
87        Self::with_seed(seed)
88    }
89}
90
91impl From<[u32; DEFAULT_SEED_CNT]> for Random {
92    #[inline]
93    fn from(seed: [u32; DEFAULT_SEED_CNT]) -> Self {
94        Self::with_array_seed(seed)
95    }
96}
97
98impl From<&[u32]> for Random {
99    #[inline]
100    fn from(seed: &[u32]) -> Self {
101        Self::with_array_seed(seed.iter().copied())
102    }
103}
104
105impl From<[u8; DEFAULT_SEED_BYTES]> for Random {
106    #[inline]
107    fn from(seed: [u8; DEFAULT_SEED_BYTES]) -> Self {
108        Self::with_byte_array_seed(seed)
109    }
110}
111
112impl Random {
113    /// Create a new Mersenne Twister random number generator with a randomly
114    /// generated seed.
115    ///
116    /// This method initializes the Mersenne Twister random number generator
117    /// with a seed derived from a cryptographically secure source of
118    /// randomness.
119    ///
120    /// # Examples
121    ///
122    /// ```
123    /// use spinoso_random::{Error, Random};
124    ///
125    /// # fn example() -> Result<(), Error> {
126    /// let mut random = Random::new()?;
127    /// let next = random.next_int32();
128    /// # Ok(())
129    /// # }
130    /// # example().unwrap();
131    /// ```
132    ///
133    /// # Errors
134    ///
135    /// If the randomness feature provided by the platform is not present or
136    /// failed to completely generate a seed, an error is returned. This error
137    /// should be raised as a [Ruby `RuntimeError`].
138    ///
139    /// [Ruby `RuntimeError`]: https://ruby-doc.org/core-3.1.2/RuntimeError.html
140    #[inline]
141    pub fn new() -> Result<Self, InitializeError> {
142        if let Ok(seed) = new_seed() {
143            let mt = Mt::new_with_key(seed.iter().copied());
144            Ok(Self {
145                mt,
146                seed: seed.to_vec(),
147            })
148        } else {
149            Err(InitializeError::new())
150        }
151    }
152
153    /// Create a new random number generator using the given seed.
154    ///
155    /// # Examples
156    ///
157    /// ```
158    /// use spinoso_random::Random;
159    ///
160    /// let seed = 33;
161    /// let mut random = Random::with_seed(seed);
162    /// let rand = random.next_int32();
163    /// ```
164    #[inline]
165    #[must_use]
166    pub fn with_seed(seed: u32) -> Self {
167        let mt = Mt::new(seed);
168        let seed = u128::from(seed).to_le_bytes();
169        let seed = seed_to_key(seed);
170        Self {
171            mt,
172            seed: seed.to_vec(),
173        }
174    }
175
176    /// Create a new random number generator using the given seed.
177    ///
178    /// # Examples
179    ///
180    /// ```
181    /// use spinoso_random::Random;
182    ///
183    /// let seed = [1_u32, 2, 3, 4];
184    /// let mut random = Random::with_array_seed(seed);
185    /// let rand = random.next_int32();
186    /// ```
187    #[inline]
188    #[must_use]
189    pub fn with_array_seed<T>(seed: T) -> Self
190    where
191        T: IntoIterator<Item = u32>,
192        T::IntoIter: Clone,
193    {
194        let iter = seed.into_iter();
195        let mt = Mt::new_with_key(iter.clone());
196        Self {
197            mt,
198            seed: iter.collect(),
199        }
200    }
201
202    /// Create a new random number generator using the given seed.
203    ///
204    /// # Examples
205    ///
206    /// ```
207    /// use spinoso_random::Random;
208    ///
209    /// let seed = [1_u32, 2, 3, 4];
210    /// let mut random = Random::with_array_seed(seed);
211    /// let rand = random.next_int32();
212    /// ```
213    #[inline]
214    #[must_use]
215    pub fn with_byte_array_seed(seed: [u8; DEFAULT_SEED_BYTES]) -> Self {
216        let seed = seed_to_key(seed);
217        let mt = Mt::new_with_key(seed.iter().copied());
218        Self {
219            mt,
220            seed: seed.to_vec(),
221        }
222    }
223
224    /// Generate next `u32` output.
225    ///
226    /// Generates a random number on `(0..=0xffffffff)`-interval.
227    ///
228    /// `u32` is the native output of the generator. This function advances the
229    /// RNG step counter by one.
230    ///
231    /// # Examples
232    ///
233    /// ```
234    /// use spinoso_random::{Error, Random};
235    ///
236    /// # fn example() -> Result<(), Error> {
237    /// let mut random = Random::new()?;
238    /// assert_ne!(random.next_int32(), random.next_int32());
239    /// # Ok(())
240    /// # }
241    /// # example().unwrap();
242    /// ```
243    #[inline]
244    #[must_use]
245    pub fn next_int32(&mut self) -> u32 {
246        self.mt.next_u32()
247    }
248
249    /// Generate next `f64` output.
250    ///
251    /// Generates a random number on [0,1) with 53-bit resolution.
252    ///
253    /// # Examples
254    ///
255    /// ```
256    /// use spinoso_random::{Error, Random};
257    ///
258    /// # fn example() -> Result<(), Error> {
259    /// let mut random = Random::new()?;
260    /// assert_ne!(random.next_real(), random.next_real());
261    /// # Ok(())
262    /// # }
263    /// # example().unwrap();
264    /// ```
265    #[inline]
266    #[must_use]
267    pub fn next_real(&mut self) -> f64 {
268        let a = self.next_int32();
269        let b = self.next_int32();
270        int_pair_to_real_exclusive(a, b)
271    }
272
273    /// Fill a buffer with bytes generated from the RNG.
274    ///
275    /// This method generates random `u32`s (the native output unit of the RNG)
276    /// until `dest` is filled.
277    ///
278    /// This method may discard some output bits if `dest.len()` is not a
279    /// multiple of 4.
280    ///
281    /// # Examples
282    ///
283    /// ```
284    /// use spinoso_random::{Error, Random};
285    ///
286    /// # fn example() -> Result<(), Error> {
287    /// let mut random = Random::new()?;
288    /// let mut buf = [0; 32];
289    /// random.fill_bytes(&mut buf);
290    /// assert_ne!([0; 32], buf);
291    /// let mut buf = [0; 31];
292    /// random.fill_bytes(&mut buf);
293    /// assert_ne!([0; 31], buf);
294    /// # Ok(())
295    /// # }
296    /// # example().unwrap();
297    /// ```
298    #[inline]
299    pub fn fill_bytes(&mut self, dest: &mut [u8]) {
300        self.mt.fill_bytes(dest);
301    }
302
303    /// Returns the seed value used to initialize the generator.
304    ///
305    /// This may be used to initialize another generator with the same state at
306    /// a later time, causing it to produce the same sequence of numbers.
307    ///
308    /// # Examples
309    ///
310    /// ```
311    /// use spinoso_random::Random;
312    ///
313    /// let seed = [1_u32, 2, 3, 4];
314    /// let random = Random::with_array_seed(seed);
315    /// assert_eq!(random.seed(), seed);
316    /// ```
317    #[inline]
318    #[must_use]
319    pub fn seed(&self) -> &[u32] {
320        &self.seed
321    }
322}
323
324#[inline]
325#[must_use]
326fn int_pair_to_real_exclusive(mut a: u32, mut b: u32) -> f64 {
327    a >>= 5;
328    b >>= 6;
329    let a = f64::from(a);
330    let b = f64::from(b);
331    (a * 67_108_864.0 + b) * (1.0 / 9_007_199_254_740_992.0)
332}
333
334#[inline]
335#[must_use]
336#[expect(dead_code, reason = "implementing a routine from MRI which is currently unused")]
337#[expect(clippy::cast_precision_loss, reason = "MRI routine")]
338fn int_pair_to_real_inclusive(a: u32, b: u32) -> f64 {
339    const MANTISSA_DIGITS: i32 = 53;
340    const M: u128 = (1 << MANTISSA_DIGITS) | 1;
341    let x = (u128::from(a) << 32) | u128::from(b);
342    let r = ((x * M) >> 64) as u64 as f64;
343    libm::ldexp(r, -MANTISSA_DIGITS)
344}
345
346/// Convert a byte array into a reseeding key of `u32`s.
347#[inline]
348#[must_use]
349pub fn seed_to_key(seed: [u8; DEFAULT_SEED_BYTES]) -> [u32; DEFAULT_SEED_CNT] {
350    let mut key = [0_u32; DEFAULT_SEED_CNT];
351    let iter = key.iter_mut().zip(seed.chunks_exact(size_of::<u32>()));
352
353    let mut bytes = [0; size_of::<u32>()];
354    for (cell, chunk) in iter {
355        bytes.copy_from_slice(chunk);
356        *cell = u32::from_le_bytes(bytes);
357    }
358    key
359}
360
361/// Read a new [`Random`] seed, using platform-provided randomness.
362///
363/// # Examples
364///
365/// ```
366/// use spinoso_random::{Error, Random};
367///
368/// # fn example() -> Result<(), Error> {
369/// let seed = spinoso_random::new_seed()?;
370/// # Ok(())
371/// # }
372/// example().unwrap();
373/// ```
374///
375/// # Errors
376///
377/// If the randomness feature provided by the platform is not present or failed
378/// to completely generate a seed, an error is returned. This error should be
379/// raised as a [Ruby `RuntimeError`].
380///
381/// [Ruby `RuntimeError`]: https://ruby-doc.org/core-3.1.2/RuntimeError.html
382#[inline]
383pub fn new_seed() -> Result<[u32; DEFAULT_SEED_CNT], NewSeedError> {
384    let mut seed = [0; DEFAULT_SEED_BYTES];
385    getrandom::fill(&mut seed)?;
386    let seed = seed_to_key(seed);
387    Ok(seed)
388}
389
390#[cfg(test)]
391mod tests {
392    use alloc::string::String;
393    use core::fmt::Write as _;
394
395    use super::Random;
396
397    #[test]
398    fn fmt_debug_does_not_leak_seed() {
399        let random = Random::with_seed(874);
400
401        let mut buf = String::new();
402        write!(&mut buf, "{random:?}").unwrap();
403        assert!(!buf.contains("874"));
404        assert_eq!(buf, "Random {}");
405
406        let random = Random::with_seed(123_456);
407
408        let mut buf = String::new();
409        write!(&mut buf, "{random:?}").unwrap();
410        assert!(!buf.contains("123456"));
411        assert_eq!(buf, "Random {}");
412    }
413}
spinoso_random/random/mod.rs

spinoso_random/random/
mod.rs
