vendor/rand/README.md

   1 # Rand
   2
   3 [![Build Status](https://travis-ci.org/rust-random/rand.svg?branch=master)](https://travis-ci.org/rust-random/rand)
   4 [![Build Status](https://ci.appveyor.com/api/projects/status/github/rust-random/rand?svg=true)](https://ci.appveyor.com/project/rust-random/rand)
   5 [![Crate](https://img.shields.io/crates/v/rand.svg)](https://crates.io/crates/rand)
   6 [![Book](https://img.shields.io/badge/book-master-yellow.svg)](https://rust-random.github.io/book/)
   7 [![API](https://img.shields.io/badge/api-master-yellow.svg)](https://rust-random.github.io/rand)
   8 [![API](https://docs.rs/rand/badge.svg)](https://docs.rs/rand)
   9 [![Minimum rustc version](https://img.shields.io/badge/rustc-1.32+-lightgray.svg)](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.7"
  34 ```
  35
  36 To get started using Rand, see [The Book](https://rust-random.github.io/book).
  37
  38
  39 ## Versions
  40
  41 Rand libs have inter-dependencies and make use of the
  42 [semver trick](https://github.com/dtolnay/semver-trick/) in order to make traits
  43 compatible across crate versions. (This is especially important for `RngCore`
  44 and `SeedableRng`.) A few crate releases are thus compatibility shims,
  45 depending 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
  48 cause build errors. Usually, running `cargo update` is enough to fix any issues.
  49
  50 The Rand lib is not yet stable, however we are careful to limit breaking changes
  51 and warn via deprecation wherever possible. Patch versions never introduce
  52 breaking 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
  65 A detailed [changelog](CHANGELOG.md) is available.
  66
  67 When upgrading to the next minor series (especially 0.4 → 0.5), we recommend
  68 reading the [Upgrade Guide](https://rust-random.github.io/book/update.html).
  69
  70 ### Yanked versions
  71
  72 Some versions of Rand crates have been yanked ("unreleased"). Where this occurs,
  73 the crate's CHANGELOG *should* be updated with a rationale, and a search on the
  74 issue tracker with the keyword `yank` *should* uncover the motivation.
  75
  76 ### Rust version requirements
  77
  78 Since version 0.7, Rand requires **Rustc version 1.32 or greater**.
  79 Rand 0.5 requires Rustc 1.22 or greater while versions
  80 0.4 and 0.3 (since approx. June 2017) require Rustc version 1.15 or
  81 greater. Subsets of the Rand code may work with older Rust versions, but this
  82 is not supported.
  83
  84 Travis CI always has a build with a pinned version of Rustc matching the oldest
  85 supported Rust release. The current policy is that this can be updated in any
  86 Rand release if required, but the change must be noted in the changelog.
  87
  88 ## Crate Features
  89
  90 Rand 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
  97 Optionally, 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
 107 Additionally, 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
 114 Rand supports limited functionality in `no_std` mode (enabled via
 115 `default-features = false`). In this case, `OsRng` and `from_entropy` are
 116 unavailable (unless `getrandom` is enabled), large parts of `seq` are
 117 unavailable (unless `alloc` is enabled), and `thread_rng` and `random` are
 118 unavailable.
 119
 120 # License
 121
 122 Rand is distributed under the terms of both the MIT license and the
 123 Apache License (Version 2.0).
 124
 125 See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT), and
 126 [COPYRIGHT](COPYRIGHT) for details.