diff options
Diffstat (limited to 'third_party/rust/rand/README.md')
| -rw-r--r-- | third_party/rust/rand/README.md | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/third_party/rust/rand/README.md b/third_party/rust/rand/README.md new file mode 100644 index 0000000000..44c2e4d518 --- /dev/null +++ b/third_party/rust/rand/README.md @@ -0,0 +1,158 @@ +# 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.4" +``` + +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 + +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 +- `min_const_gen` enables generating random arrays of + any size using min-const-generics, requiring Rust ≥ 1.51. + +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. + +### WASM support + +The WASM target `wasm32-unknown-unknown` is not *automatically* supported by +`rand` or `getrandom`. To solve this, 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 +[getrandom#WebAssembly support](https://docs.rs/getrandom/latest/getrandom/#webassembly-support). + +# 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. |