turborand/
lib.rs

1//! Fast random number generators.
2//!
3//! The implementations use [Wyrand](https://github.com/wangyi-fudan/wyhash), a simple and fast
4//! generator but **not** cryptographically secure, and [ChaCha8](https://cr.yp.to/chacha.html),
5//! a cryptographically secure generator tuned to 8 rounds of the ChaCha algorithm in order to
6//! increase throughput considerably without sacrificing too much security, as per the
7//! recommendations set out in the [Too Much Crypto](https://eprint.iacr.org/2019/1492.pdf) paper.
8//!
9//! # Examples
10//!
11//! Generate a random value:
12//!
13//! ```ignore
14//! use turborand::prelude::*;
15//!
16//! let rand = Rng::new();
17//!
18//! let value = rand.bool();
19//! ```
20//!
21//! Sample a value from a list:
22//!
23//! ```ignore
24//! use turborand::prelude::*;
25//!
26//! let rand = Rng::new();
27//!
28//! let values = [1, 2, 3, 4, 5];
29//!
30//! let value = rand.sample(&values);
31//! ```
32//!
33//! Generate a vector with random values:
34//!
35//! ```ignore
36//! use turborand::prelude::*;
37//! use std::iter::repeat_with;
38//!
39//! let rand = Rng::new();
40//!
41//! let values: Vec<_> = repeat_with(|| rand.f32()).take(10).collect();
42//! ```
43//!
44//! # Features
45//!
46//! The base crate will always export the [`TurboCore`], [`GenCore`],
47//! [`SeededCore`], [`TurboRand`], [`SecureCore`] and [`ForkableCore`] traits, and will do
48//! so when set as `default-features = false` in the Cargo.toml. By default,
49//! it will have `wyrand` feature enabled as the basic PRNG exposed.
50//!
51//! * **`alloc`** - Enables support for boxed [`TurboCore`] references, as well
52//!   as [`TurboRand`] methods that return [`Vec`] results.
53//! * **`fmt`** - Enables [`core::fmt::Debug`] implementations for [`rng::Rng`]
54//!   & [`chacha_rng::ChaChaRng`].
55//! * **`std`** - Enables `std` features, such as `alloc` methods as well as
56//!   [`Default`] implementations for [`rng::Rng`] & [`chacha_rng::ChaChaRng`].
57//! * **`wyrand`** - Enables [`rng::Rng`], so to provide a
58//!   basic, non-threadsafe PRNG. Enabled by default. `no-std` compatible.
59//! * **`atomic`** - Enables [`rng::AtomicRng`], so
60//!   to provide a thread-safe variation of [`rng::Rng`]. Enables `wyrand`
61//!   feature implicitly. **Note**, this is slower than [`rng::Rng`].
62//! * **`rand`** - Provides [`compatibility::RandCompat`], which implements [`RngCore`]
63//!   so to allow for compatibility with `rand` ecosystem of crates
64//! * **`serialize`** - Enables [`Serialize`] and [`Deserialize`] derives on [`rng::Rng`],
65//!   [`rng::AtomicRng`] and [`chacha_rng::ChaChaRng`], provided they have their
66//!   respective features activated as well.
67//! * **`chacha`** - Enables [`chacha_rng::ChaChaRng`] for providing a more cryptographically
68//!   secure source of Rng. Note, this will be slower than [`rng::Rng`] in
69//!   throughput, but will produce much higher quality randomness. `no-std` compatible.
70#![warn(missing_docs, rust_2018_idioms)]
71#![forbid(clippy::undocumented_unsafe_blocks)]
72#![cfg_attr(docsrs, feature(doc_cfg))]
73#![cfg_attr(docsrs, allow(unused_attributes))]
74#![cfg_attr(not(feature = "std"), no_std)]
75
76#[cfg(feature = "alloc")]
77extern crate alloc;
78
79#[cfg(all(feature = "std", any(feature = "wyrand", feature = "chacha")))]
80use alloc::rc::Rc;
81
82#[cfg(all(feature = "fmt", any(feature = "wyrand", feature = "chacha")))]
83use core::fmt::Debug;
84
85#[cfg(all(
86    feature = "std",
87    target_arch = "wasm32",
88    any(feature = "wyrand", feature = "chacha")
89))]
90use instant::Instant;
91#[cfg(all(
92    feature = "std",
93    not(target_arch = "wasm32"),
94    any(feature = "wyrand", feature = "chacha")
95))]
96use std::time::Instant;
97
98#[cfg(feature = "rand")]
99use rand_core::RngCore;
100
101#[cfg(all(feature = "serialize", any(feature = "chacha", feature = "wyrand")))]
102use serde::{Deserialize, Serialize};
103
104#[cfg(all(feature = "serialize", any(feature = "chacha", feature = "atomic")))]
105use serde::de::Visitor;
106
107#[cfg(all(feature = "serialize", feature = "chacha"))]
108use serde::ser::{SerializeStruct, SerializeTuple};
109
110#[macro_use]
111mod methods;
112
113#[cfg(feature = "chacha")]
114#[cfg_attr(docsrs, doc(cfg(feature = "chacha")))]
115pub mod chacha_rng;
116#[cfg(feature = "rand")]
117#[cfg_attr(docsrs, doc(cfg(feature = "rand")))]
118pub mod compatibility;
119#[cfg(all(feature = "std", any(feature = "wyrand", feature = "chacha")))]
120mod entropy;
121mod internal;
122#[cfg(any(feature = "wyrand", feature = "atomic"))]
123#[cfg_attr(docsrs, doc(cfg(any(feature = "wyrand", feature = "atomic"))))]
124pub mod rng;
125mod source;
126mod traits;
127
128pub use traits::{ForkableCore, GenCore, SecureCore, SeededCore, TurboCore, TurboKind, TurboRand};
129
130pub mod prelude;
turborand/lib.rs

turborand/
lib.rs
