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.6"
34```
35
36To get started using Rand, see [The Book](https://rust-random.github.io/book).
37
38
39## Versions
40
41The Rand lib is not yet stable, however we are careful to limit breaking changes
42and warn via deprecation wherever possible. Patch versions never introduce
43breaking changes. The following minor versions are supported:
44
45- Version 0.6 was released in November 2018, redesigning the `seq` module,
46 moving most PRNGs to external crates, and many small changes.
47- Version 0.5 was released in May 2018, as a major reorganisation
48 (introducing `RngCore` and `rand_core`, and deprecating `Rand` and the
49 previous distribution traits).
50- Version 0.4 was released in December 2017, but contained almost no breaking
51 changes from the 0.3 series.
52
53A detailed [changelog](CHANGELOG.md) is available.
54
55When upgrading to the next minor series (especially 0.4 → 0.5), we recommend
56reading the [Upgrade Guide](https://rust-random.github.io/book/update.html).
57
58### Rust version requirements
59
60Since version 0.5, Rand requires **Rustc version 1.22 or greater**.
61Rand 0.4 and 0.3 (since approx. June 2017) require Rustc version 1.15 or
62greater. Subsets of the Rand code may work with older Rust versions, but this
63is not supported.
64
65Travis CI always has a build with a pinned version of Rustc matching the oldest
66supported Rust release. The current policy is that this can be updated in any
67Rand release if required, but the change must be noted in the changelog.
68
69To avoid bumping the required version unnecessarily, we use a `build.rs` script
70to auto-detect the compiler version and enable certain features or change code
71paths automatically. Since this makes it easy to unintentionally make use of
72features requiring a more recent Rust version, we recommend testing with a
73pinned version of Rustc if you require compatibility with a specific version.
74
75## Crate Features
76
77Rand is built with the `std` and `rand_os` features enabled by default:
78
79- `std` enables functionality dependent on the `std` lib and implies `alloc`
80 and `rand_os`
81- `rand_os` enables the `rand_os` crate, `rngs::OsRng` and enables its usage;
82 the continued existance of this feature is not guaranteed so users are
83 encouraged to specify `std` instead
84
85The following optional features are available:
86
87- `alloc` can be used instead of `std` to provide `Vec` and `Box`.
88- `log` enables some logging via the `log` crate.
89- `nightly` enables all unstable features (`simd_support`).
90- `serde1` enables serialization for some types, via Serde version 1.
91- `simd_support` enables uniform sampling of SIMD types (integers and floats).
92- `stdweb` enables support for `OsRng` on `wasm32-unknown-unknown` via `stdweb`
93 combined with `cargo-web`.
94- `wasm-bindgen` enables support for `OsRng` on `wasm32-unknown-unknown` via
95 [`wasm-bindgen`]
96
97[`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen
98
99`no_std` mode is activated by setting `default-features = false`; this removes
100functionality depending on `std`:
101
102- `thread_rng()`, and `random()` are not available, as they require thread-local
103 storage and an entropy source.
104- `OsRng` and `EntropyRng` are unavailable.
105- `JitterRng` code is still present, but a nanosecond timer must be provided via
106 `JitterRng::new_with_timer`
107- Since no external entropy is available, it is not possible to create
108 generators with fresh seeds using the `FromEntropy` trait (user must provide
109 a seed).
110- Several non-linear distributions distributions are unavailable since `exp`
111 and `log` functions are not provided in `core`.
112- Large parts of the `seq`-uence module are unavailable, unless the `alloc`
113 feature is used (several APIs and many implementations require `Vec`).
114
115
116# License
117
118Rand is distributed under the terms of both the MIT license and the
119Apache License (Version 2.0).
120
121See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
122[COPYRIGHT](COPYRIGHT) for details.
123
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}