diff --git a/README.md b/README.md index 867a543b91a..6d1db896ddd 100644 --- a/README.md +++ b/README.md @@ -8,19 +8,41 @@ [![API](https://docs.rs/rand/badge.svg)](https://docs.rs/rand) [![Minimum rustc version](https://img.shields.io/badge/rustc-1.36+-lightgray.svg)](https://github.com/rust-random/rand#rust-version-requirements) -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]( -https://crates.io/crates/rand_core) crate but are also exposed here; RNG -implementations should prefer to use `rand_core` while most other users should -depend on `rand`. +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)](https://rust-random.github.io/rand) +- [API reference (master branch)](https://rust-random.github.io/rand) - [API reference (docs.rs)](https://docs.rs/rand) @@ -38,35 +60,36 @@ To get started using Rand, see [The Book](https://rust-random.github.io/book). ## Versions -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. +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). -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: +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.6 was released in November 2018, redesigning the `seq` module, - moving most PRNGs to external crates, and many small changes. -- Version 0.5 was released in May 2018, as a major reorganisation - (introducing `RngCore` and `rand_core`, and deprecating `Rand` and the - previous distribution traits). -- Version 0.4 was released in December 2017, but contained almost no breaking - changes from the 0.3 series. +- The `master` branch is close to 0.8 release. -A detailed [changelog](CHANGELOG.md) is available. +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, diff --git a/appveyor.yml b/appveyor.yml index da50fb87f2f..c7d35ef2b33 100644 --- a/appveyor.yml +++ b/appveyor.yml @@ -34,6 +34,7 @@ build: false test_script: - cargo test --tests --no-default-features - cargo test --tests --no-default-features --features=alloc,getrandom + - cargo test --features simd_support # all stable features: - cargo test --features=serde1,log - cargo test --benches --features=nightly