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### Yanked versions
71
72Some versions of Rand crates have been yanked ("unreleased"). Where this occurs,
73the crate's CHANGELOG *should* be updated with a rationale, and a search on the
74issue tracker with the keyword `yank` *should* uncover the motivation.
75
76### Rust version requirements
77
78Since version 0.7, Rand requires **Rustc version 1.32 or greater**.
79Rand 0.5 requires Rustc 1.22 or greater while versions
800.4 and 0.3 (since approx. June 2017) require Rustc version 1.15 or
81greater. Subsets of the Rand code may work with older Rust versions, but this
82is not supported.
83
84Travis CI always has a build with a pinned version of Rustc matching the oldest
85supported Rust release. The current policy is that this can be updated in any
86Rand release if required, but the change must be noted in the changelog.
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 (when using this feature in `no_std`, Rand requires Rustc version 1.36 or greater)
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 (will be removed in rand 0.8; activate via `getrandom` crate instead)
103- `wasm-bindgen` implies `getrandom/wasm-bindgen` to enable
104 `getrandom` support on `wasm32-unknown-unknown`
105 (will be removed in rand 0.8; activate via `getrandom` crate instead)
106
107Additionally, these features configure Rand:
108
109- `small_rng` enables inclusion of the `SmallRng` PRNG
110- `nightly` enables all experimental features
111- `simd_support` (experimental) enables sampling of SIMD values
112 (uniformly random SIMD integers and floats)
113
114Rand supports limited functionality in `no_std` mode (enabled via
115`default-features = false`). In this case, `OsRng` and `from_entropy` are
116unavailable (unless `getrandom` is enabled), large parts of `seq` are
117unavailable (unless `alloc` is enabled), and `thread_rng` and `random` are
118unavailable.
119
120# License
121
122Rand is distributed under the terms of both the MIT license and the
123Apache License (Version 2.0).
124
125See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
126[COPYRIGHT](COPYRIGHT) for details.
127
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}