rand_xorshift/
lib.rs

1// Copyright 2018 Developers of the Rand project.
2//
3// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
4// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
5// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
6// option. This file may not be copied, modified, or distributed
7// except according to those terms.
8
9//! The xorshift random number generator.
10
11#![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",
12       html_favicon_url = "https://www.rust-lang.org/favicon.ico",
13       html_root_url = "https://rust-random.github.io/rand/")]
14
15#![deny(missing_docs)]
16#![deny(missing_debug_implementations)]
17
18#![no_std]
19
20use core::num::Wrapping as w;
21use core::{fmt, slice};
22use rand_core::{RngCore, SeedableRng, Error, impls, le};
23#[cfg(feature="serde1")] use serde::{Serialize, Deserialize};
24
25/// An Xorshift random number generator.
26///
27/// The Xorshift[^1] algorithm is not suitable for cryptographic purposes
28/// but is very fast. If you do not know for sure that it fits your
29/// requirements, use a more secure one such as `StdRng` or `OsRng`.
30///
31/// [^1]: Marsaglia, George (July 2003).
32///       ["Xorshift RNGs"](https://www.jstatsoft.org/v08/i14/paper).
33///       *Journal of Statistical Software*. Vol. 8 (Issue 14).
34#[derive(Clone)]
35#[cfg_attr(feature="serde1", derive(Serialize,Deserialize))]
36pub struct XorShiftRng {
37    x: w<u32>,
38    y: w<u32>,
39    z: w<u32>,
40    w: w<u32>,
41}
42
43// Custom Debug implementation that does not expose the internal state
44impl fmt::Debug for XorShiftRng {
45    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
46        write!(f, "XorShiftRng {{}}")
47    }
48}
49
50impl RngCore for XorShiftRng {
51    #[inline]
52    fn next_u32(&mut self) -> u32 {
53        let x = self.x;
54        let t = x ^ (x << 11);
55        self.x = self.y;
56        self.y = self.z;
57        self.z = self.w;
58        let w_ = self.w;
59        self.w = w_ ^ (w_ >> 19) ^ (t ^ (t >> 8));
60        self.w.0
61    }
62
63    #[inline]
64    fn next_u64(&mut self) -> u64 {
65        impls::next_u64_via_u32(self)
66    }
67
68    #[inline]
69    fn fill_bytes(&mut self, dest: &mut [u8]) {
70        impls::fill_bytes_via_next(self, dest)
71    }
72
73    fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
74        Ok(self.fill_bytes(dest))
75    }
76}
77
78impl SeedableRng for XorShiftRng {
79    type Seed = [u8; 16];
80
81    fn from_seed(seed: Self::Seed) -> Self {
82        let mut seed_u32 = [0u32; 4];
83        le::read_u32_into(&seed, &mut seed_u32);
84
85        // Xorshift cannot be seeded with 0 and we cannot return an Error, but
86        // also do not wish to panic (because a random seed can legitimately be
87        // 0); our only option is therefore to use a preset value.
88        if seed_u32.iter().all(|&x| x == 0) {
89            seed_u32 = [0xBAD_5EED, 0xBAD_5EED, 0xBAD_5EED, 0xBAD_5EED];
90        }
91
92        XorShiftRng {
93            x: w(seed_u32[0]),
94            y: w(seed_u32[1]),
95            z: w(seed_u32[2]),
96            w: w(seed_u32[3]),
97        }
98    }
99
100    fn from_rng<R: RngCore>(mut rng: R) -> Result<Self, Error> {
101        let mut seed_u32 = [0u32; 4];
102        loop {
103            unsafe {
104                let ptr = seed_u32.as_mut_ptr() as *mut u8;
105
106                let slice = slice::from_raw_parts_mut(ptr, 4 * 4);
107                rng.try_fill_bytes(slice)?;
108            }
109            for v in seed_u32.iter_mut() {
110                // enforce LE for consistency across platforms
111                *v = v.to_le();
112            }
113            if !seed_u32.iter().all(|&x| x == 0) { break; }
114        }
115
116        Ok(XorShiftRng {
117            x: w(seed_u32[0]),
118            y: w(seed_u32[1]),
119            z: w(seed_u32[2]),
120            w: w(seed_u32[3]),
121        })
122    }
123}
rand_xorshift/lib.rs

rand_xorshift/
lib.rs
