rand_mt/
lib.rs

1// src/lib.rs
2//
3// Copyright (c) 2015,2017 rust-mersenne-twister developers
4// Copyright (c) 2020 Ryan Lopopolo <rjl@hyperbo.la>
5//
6// Licensed under the Apache License, Version 2.0
7// <LICENSE-APACHE> or <http://www.apache.org/licenses/LICENSE-2.0> or the MIT
8// license <LICENSE-MIT> or <http://opensource.org/licenses/MIT>, at your
9// option. All files in the project carrying such notice may not be copied,
10// modified, or distributed except according to those terms.
11
12#![deny(clippy::all)]
13#![deny(clippy::pedantic)]
14#![deny(clippy::cargo)]
15#![allow(unknown_lints)]
16#![deny(missing_debug_implementations)]
17#![warn(missing_docs)]
18#![warn(rust_2018_idioms)]
19#![warn(trivial_casts, trivial_numeric_casts)]
20#![warn(unused_qualifications)]
21#![warn(variant_size_differences)]
22#![forbid(unsafe_code)]
23// Enable feature callouts in generated documentation:
24// https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html
25//
26// This approach is borrowed from tokio.
27#![cfg_attr(docsrs, feature(doc_cfg))]
28#![cfg_attr(docsrs, feature(doc_alias))]
29
30//! Mersenne Twister random number generators.
31//!
32//! This is a native Rust implementation of a selection of Mersenne Twister
33//! generators. Mersenne Twister is not suitable for cryptographic use.
34//!
35//! This crate provides:
36//!
37//! - [`Mt`], the original reference Mersenne Twister implementation known as
38//!   `MT19937`. This is a good choice on both 32-bit and 64-bit CPUs (for
39//!   32-bit output).
40//! - [`Mt64`], the 64-bit variant of `MT19937` known as `MT19937-64`. This
41//!   algorithm produces a different output stream than `MT19937` and produces
42//!   64-bit output. This is a good choice on 64-bit CPUs.
43//!
44//! Both of these RNGs use approximately 2.5 kilobytes of state. [`Mt`] uses a
45//! 32-bit seed. [`Mt64`] uses a 64-bit seed. Both can be seeded from an
46//! iterator of seeds.
47//!
48//! Both RNGs implement a `recover` constructor which can reconstruct the RNG
49//! state from a sequence of output samples.
50//!
51//! # Usage
52//!
53//! You can seed a RNG and begin sampling it:
54//!
55//! ```
56//! # use rand_mt::Mt64;
57//! // Create the RNG.
58//! let mut rng = Mt64::new(0x1234_567_89ab_cdef_u64);
59//! // start grabbing randomness from rng...
60//! let mut buf = vec![0; 512];
61//! rng.fill_bytes(&mut buf);
62//! ```
63//!
64//! Or if you want to use the default (fixed) seeds that are specified in the
65//! reference implementations:
66//!
67//! ```
68//! # use rand_mt::Mt;
69//! let default = Mt::default();
70//! let mt = Mt::new_unseeded();
71//! assert_eq!(default, mt);
72//! ```
73//!
74//! # Crate Features
75//!
76//! `rand_mt` is `no_std` compatible. `rand_mt` has several optional features
77//! that are enabled by default:
78//!
79//! - **rand-traits** - Enables a dependency on [`rand_core`]. Activating this
80//!   feature implements `RngCore` and `SeedableRng` on the RNGs in this crate.
81//!
82//! Mersenne Twister requires approximately 2.5 kilobytes of internal state. To
83//! make the RNGs implemented in this crate practical to embed in other structs,
84//! you may wish to store the RNG in a [`Box`].
85//!
86#![cfg_attr(
87    not(feature = "rand-traits"),
88    doc = "[`rand_core`]: https://crates.io/crates/rand_core"
89)]
90//! [`Box`]: https://doc.rust-lang.org/std/boxed/struct.Box.html"
91
92#![doc(html_root_url = "https://docs.rs/rand_mt/5.0.0")]
93#![no_std]
94
95#[cfg(any(test, doctest))]
96extern crate std;
97
98use core::fmt;
99
100pub use crate::mt::Mt;
101pub use crate::mt64::Mt64;
102
103mod mt;
104mod mt64;
105#[cfg(test)]
106mod vectors;
107
108/// Error returned from fallible Mersenne Twister recovery constructors.
109#[non_exhaustive]
110#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq)]
111pub enum RecoverRngError {
112    /// Attempted to recover an RNG with too many samples.
113    ///
114    /// Recover constructors require an exact number of samples to ensure the
115    /// recovered RNG matches the state of the RNG that supplied all of the
116    /// samples.
117    TooFewSamples(usize),
118    /// Attempted to recover an RNG with too few samples.
119    ///
120    /// Too few samples leaves the internal state buffer partially
121    /// uninitialized.
122    ///
123    /// Recover constructors require an exact number of samples to ensure the
124    /// recovered RNG matches the state of the RNG that supplied all of the
125    /// samples.
126    TooManySamples(usize),
127}
128
129impl fmt::Display for RecoverRngError {
130    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
131        match self {
132            Self::TooFewSamples(expected) => {
133                write!(f, "Too few samples given to recover: expected {expected}")
134            }
135            Self::TooManySamples(expected) => {
136                write!(f, "Too many samples given to recover: expected {expected}")
137            }
138        }
139    }
140}
141
142impl core::error::Error for RecoverRngError {}
143
144#[cfg(test)]
145mod tests {
146    use super::RecoverRngError;
147
148    #[test]
149    fn error_display_is_not_empty() {
150        use core::fmt::Write as _;
151        use std::string::String;
152
153        let test_cases = [
154            RecoverRngError::TooFewSamples(0),
155            RecoverRngError::TooFewSamples(124),
156            RecoverRngError::TooManySamples(0),
157            RecoverRngError::TooManySamples(987),
158        ];
159        for tc in test_cases {
160            let mut buf = String::new();
161            write!(&mut buf, "{tc}").unwrap();
162            assert!(!buf.is_empty());
163        }
164    }
165}
166
167// Ensure code blocks in `README.md` compile.
168//
169// This module and macro declaration should be kept at the end of the file, in
170// order to not interfere with code coverage.
171#[cfg(doctest)]
172macro_rules! readme {
173    ($x:expr) => {
174        #[doc = $x]
175        mod readme {}
176    };
177    () => {
178        readme!(include_str!("../README.md"));
179    };
180}
181#[cfg(doctest)]
182readme!();
rand_mt/lib.rs

rand_mt/
lib.rs
