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;
The rand
crate has been at version 0.3
since March 2015. If you wish to
avoid all breaking changes you may wish to stick with this version.
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.
Version 0.5
is in development and contains significant performance
improvements for the ISAAC random number generators.
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:
-
i128_support
enables support for generatingu128
andi128
values -
nightly
enables all unstable features (i128_support
) -
std
enabled by default; by setting "default-features = false"no_std
mode is activated; this removes features depending onstd
functionality:- `OsRng` is entirely unavailable - `JitterRng` code is still present, but a nanosecond timer must be provided via `JitterRng::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` and `random` are all disabled - exponential, normal and gamma type distributions are unavailable since `exp` and `log` functions are not provided in `core` - any code requiring `Vec` or `Box`
-
alloc
can be used instead ofstd
to provideVec
andBox
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 (build only since nearly all tests require std)
cargo build --all --no-default-features
# 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
You can derive the Rand
trait for your custom type via the #[derive(Rand)]
directive. To use this first add this to your Cargo.toml:
rand = "0.4"
rand_derive = "0.3"
Next in your crate:
extern crate rand;
#[macro_use]
extern crate rand_derive;
#[derive(Rand, Debug)]
struct MyStruct {
a: i32,
b: u32,
}
fn main() {
println!("{:?}", rand::random::<MyStruct>());
}
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.