A Rust library for random number generation.
Rand provides utilities to generate random numbers, to convert them to useful types and distributions, and some randomness-related algorithms.
The core random number generation traits of Rand live in the rand_core crate but are also exposed here; RNG implementations should prefer to use rand_core
while most other users should depend on rand
.
Documentation:
Add this to your Cargo.toml
:
[dependencies] rand = "0.6"
To get started using Rand, see The Book.
The Rand lib is not yet stable, however we are careful to limit breaking changes and warn via deprecation wherever possible. Patch versions never introduce breaking changes. The following minor versions are supported:
seq
module, moving most PRNGs to external crates, and many small changes.RngCore
and rand_core
, and deprecating Rand
and the previous distribution traits).A detailed changelog is available.
When upgrading to the next minor series (especially 0.4 → 0.5), we recommend reading the Upgrade Guide.
Since version 0.5, Rand requires 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.
To avoid bumping the required version unnecessarily, we use a build.rs
script to auto-detect the compiler version and enable certain features or change code paths automatically. Since this makes it easy to unintentionally make use of features requiring a more recent Rust version, we recommend testing with a pinned version of Rustc if you require compatibility with a specific version.
Rand is built with the std
and rand_os
features enabled by default:
std
enables functionality dependent on the std
lib and implies alloc
and rand_os
rand_os
enables the rand_os
crate, rngs::OsRng
and enables its usage; the continued existance of this feature is not guaranteed so users are encouraged to specify std
insteadThe following optional features are available:
alloc
can be used instead of std
to provide Vec
and Box
.log
enables some logging via the log
crate.nightly
enables all unstable features (simd_support
).serde1
enables serialization for some types, via Serde version 1.simd_support
enables uniform sampling of SIMD types (integers and floats).stdweb
enables support for OsRng
on wasm32-unknown-unknown
via stdweb
combined with cargo-web
.wasm-bindgen
enables support for OsRng
on wasm32-unknown-unknown
via wasm-bindgen
no_std
mode is activated by setting default-features = false
; this removes functionality depending on std
:
thread_rng()
, and random()
are not available, as they require thread-local storage and an entropy source.OsRng
and EntropyRng
are unavailable.JitterRng
code is still present, but a nanosecond timer must be provided via JitterRng::new_with_timer
FromEntropy
trait (user must provide a seed).exp
and log
functions are not provided in core
.seq
-uence module are unavailable, unless the alloc
feature is used (several APIs and many implementations require Vec
).Rand is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE-APACHE and LICENSE-MIT, and COPYRIGHT for details.