A Rust library for random number generators and other randomness functionality.
Add this to your Cargo.toml
:
[dependencies]
rand = "0.4"
and this to your crate root:
extern crate rand;
Version 0.4
was released in December 2017. It contains almost no breaking
changes since the 0.3
series, but nevertheless contains some significant
new code, including a new "external" entropy source (JitterRng
) and no_std
support. Both 0.3 and 0.4 require Rustc version 1.15 or greater.
Version 0.5
is in development and will contain significant breaking changes.
It requires Rustc version 1.22 or greater.
There is built-in support for a random number generator (RNG) associated with each thread stored in thread-local storage. This RNG can be accessed via thread_rng, or used implicitly via random. This RNG is normally randomly seeded from an operating-system source of randomness, e.g. /dev/urandom on Unix systems, and will automatically reseed itself from this source after generating 32 KiB of random data.
let tuple = rand::random::<(f64, char)>();
println!("{:?}", tuple)
use rand::Rng;
let mut rng = rand::thread_rng();
if rng.gen() { // random bool
println!("i32: {}, u32: {}", rng.gen::<i32>(), rng.gen::<u32>())
}
It is also possible to use other RNG types, which have a similar interface. The following uses the "ChaCha" algorithm instead of the default.
use rand::{Rng, ChaChaRng};
let mut rng = rand::ChaChaRng::new_unseeded();
println!("i32: {}, u32: {}", rng.gen::<i32>(), rng.gen::<u32>())
By default, rand
is built with all stable features available. The following
optional features are available:
alloc
can be used instead ofstd
to provideVec
andBox
i128_support
enables support for generatingu128
andi128
valueslog
enables some logging via thelog
cratenightly
enables all unstable features (i128_support
)serde-1
enables serialisation for some types, via Serde version 1std
enabled by default; by setting "default-features = false"no_std
mode is activated; this removes features depending onstd
functionality:OsRng
is entirely unavailableJitterRng
code is still present, but a nanosecond timer must be provided viaJitterRng::new_with_timer
- Since no external entropy is available, it is not possible to create generators with fresh seeds (user must provide entropy)
thread_rng
,weak_rng
andrandom
are all disabled- exponential, normal and gamma type distributions are unavailable
since
exp
andlog
functions are not provided incore
- any code requiring
Vec
orBox
Unfortunately, cargo test
does not test everything. The following tests are
recommended:
# Basic tests for rand and sub-crates
cargo test --all
# Test no_std support
cargo test --tests --no-default-features
# Test no_std+alloc support
cargo test --tests --no-default-features --features alloc
# Test log and serde support
cargo test --features serde-1,log
# Test 128-bit support (requires nightly)
cargo test --all --features nightly
# Benchmarks (requires nightly)
cargo bench
# or just to test the benchmark code:
cargo test --benches
rand
is primarily distributed under the terms of both the MIT
license and the Apache License (Version 2.0).
See LICENSE-APACHE, and LICENSE-MIT for details.