You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
149 lines
6.9 KiB
149 lines
6.9 KiB
# Rand
|
|
|
|
[](https://github.com/rust-random/rand/actions)
|
|
[](https://crates.io/crates/rand)
|
|
[](https://rust-random.github.io/book/)
|
|
[](https://rust-random.github.io/rand/rand)
|
|
[](https://docs.rs/rand)
|
|
[](https://github.com/rust-random/rand#rust-version-requirements)
|
|
|
|
A Rust library for random number generation, featuring:
|
|
|
|
- Easy random value generation and usage via the [`Rng`](https://docs.rs/rand/*/rand/trait.Rng.html),
|
|
[`SliceRandom`](https://docs.rs/rand/*/rand/seq/trait.SliceRandom.html) and
|
|
[`IteratorRandom`](https://docs.rs/rand/*/rand/seq/trait.IteratorRandom.html) traits
|
|
- Secure seeding via the [`getrandom` crate](https://crates.io/crates/getrandom)
|
|
and fast, convenient generation via [`thread_rng`](https://docs.rs/rand/*/rand/fn.thread_rng.html)
|
|
- A modular design built over [`rand_core`](https://crates.io/crates/rand_core)
|
|
([see the book](https://rust-random.github.io/book/crates.html))
|
|
- 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
|
|
[non-cryptographic](https://rust-random.github.io/book/guide-rngs.html#basic-pseudo-random-number-generators-prngs) generators
|
|
- A flexible [`distributions`](https://docs.rs/rand/*/rand/distributions/index.html) module
|
|
- 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/)
|
|
- [Portably reproducible output](https://rust-random.github.io/book/portability.html)
|
|
- `#[no_std]` compatibility (partial)
|
|
- *Many* performance optimisations
|
|
|
|
It's also worth pointing out what `rand` *is not*:
|
|
|
|
- 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.
|
|
|
|
Documentation:
|
|
|
|
- [The Rust Rand Book](https://rust-random.github.io/book)
|
|
- [API reference (master branch)](https://rust-random.github.io/rand)
|
|
- [API reference (docs.rs)](https://docs.rs/rand)
|
|
|
|
|
|
## Usage
|
|
|
|
Add this to your `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
rand = "0.8.0"
|
|
```
|
|
|
|
To get started using Rand, see [The Book](https://rust-random.github.io/book).
|
|
|
|
|
|
## Versions
|
|
|
|
Rand is *mature* (suitable for general usage, with infrequent breaking releases
|
|
which minimise breakage) but not yet at 1.0. We maintain compatibility with
|
|
pinned versions of the Rust compiler (see below).
|
|
|
|
Current Rand versions are:
|
|
|
|
- Version 0.7 was released in June 2019, moving most non-uniform distributions
|
|
to an external crate, moving `from_entropy` to `SeedableRng`, and many small
|
|
changes and fixes.
|
|
- Version 0.8 was released in December 2020 with many small changes.
|
|
|
|
A detailed [changelog](CHANGELOG.md) is available for releases.
|
|
|
|
When upgrading to the next minor series (especially 0.4 → 0.5), we recommend
|
|
reading the [Upgrade Guide](https://rust-random.github.io/book/update.html).
|
|
|
|
Rand has not yet reached 1.0 implying some breaking changes may arrive in the
|
|
future ([SemVer](https://semver.org/) allows each 0.x.0 release to include
|
|
breaking changes), but is considered *mature*: breaking changes are minimised
|
|
and breaking releases are infrequent.
|
|
|
|
Rand libs have inter-dependencies and make use of the
|
|
[semver trick](https://github.com/dtolnay/semver-trick/) in order to make traits
|
|
compatible across crate versions. (This is especially important for `RngCore`
|
|
and `SeedableRng`.) A few crate releases are thus compatibility shims,
|
|
depending on the *next* lib version (e.g. `rand_core` versions `0.2.2` and
|
|
`0.3.1`). This means, for example, that `rand_core_0_4_0::SeedableRng` and
|
|
`rand_core_0_3_0::SeedableRng` are distinct, incompatible traits, which can
|
|
cause build errors. Usually, running `cargo update` is enough to fix any issues.
|
|
|
|
### Yanked versions
|
|
|
|
Some versions of Rand crates have been yanked ("unreleased"). Where this occurs,
|
|
the crate's CHANGELOG *should* be updated with a rationale, and a search on the
|
|
issue tracker with the keyword `yank` *should* uncover the motivation.
|
|
|
|
### Rust version requirements
|
|
|
|
Since version 0.8, Rand requires **Rustc version 1.36 or greater**.
|
|
Rand 0.7 requires Rustc 1.32 or greater while versions 0.5 require Rustc 1.22 or
|
|
greater, and 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.
|
|
|
|
Continuous Integration (CI) will always test the minimum supported Rustc version
|
|
(the MSRV). The current policy is that this can be updated in any
|
|
Rand release if required, but the change must be noted in the changelog.
|
|
|
|
## Crate Features
|
|
|
|
Rand is built with these features enabled by default:
|
|
|
|
- `std` enables functionality dependent on the `std` lib
|
|
- `alloc` (implied by `std`) enables functionality requiring an allocator
|
|
- `getrandom` (implied by `std`) is an optional dependency providing the code
|
|
behind `rngs::OsRng`
|
|
- `std_rng` enables inclusion of `StdRng`, `thread_rng` and `random`
|
|
(the latter two *also* require that `std` be enabled)
|
|
|
|
Optionally, the following dependencies can be enabled:
|
|
|
|
- `log` enables logging via the `log` crate` crate
|
|
|
|
Additionally, these features configure Rand:
|
|
|
|
- `small_rng` enables inclusion of the `SmallRng` PRNG
|
|
- `nightly` enables some optimizations requiring nightly Rust
|
|
- `simd_support` (experimental) enables sampling of SIMD values
|
|
(uniformly random SIMD integers and floats), requiring nightly Rust
|
|
|
|
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.
|
|
|
|
Rand supports limited functionality in `no_std` mode (enabled via
|
|
`default-features = false`). In this case, `OsRng` and `from_entropy` are
|
|
unavailable (unless `getrandom` is enabled), large parts of `seq` are
|
|
unavailable (unless `alloc` is enabled), and `thread_rng` and `random` are
|
|
unavailable.
|
|
|
|
# License
|
|
|
|
Rand is distributed under the terms of both the MIT license and the
|
|
Apache License (Version 2.0).
|
|
|
|
See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
|
|
[COPYRIGHT](COPYRIGHT) for details.
|