Crate turborand

Fast random number generators.

The implementations use Wyrand, a simple and fast generator but not cryptographically secure, and ChaCha8, a cryptographically secure generator tuned to 8 rounds of the ChaCha algorithm in order to increase throughput considerably without sacrificing too much security, as per the recommendations set out in the Too Much Crypto paper.

Examples

Generate a random value:

use turborand::prelude::*;

let rand = Rng::new();

let value = rand.bool();

Sample a value from a list:

use turborand::prelude::*;

let rand = Rng::new();

let values = [1, 2, 3, 4, 5];

let value = rand.sample(&values);

Generate a vector with random values:

use turborand::prelude::*;
use std::iter::repeat_with;

let rand = Rng::new();

let values: Vec<_> = repeat_with(|| rand.f32()).take(10).collect();

Features

The base crate will always export the TurboCore, GenCore, SeededCore, TurboRand, SecureCore and ForkableCore traits, and will do so when set as default-features = false in the Cargo.toml. By default, it will have wyrand feature enabled as the basic PRNG exposed.

• alloc - Enables support for boxed TurboCore references, as well as TurboRand methods that return Vec results.
• fmt - Enables core::fmt::Debug implementations for rng::Rng & chacha_rng::ChaChaRng.
• std - Enables std features, such as alloc methods as well as Default implementations for rng::Rng & chacha_rng::ChaChaRng.
• wyrand - Enables rng::Rng, so to provide a basic, non-threadsafe PRNG. Enabled by default. no-std compatible.
• atomic - Enables rng::AtomicRng, so to provide a thread-safe variation of rng::Rng. Enables wyrand feature implicitly. Note, this is slower than rng::Rng.
• rand - Provides compatibility::RandCompat, which implements RngCore so to allow for compatibility with rand ecosystem of crates
• serialize - Enables Serialize and Deserialize derives on rng::Rng, rng::AtomicRng and chacha_rng::ChaChaRng, provided they have their respective features activated as well.
• chacha - Enables chacha_rng::ChaChaRng for providing a more cryptographically secure source of Rng. Note, this will be slower than rng::Rng in throughput, but will produce much higher quality randomness. no-std compatible.

Modules

chacha_rngchacha

A cryptographically secure PRNG (CSPRNG) based on ChaCha8.

compatibilityrand

Compatibility shims for the rand crate ecosystem.

prelude

Convenience re-export of common traits, structs and utils.

rngwyrand or atomic

A fast but not cryptographically secure PRNG based on Wyrand.

Enums

TurboKind

Enum for determining the kind of PRNG, whether a fast one, or a slow, possibly crypographically secure one.

Traits

ForkableCore

Trait for enabling creating new TurboCore instances from an original instance. Similar to cloning, except forking modifies the state of the original instance in order to provide a new, random state for the forked instance. This allows for creating many randomised instances from a single seed in a deterministic manner.

GenCore

This trait provides the means to easily generate all integer types, provided the main method underpinning this is implemented: GenCore::gen. Once implemented, the rest of the trait provides default implementations for generating all integer types, though it is not recommended to override these.

SecureCore

A marker trait to be applied to anything that implements TurboCore in order to indicate that a PRNG source is cryptographically secure, so being a CSPRNG.

SeededCore

Trait for implementing Seedable PRNGs, requiring that the PRNG implements TurboCore as a baseline. Seeds must be Sized in order to be used as the internal state of a PRNG.

TurboCore

Base trait for implementing a PRNG. Only one method must be implemented: TurboCore::fill_bytes, which provides the basis for any PRNG, to fill a buffer of bytes with random data.

TurboRand

Extension trait for automatically implementing all TurboRand methods, as long as the struct implements TurboCore & GenCore. All methods are provided as default implementations that build on top of TurboCore and GenCore, and thus are not recommended to be overridden, lest you potentially change the expected outcome of the methods.