README.md
1# Rand
2
3[](https://travis-ci.org/rust-random/rand)
4[](https://ci.appveyor.com/project/rust-random/rand)
5[](https://crates.io/crates/rand)
6[](https://rust-random.github.io/book/)
7[](https://rust-random.github.io/rand)
8[](https://docs.rs/rand)
9[](https://github.com/rust-random/rand#rust-version-requirements)
10
11A Rust library for random number generation.
12
13Rand provides utilities to generate random numbers, to convert them to useful
14types and distributions, and some randomness-related algorithms.
15
16The core random number generation traits of Rand live in the [rand_core](
17https://crates.io/crates/rand_core) crate but are also exposed here; RNG
18implementations should prefer to use `rand_core` while most other users should
19depend on `rand`.
20
21Documentation:
22- [The Rust Rand Book](https://rust-random.github.io/book)
23- [API reference (master)](https://rust-random.github.io/rand)
24- [API reference (docs.rs)](https://docs.rs/rand)
25
26
27## Usage
28
29Add this to your `Cargo.toml`:
30
31```toml
32[dependencies]
33rand = "0.7"
34```
35
36To get started using Rand, see [The Book](https://rust-random.github.io/book).
37
38
39## Versions
40
41Rand libs have inter-dependencies and make use of the
42[semver trick](https://github.com/dtolnay/semver-trick/) in order to make traits
43compatible across crate versions. (This is especially important for `RngCore`
44and `SeedableRng`.) A few crate releases are thus compatibility shims,
45depending on the *next* lib version (e.g. `rand_core` versions `0.2.2` and
46`0.3.1`). This means, for example, that `rand_core_0_4_0::SeedableRng` and
47`rand_core_0_3_0::SeedableRng` are distinct, incompatible traits, which can
48cause build errors. Usually, running `cargo update` is enough to fix any issues.
49
50The Rand lib is not yet stable, however we are careful to limit breaking changes
51and warn via deprecation wherever possible. Patch versions never introduce
52breaking changes. The following minor versions are supported:
53
54- Version 0.7 was released in June 2019, moving most non-uniform distributions
55 to an external crate, moving `from_entropy` to `SeedableRng`, and many small
56 changes and fixes.
57- Version 0.6 was released in November 2018, redesigning the `seq` module,
58 moving most PRNGs to external crates, and many small changes.
59- Version 0.5 was released in May 2018, as a major reorganisation
60 (introducing `RngCore` and `rand_core`, and deprecating `Rand` and the
61 previous distribution traits).
62- Version 0.4 was released in December 2017, but contained almost no breaking
63 changes from the 0.3 series.
64
65A detailed [changelog](CHANGELOG.md) is available.
66
67When upgrading to the next minor series (especially 0.4 → 0.5), we recommend
68reading the [Upgrade Guide](https://rust-random.github.io/book/update.html).
69
70### Rust version requirements
71
72Since version 0.7, Rand requires **Rustc version 1.32 or greater**.
73Rand 0.5 requires Rustc 1.22 or greater while versions
740.4 and 0.3 (since approx. June 2017) require Rustc version 1.15 or
75greater. Subsets of the Rand code may work with older Rust versions, but this
76is not supported.
77
78Travis CI always has a build with a pinned version of Rustc matching the oldest
79supported Rust release. The current policy is that this can be updated in any
80Rand release if required, but the change must be noted in the changelog.
81
82To avoid bumping the required version unnecessarily, we use a `build.rs` script
83to auto-detect the compiler version and enable certain features or change code
84paths automatically. Since this makes it easy to unintentionally make use of
85features requiring a more recent Rust version, we recommend testing with a
86pinned version of Rustc if you require compatibility with a specific version.
87
88## Crate Features
89
90Rand is built with these features enabled by default:
91
92- `std` enables functionality dependent on the `std` lib
93- `alloc` (implied by `std`) enables functionality requiring an allocator
94- `getrandom` (implied by `std`) is an optional dependency providing the code
95 behind `rngs::OsRng`
96
97Optionally, the following dependencies can be enabled:
98
99- `log` enables logging via the `log` crate
100- `stdweb` implies `getrandom/stdweb` to enable
101 `getrandom` support on `wasm32-unknown-unknown`
102- `wasm-bindgen` implies `getrandom/wasm-bindgen` to enable
103 `getrandom` support on `wasm32-unknown-unknown`
104
105Additionally, these features configure Rand:
106
107- `small_rng` enables inclusion of the `SmallRng` PRNG
108- `nightly` enables all experimental features
109- `simd_support` (experimental) enables sampling of SIMD values
110 (uniformly random SIMD integers and floats)
111
112Rand supports limited functionality in `no_std` mode (enabled via
113`default-features = false`). In this case, `OsRng` and `from_entropy` are
114unavailable (unless `getrandom` is enabled), large parts of `seq` are
115unavailable (unless `alloc` is enabled), and `thread_rng` and `random` are
116unavailable.
117
118# License
119
120Rand is distributed under the terms of both the MIT license and the
121Apache License (Version 2.0).
122
123See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
124[COPYRIGHT](COPYRIGHT) for details.
125
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}