Crate nanorand

A library meant for fast, random number generation with quick compile time, and minimal dependencies.

Examples

Generating a number with an initialized RNG

use nanorand::{Rng, WyRand};

let mut rng = WyRand::new();
println!("Random number: {}", rng.generate::<u64>());

Generating a number with a thread-local RNG

use nanorand::Rng;

let mut rng = nanorand::tls_rng();
println!("Random number: {}", rng.generate::<u64>());

Generating a number in a range

use nanorand::{Rng, WyRand};

let mut rng = WyRand::new();
println!("Random number between 1 and 100: {}", rng.generate_range(1_u64..=100));
println!("Random number between -100 and 50: {}", rng.generate_range(-100_i64..=50));

Buffering random bytes

use nanorand::{Rng, BufferedRng, WyRand};

let mut thingy = [0u8; 5];
let mut rng = BufferedRng::new(WyRand::new());
rng.fill(&mut thingy);
// As WyRand generates 8 bytes of output, and our target is only 5 bytes,
// 3 bytes will remain in the buffer.
assert_eq!(rng.buffered(), 3);

Shuffling a Vec

use nanorand::{Rng, WyRand};

let mut rng = WyRand::new();
let mut items = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
rng.shuffle(&mut items);

Why should I use this over…

• rand - The standard rand crate is a complex beast. It contains unsafe code in the core implementations, and while it has much more options than we do, that’s kind of the point. We’re straight to the point, while rand is everything and the kitchen sink.
• fastrand, oorandom, random-fast-rng, or randomize - These are all minimal, zero-dep implementations of the PCG family of RNGs (Pcg32 and Pcg64). While these are decent, they are much slower than wyrand (which beats the speed of these Pcg32 implementations while providing 64 random bits), and do not provide CSPRNGs.
• getrandom - The getrandom crate just provides OS entropy sources. It is not meant for random number generation. In fact, we provide it as an optional entropy source.

RNG Implementations

RNG	nanorand type	Output Size	Cryptographically Secure	Speed1	Notes	Original Implementation
wyrand	nanorand::WyRand, nanorand::tls::TlsWyRand	64 bits (u64)	🚫	16.4 GB/s		https://github.com/lemire/testingRNG/blob/master/source/wyrand.h
Pcg64	nanorand::Pcg64	64 bits (u64)	🚫	1.6 GB/s		https://github.com/rkern/pcg64
ChaCha	nanorand::ChaCha	512 bits ([u32; 16])	✅	204 MB/s (ChaCha8), 79 MB/s (ChaCha20)	Only works in Rust 1.47 or above	https://cr.yp.to/chacha.html

^{1. Speed benchmarked on an M1 Macbook Air}

Entropy Sources

Listed in order of priority

• If the getrandom feature is enabled, then getrandom::getrandom will be called, and no other entropy sources will be used.
• If the rdseed feature is enabled, and is running on an x86(-64) system with the RDSEED instruction, then we will attempt to source as much entropy as possible via our rdseed_entropy function
• Linux and Android will attempt to use the getrandom syscall.
• macOS and iOS (Darwin-based systems) will use Security.framework’s SecRandomCopyBytes.
• Windows
  • If we’re targeting UWP, then the BCryptGenRandom is used with system-preferred RNG (BCRYPT_USE_SYSTEM_PREFERRED_RNG).
  • Otherwise, we’ll use RtlGenRandom.

Feature Flags

• alloc (default) - Enables Rust alloc lib features, such as a buffering Rng wrapper.
• std (default) - Enables Rust std lib features, such as seeding from OS entropy sources. Requires alloc to be enabled.
• tls (default) - Enables a thread-local WyRand RNG (see below). Requires std to be enabled.
• wyrand (default) - Enable the WyRand RNG.
• pcg64 (default) - Enable the Pcg64 RNG.
• chacha - Enable the ChaCha RNG. Requires Rust 1.47 or later.
• rdseed - On x86 and x86-64 platforms, the rdseed intrinsic will be used when OS entropy isn’t available.
• zeroize - Implement the Zeroize trait for all RNGs.
• getrandom - Use the getrandom crate as an entropy source. Works on most systems, optional due to the fact that it brings in more dependencies.

MSRV

The minimum supported Rust version for the latest version of nanorand is Rust 1.56.0, released October 21st, 2021.

Re-exports

• pub use buffer::BufferedRng;
• pub use tls::tls_rng;
• pub use gen::*;
• pub use rand::*;

Modules

• buffer
  Provides a buffered wrapper for RNGs, preventing bits from being wasted.
• crypto
  Implementation of cryptography, for CSPRNGs.
• entropy
  Sources for obtaining entropy.
• gen
  Traits for generating types from an RNG.
• rand
  RNG algorithms.
• tls
  Provides a thread-local WyRand RNG.