2018-03-25 08:40:31 +00:00
# Rand
2020-12-08 11:57:26 +00:00
[![Test Status ](https://github.com/rust-random/rand/workflows/Tests/badge.svg?event=push )](https://github.com/rust-random/rand/actions)
2018-11-22 19:27:08 +00:00
[![Crate ](https://img.shields.io/crates/v/rand.svg )](https://crates.io/crates/rand)
[![Book ](https://img.shields.io/badge/book-master-yellow.svg )](https://rust-random.github.io/book/)
2020-12-14 14:59:52 +00:00
[![API ](https://img.shields.io/badge/api-master-yellow.svg )](https://rust-random.github.io/rand/rand)
2018-11-22 19:27:08 +00:00
[![API ](https://docs.rs/rand/badge.svg )](https://docs.rs/rand)
2015-02-03 05:57:35 +00:00
2024-10-01 13:59:11 +00:00
Rand is a Rust library supporting random generators:
2020-11-19 10:22:12 +00:00
2024-10-01 13:59:11 +00:00
- A standard RNG trait: [`rand_core::RngCore` ](https://docs.rs/rand_core/latest/rand_core/trait.RngCore.html )
2020-11-19 10:22:12 +00:00
- Fast implementations of the best-in-class [cryptographic ](https://rust-random.github.io/book/guide-rngs.html#cryptographically-secure-pseudo-random-number-generators-csprngs ) and
2024-10-01 13:59:11 +00:00
[non-cryptographic ](https://rust-random.github.io/book/guide-rngs.html#basic-pseudo-random-number-generators-prngs ) generators: [`rand::rngs` ](https://docs.rs/rand/latest/rand/rngs/index.html ), and more RNGs: [`rand_chacha` ](https://docs.rs/rand_chacha ), [`rand_xoshiro` ](https://docs.rs/rand_xoshiro/ ), [`rand_pcg` ](https://docs.rs/rand_pcg/ ), [rngs repo ](https://github.com/rust-random/rngs/ )
2024-10-11 07:51:21 +00:00
- [`rand::rng` ](https://docs.rs/rand/latest/rand/fn.rng.html ) is an asymtotically-fast, reasonably secure generator available on all `std` targets
2024-10-01 13:59:11 +00:00
- Secure seeding via the [`getrandom` crate ](https://crates.io/crates/getrandom )
Supporting random value generation and random processes:
- [`Standard` ](https://docs.rs/rand/latest/rand/distributions/struct.Standard.html ) random value generation
- Ranged [`Uniform` ](https://docs.rs/rand/latest/rand/distributions/struct.Uniform.html ) number generation for many types
2024-07-23 13:14:11 +00:00
- A flexible [`distributions` ](https://docs.rs/rand/*/rand/distr/index.html ) module
2020-11-19 10:22:12 +00:00
- Samplers for a large number of random number distributions via our own
[`rand_distr` ](https://docs.rs/rand_distr ) and via
the [`statrs` ](https://docs.rs/statrs/0.13.0/statrs/ )
2024-10-01 13:59:11 +00:00
- Random processes (mostly choose and shuffle) via [`rand::seq` ](https://docs.rs/rand/latest/rand/seq/index.html ) traits
All with:
2020-11-19 10:22:12 +00:00
- [Portably reproducible output ](https://rust-random.github.io/book/portability.html )
- `#[no_std]` compatibility (partial)
- *Many* performance optimisations
2024-10-01 13:59:11 +00:00
It's also worth pointing out what Rand *is not* :
2020-11-19 10:22:12 +00:00
- Small. Most low-level crates are small, but the higher-level `rand` and
`rand_distr` each contain a lot of functionality.
- Simple (implementation). We have a strong focus on correctness, speed and flexibility, but
not simplicity. If you prefer a small-and-simple library, there are
alternatives including [fastrand ](https://crates.io/crates/fastrand )
and [oorandom ](https://crates.io/crates/oorandom ).
- Slow. We take performance seriously, with considerations also for set-up
time of new distributions, commonly-used parameters, and parameters of the
current sampler.
2018-03-23 15:37:31 +00:00
2018-07-09 17:15:13 +00:00
Documentation:
2020-11-19 10:22:12 +00:00
2018-11-22 19:27:08 +00:00
- [The Rust Rand Book ](https://rust-random.github.io/book )
2020-11-19 10:22:12 +00:00
- [API reference (master branch) ](https://rust-random.github.io/rand )
2018-11-22 19:27:08 +00:00
- [API reference (docs.rs) ](https://docs.rs/rand )
2018-07-09 17:15:13 +00:00
2015-02-03 05:57:35 +00:00
## Usage
Add this to your `Cargo.toml` :
```toml
[dependencies]
2022-02-14 08:38:55 +00:00
rand = "0.8.5"
2015-02-03 05:57:35 +00:00
```
2018-11-22 19:27:08 +00:00
To get started using Rand, see [The Book ](https://rust-random.github.io/book ).
2018-05-11 08:42:10 +00:00
2018-03-11 12:07:24 +00:00
## Versions
2017-12-11 16:39:13 +00:00
2020-11-19 10:22:12 +00:00
Rand is *mature* (suitable for general usage, with infrequent breaking releases
2024-03-25 14:56:17 +00:00
which minimise breakage) but not yet at 1.0. Current versions are:
2018-11-08 18:12:01 +00:00
2020-12-14 16:04:34 +00:00
- Version 0.8 was released in December 2020 with many small changes.
2024-03-25 14:56:17 +00:00
- Version 0.9 is in development with many small changes.
2018-01-02 14:35:06 +00:00
2024-03-25 14:56:17 +00:00
See the [CHANGELOG ](CHANGELOG.md ) or [Upgrade Guide ](https://rust-random.github.io/book/update.html ) for more details.
2017-12-11 16:39:13 +00:00
2018-03-23 15:37:31 +00:00
## Crate Features
2017-12-14 16:36:28 +00:00
2019-05-07 08:57:43 +00:00
Rand is built with these features enabled by default:
2017-12-14 16:36:28 +00:00
2019-05-07 08:57:43 +00:00
- `std` enables functionality dependent on the `std` lib
2020-03-09 15:22:13 +00:00
- `alloc` (implied by `std` ) enables functionality requiring an allocator
2019-05-07 08:57:43 +00:00
- `getrandom` (implied by `std` ) is an optional dependency providing the code
behind `rngs::OsRng`
2024-10-11 07:51:21 +00:00
- `std_rng` enables inclusion of `StdRng` , `ThreadRng`
2019-05-07 08:57:43 +00:00
Optionally, the following dependencies can be enabled:
2024-03-25 14:56:17 +00:00
- `log` enables logging via [log ](https://crates.io/crates/log )
2019-05-07 08:57:43 +00:00
Additionally, these features configure Rand:
2019-05-13 10:18:52 +00:00
- `small_rng` enables inclusion of the `SmallRng` PRNG
2022-08-05 08:30:05 +00:00
- `nightly` includes some additions requiring nightly Rust
2019-05-07 08:57:43 +00:00
- `simd_support` (experimental) enables sampling of SIMD values
2020-09-22 14:59:16 +00:00
(uniformly random SIMD integers and floats), requiring nightly Rust
2020-09-22 18:05:04 +00:00
Note that nightly features are not stable and therefore not all library and
compiler versions will be compatible. This is especially true of Rand's
experimental `simd_support` feature.
2019-05-07 08:57:43 +00:00
Rand supports limited functionality in `no_std` mode (enabled via
2024-05-08 13:10:32 +00:00
`default-features = false` ). In this case, `OsRng` and `from_os_rng` are
2019-05-07 08:57:43 +00:00
unavailable (unless `getrandom` is enabled), large parts of `seq` are
2024-10-11 07:51:21 +00:00
unavailable (unless `alloc` is enabled), and `ThreadRng` is unavailable.
2017-06-14 19:22:22 +00:00
2024-03-25 14:56:17 +00:00
## Portability and platform support
Many (but not all) algorithms are intended to have reproducible output. Read more in the book: [Portability ](https://rust-random.github.io/book/portability.html ).
The Rand library supports a variety of CPU architectures. Platform integration is outsourced to [getrandom ](https://docs.rs/getrandom/latest/getrandom/ ).
2021-05-31 16:43:57 +00:00
### WASM support
2022-08-14 07:59:12 +00:00
Seeding entropy from OS on WASM target `wasm32-unknown-unknown` is not
*automatically* supported by `rand` or `getrandom` . If you are fine with
seeding the generator manually, you can disable the `getrandom` feature
and use the methods on the `SeedableRng` trait. To enable seeding from OS,
either use a different target such as `wasm32-wasi` or add a direct
dependency on `getrandom` with the `js` feature (if the target supports
JavaScript). See
2021-05-31 16:43:57 +00:00
[getrandom#WebAssembly support ](https://docs.rs/getrandom/latest/getrandom/#webassembly-support ).
2017-06-14 19:22:22 +00:00
# License
2018-05-11 08:42:10 +00:00
Rand is distributed under the terms of both the MIT license and the
Apache License (Version 2.0).
2017-06-14 19:22:22 +00:00
2018-08-24 08:22:35 +00:00
See [LICENSE-APACHE ](LICENSE-APACHE ) and [LICENSE-MIT ](LICENSE-MIT ), and
[COPYRIGHT ](COPYRIGHT ) for details.