[−][src]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::<u64>(1, 100));
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
, orrandomize
- 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 ) | 🚫 | 8.6 GB/s | https://github.com/lemire/testingRNG/blob/master/source/wyrand.h | |
Pcg64 | nanorand::Pcg64 | 64 bits (u64 ) | 🚫 | 2.3 GB/s | https://github.com/rkern/pcg64 | |
ChaCha | nanorand::ChaCha | 512 bits ([u32; 16] ) | ✅ | 140 MB/s (ChaCha8), 70 MB/s (ChaCha20) | Only works in Rust 1.47 or above | https://cr.yp.to/chacha.html |
1. Speed benchmarked on an Intel Core i7 8086k processor running at 5.1 GHz
Entropy Sources
Listed in order of priority
- If the
getrandom
feature is enabled, then getrandom::getrandom will be called. - 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 - Unix-like systems (Linux, macOS, iOS, BSD, Android)
- We will first attempt to source random bytes from
/dev/urandom
- If that fails, we will resort to
/dev/random
- We will first attempt to source random bytes from
- 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
.
- If we're targeting UWP, then the
- If all else fails, and the
std
feature is enabled, we'll resort to pulling bytes from the current system unix time (entropy::emergency_system_time_entropy), and screwing with them via XOR and endianness operations.
Feature Flags
std
(default) - Enables Ruststd
lib features, such as seeding from OS entropy sources.tls
(default) - Enables a thread-local WyRand RNG (see below). Requirestls
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/x86_64 platforms, therdseed
intrinsic will be used when OS entropy isn't available.zeroize
- Implement the Zeroize trait for all RNGs.getrandom
- Use thegetrandom
crate as an entropy source. Works on most systems, optional due to the fact that it brings in more dependencies.
Re-exports
pub use gen::*; |
pub use rand::*; |
pub use tls::tls_rng; |
Modules
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. |