A Rust library for random number generators and other randomness functionality.

See also:

• rand_core

Documentation: master branch, by release

Add this to your Cargo.toml:

[dependencies]
rand = "0.5.0-pre.0"

and this to your crate root:

extern crate rand;

// example usage:
use rand::{Rng, thread_rng};
let x: f64 = thread_rng().gen();

Version 0.5 is available as a pre-release and contains many breaking changes. See the Upgrade Guide for guidance on updating from previous versions.

Version 0.4 was released in December 2017. It contains almost no breaking changes since the 0.3 series.

For more details, see the changelog.

As of now there is no compatibility shim between Rand 0.4 and 0.5. It is also not entirely obvious how to make one due to the large differences between the two versions, although it would be possible to implement the new RngCore for any implementation of the old Rng (or vice-versa; unfortunately not both as that would result in circular implementation). If we implement a compatibility shim it will be optional (opt-in via a feature).

There is a compatibility shim from 0.3 to 0.4 forcibly upgrading all Rand 0.3 users; this is largely due to the small differences between the two versions.

The 0.5 release of Rand will require Rustc version 1.22 or greater. Rand 0.4 and 0.3 (since approx. June 2017) require Rustc version 1.15 or greater. Subsets of the Rand code may work with older Rust versions, but this is not supported.

Travis CI always has a build with a pinned version of Rustc matching the oldest supported Rust release. The current policy is that this can be updated in any Rand release if required, but the change must be noted in the changelog.

The rand_core crate provides:

• base random number generator traits
• error-reporting types
• functionality to aid implementation of RNGs

The rand crate provides:

• most content from rand_core (re-exported)
• fresh entropy: EntropyRng, OsRng, JitterRng
• pseudo-random number generators: StdRng, SmallRng, prng module
• convenient, auto-seeded crypto-grade thread-local generator: thread_rng
• distributions producing many different types of random values:
  • Uniform-ly distributed integers and floats of many types
  • unbiased sampling from specified Ranges
  • sampling from exponential/normal/gamma distributions
  • sampling from binomial/poisson distributions
  • gen_bool aka Bernoulli distribution
• seq-uence related functionality:
  • sampling a subset of elements
  • randomly shuffling a list

By default, Rand is built with all stable features available. The following optional features are available:

• alloc can be used instead of std to provide Vec and Box
• i128_support enables support for generating u128 and i128 values
• log enables some logging via the log crate
• nightly enables all unstable features (i128_support)
• serde-1 enables serialisation for some types, via Serde version 1
• stdweb enables support for OsRng on WASM via stdweb.
• std enabled by default; by setting "default-features = false" no_std mode is activated; this removes features depending on std 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

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 distributed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE and LICENSE-MIT for details.