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
82## Crate Features
83
84Rand is built with these features enabled by default:
85
86- `std` enables functionality dependent on the `std` lib
87- `alloc` (implied by `std`) enables functionality requiring an allocator (when using this feature in `no_std`, Rand requires Rustc version 1.36 or greater)
88- `getrandom` (implied by `std`) is an optional dependency providing the code
89 behind `rngs::OsRng`
90
91Optionally, the following dependencies can be enabled:
92
93- `log` enables logging via the `log` crate
94- `stdweb` implies `getrandom/stdweb` to enable
95 `getrandom` support on `wasm32-unknown-unknown`
96 (will be removed in rand 0.8; activate via `getrandom` crate instead)
97- `wasm-bindgen` implies `getrandom/wasm-bindgen` to enable
98 `getrandom` support on `wasm32-unknown-unknown`
99 (will be removed in rand 0.8; activate via `getrandom` crate instead)
100
101Additionally, these features configure Rand:
102
103- `small_rng` enables inclusion of the `SmallRng` PRNG
104- `nightly` enables all experimental features
105- `simd_support` (experimental) enables sampling of SIMD values
106 (uniformly random SIMD integers and floats)
107
108Rand supports limited functionality in `no_std` mode (enabled via
109`default-features = false`). In this case, `OsRng` and `from_entropy` are
110unavailable (unless `getrandom` is enabled), large parts of `seq` are
111unavailable (unless `alloc` is enabled), and `thread_rng` and `random` are
112unavailable.
113
114# License
115
116Rand is distributed under the terms of both the MIT license and the
117Apache License (Version 2.0).
118
119See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
120[COPYRIGHT](COPYRIGHT) for details.
121
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}