projects / rustc.git / blame
| Commit | Line | Data |
|---|---|---|
| 416331ca XL |
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 | ||
| 11 | A Rust library for random number generation. | |
| 12 | ||
| 13 | Rand provides utilities to generate random numbers, to convert them to useful | |
| 14 | types and distributions, and some randomness-related algorithms. | |
| 15 | ||
| 16 | The core random number generation traits of Rand live in the [rand_core]( | |
| 17 | https://crates.io/crates/rand_core) crate but are also exposed here; RNG | |
| 18 | implementations should prefer to use `rand_core` while most other users should | |
| 19 | depend on `rand`. | |
| 20 | ||
| 21 | Documentation: | |
| 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 | ||
| 29 | Add this to your `Cargo.toml`: | |
| 30 | ||
| 31 | ```toml | |
| 32 | [dependencies] | |
| 33 | rand = "0.6" | |
| 34 | ``` | |
| 35 | ||
| 36 | To get started using Rand, see [The Book](https://rust-random.github.io/book). | |
| 37 | ||
| 38 | ||
| 39 | ## Versions | |
| 40 | ||
| 41 | The Rand lib is not yet stable, however we are careful to limit breaking changes | |
| 42 | and warn via deprecation wherever possible. Patch versions never introduce | |
| 43 | breaking 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 | ||
| 53 | A detailed [changelog](CHANGELOG.md) is available. | |
| 54 | ||
| 55 | When upgrading to the next minor series (especially 0.4 → 0.5), we recommend | |
| 56 | reading the [Upgrade Guide](https://rust-random.github.io/book/update.html). | |
| 57 | ||
| 58 | ### Rust version requirements | |
| 59 | ||
| 60 | Since version 0.5, Rand requires **Rustc version 1.22 or greater**. | |
| 61 | Rand 0.4 and 0.3 (since approx. June 2017) require Rustc version 1.15 or | |
| 62 | greater. Subsets of the Rand code may work with older Rust versions, but this | |
| 63 | is not supported. | |
| 64 | ||
| 65 | Travis CI always has a build with a pinned version of Rustc matching the oldest | |
| 66 | supported Rust release. The current policy is that this can be updated in any | |
| 67 | Rand release if required, but the change must be noted in the changelog. | |
| 68 | ||
| 69 | To avoid bumping the required version unnecessarily, we use a `build.rs` script | |
| 70 | to auto-detect the compiler version and enable certain features or change code | |
| 71 | paths automatically. Since this makes it easy to unintentionally make use of | |
| 72 | features requiring a more recent Rust version, we recommend testing with a | |
| 73 | pinned version of Rustc if you require compatibility with a specific version. | |
| 74 | ||
| 75 | ## Crate Features | |
| 76 | ||
| 77 | Rand is built with only the `std` feature enabled by default. The following | |
| 78 | optional features are available: | |
| 79 | ||
| 80 | - `alloc` can be used instead of `std` to provide `Vec` and `Box`. | |
| 81 | - `log` enables some logging via the `log` crate. | |
| 82 | - `nightly` enables all unstable features (`simd_support`). | |
| 83 | - `serde1` enables serialization for some types, via Serde version 1. | |
| 84 | - `simd_support` enables uniform sampling of SIMD types (integers and floats). | |
| 85 | - `stdweb` enables support for `OsRng` on `wasm32-unknown-unknown` via `stdweb` | |
| 86 | combined with `cargo-web`. | |
| 87 | - `wasm-bindgen` enables support for `OsRng` on `wasm32-unknown-unknown` via | |
| 88 | [`wasm-bindgen`] | |
| 89 | ||
| 90 | [`wasm-bindgen`]: https://github.com/rustwasm/wasm-bindgen | |
| 91 | ||
| 92 | `no_std` mode is activated by setting `default-features = false`; this removes | |
| 93 | functionality depending on `std`: | |
| 94 | ||
| 95 | - `thread_rng()`, and `random()` are not available, as they require thread-local | |
| 96 | storage and an entropy source. | |
| 97 | - `OsRng` and `EntropyRng` are unavailable. | |
| 98 | - `JitterRng` code is still present, but a nanosecond timer must be provided via | |
| 99 | `JitterRng::new_with_timer` | |
| 100 | - Since no external entropy is available, it is not possible to create | |
| 101 | generators with fresh seeds using the `FromEntropy` trait (user must provide | |
| 102 | a seed). | |
| 103 | - Several non-linear distributions distributions are unavailable since `exp` | |
| 104 | and `log` functions are not provided in `core`. | |
| 105 | - Large parts of the `seq`-uence module are unavailable, unless the `alloc` | |
| 106 | feature is used (several APIs and many implementations require `Vec`). | |
| 107 | ||
| 108 | ||
| 109 | # License | |
| 110 | ||
| 111 | Rand is distributed under the terms of both the MIT license and the | |
| 112 | Apache License (Version 2.0). | |
| 113 | ||
| 114 | See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and | |
| 115 | [COPYRIGHT](COPYRIGHT) for details. |