Skip to content

Commit c3c8288

Browse files
dhardydhardy
committed
Move user-guide documentation to the book
1 parent 90e5c2c commit c3c8288

File tree

4 files changed

+30
-493
lines changed

4 files changed

+30
-493
lines changed

‎src/distributions/exponential.rs

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,8 @@ impl Distribution<f64> for Exp1 {
6363
///
6464
/// This distribution has density function: `f(x) = lambda * exp(-lambda * x)`
6565
/// for `x > 0`.
66+
///
67+
/// Note that [`Exp1`](struct.Exp1.html) is an optimised implementation for `lambda = 1`.
6668
///
6769
/// # Example
6870
///

‎src/distributions/normal.rs

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -74,8 +74,11 @@ impl Distribution<f64> for StandardNormal {
7474

7575
/// The normal distribution `N(mean, std_dev**2)`.
7676
///
77-
/// This uses the ZIGNOR variant of the Ziggurat method, see `StandardNormal`
77+
/// This uses the ZIGNOR variant of the Ziggurat method, see [`StandardNormal`]
7878
/// for more details.
79+
///
80+
/// Note that [`StandardNormal`] is an optimised implementation for mean 0, and
81+
/// standard deviation 1.
7982
///
8083
/// # Example
8184
///
@@ -87,6 +90,8 @@ impl Distribution<f64> for StandardNormal {
8790
/// let v = normal.sample(&mut rand::thread_rng());
8891
/// println!("{} is from a N(2, 9) distribution", v)
8992
/// ```
93+
///
94+
/// [`StandardNormal`]: struct.StandardNormal.html
9095
#[derive(Clone, Copy, Debug)]
9196
pub struct Normal {
9297
mean: f64,

‎src/lib.rs

Lines changed: 18 additions & 187 deletions
Original file line numberDiff line numberDiff line change
@@ -12,208 +12,39 @@
1212
//! Rand provides utilities to generate random numbers, to convert them to
1313
//! useful types and distributions, and some randomness-related algorithms.
1414
//!
15-
//! # Basic usage
16-
//!
15+
//! # Quick Start
16+
//!
1717
//! To get you started quickly, the easiest and highest-level way to get
18-
//! a random value is to use [`random()`].
18+
//! a random value is to use [`random()`]; alternatively you can use
19+
//! [`thread_rng()`]. The [`Rng`] trait provides a useful API on all RNGs, while
20+
//! the [`distributions` module] and [`seq` module] provide further
21+
//! functionality on top of RNGs.
1922
//!
2023
//! ```
21-
//! let x: u8 = rand::random(); // generates an integer within u8 bounds
22-
//! println!("{}", x);
23-
//!
24-
//! let y = rand::random::<f64>(); // generates a float between 0 and 1
25-
//! println!("{}", y);
26-
//!
24+
//! use rand::prelude::*;
25+
//!
2726
//! if rand::random() { // generates a boolean
28-
//! println!("Heads!");
27+
//! // Try printing a random unicode code point (probably a bad idea)!
28+
//! println!("char: {}", rand::random::<char>());
2929
//! }
30-
//! ```
31-
//!
32-
//! This supports generating most common types but is not very flexible, thus
33-
//! you probably want to learn a bit more about the Rand library.
34-
//!
35-
//!
36-
//! # The two-step process to get a random value
37-
//!
38-
//! Generating random values is typically a two-step process:
39-
//!
40-
//! - get some *random data* (an integer or bit/byte sequence) from a random
41-
//! number generator (RNG);
42-
//! - use some function to transform that *data* into the type of value you want
43-
//! (this function is an implementation of some *distribution* describing the
44-
//! kind of value produced).
45-
//!
46-
//! Rand represents the first step with the [`RngCore`] trait and the second
47-
//! step via a combination of the [`Rng`] extension trait and the
48-
//! [`distributions` module].
49-
//! In practice you probably won't use [`RngCore`] directly unless you are
50-
//! implementing a random number generator (RNG).
51-
//!
52-
//! There are many kinds of RNGs, with different trade-offs. You can read more
53-
//! about them in the [`rngs` module] and even more in the [`prng` module],
54-
//! however, often you can just use [`thread_rng()`]. This function
55-
//! automatically initializes an RNG in thread-local memory, then returns a
56-
//! reference to it. It is fast, good quality, and secure (unpredictable).
57-
//!
58-
//! To turn the output of the RNG into something usable, you usually want to use
59-
//! the methods from the [`Rng`] trait. Some of the most useful methods are:
60-
//!
61-
//! - [`gen`] generates a random value appropriate for the type (just like
62-
//! [`random()`]). For integers this is normally the full representable range
63-
//! (e.g. from `0u32` to `std::u32::MAX`), for floats this is between 0 and 1,
64-
//! and some other types are supported, including arrays and tuples. See the
65-
//! [`Standard`] distribution which provides the implementations.
66-
//! - [`gen_range`] samples from a specific range of values; this is like
67-
//! [`gen`] but with specific upper and lower bounds.
68-
//! - [`sample`] samples directly from some distribution.
69-
//!
70-
//! [`random()`] is defined using just the above: `thread_rng().gen()`.
71-
//!
72-
//! ## Distributions
73-
//!
74-
//! What are distributions, you ask? Specifying only the type and range of
75-
//! values (known as the *sample space*) is not enough; samples must also have
76-
//! a *probability distribution*, describing the relative probability of
77-
//! sampling each value in that space.
78-
//!
79-
//! In many cases a *uniform* distribution is used, meaning roughly that each
80-
//! value is equally likely (or for "continuous" types like floats, that each
81-
//! equal-sized sub-range has the same probability of containing a sample).
82-
//! [`gen`] and [`gen_range`] both use statistically uniform distributions.
83-
//!
84-
//! The [`distributions` module] provides implementations
85-
//! of some other distributions, including Normal, Log-Normal and Exponential.
86-
//!
87-
//! It is worth noting that the functionality already mentioned is implemented
88-
//! with distributions: [`gen`] samples values using the [`Standard`]
89-
//! distribution, while [`gen_range`] uses [`Uniform`].
90-
//!
91-
//! ## Importing (prelude)
92-
//!
93-
//! The most convenient way to import items from Rand is to use the [prelude].
94-
//! This includes the most important parts of Rand, but only those unlikely to
95-
//! cause name conflicts.
96-
//!
97-
//! Note that Rand 0.5 has significantly changed the module organization and
98-
//! contents relative to previous versions. Where possible old names have been
99-
//! kept (but are hidden in the documentation), however these will be removed
100-
//! in the future. We therefore recommend migrating to use the prelude or the
101-
//! new module organization in your imports.
102-
//!
10330
//!
104-
//! ## Examples
31+
//! let mut rng = rand::thread_rng();
32+
//! let y: f64 = rng.gen(); // generates a float between 0 and 1
10533
//!
34+
//! let nums: Vec<i32> = (1..100).collect();
35+
//! nums.shuffle(&mut rng);
10636
//! ```
107-
//! use rand::prelude::*;
108-
//!
109-
//! // thread_rng is often the most convenient source of randomness:
110-
//! let mut rng = thread_rng();
111-
//!
112-
//! if rng.gen() { // random bool
113-
//! let x: f64 = rng.gen(); // random number in range [0, 1)
114-
//! println!("x is: {}", x);
115-
//! let ch = rng.gen::<char>(); // using type annotation
116-
//! println!("char is: {}", ch);
117-
//! println!("Number from 0 to 9: {}", rng.gen_range(0, 10));
118-
//! }
119-
//! ```
120-
//!
121-
//!
122-
//! # More functionality
123-
//!
124-
//! The [`Rng`] trait includes a few more methods not mentioned above:
125-
//!
126-
//! - [`Rng::sample_iter`] allows iterating over values from a chosen
127-
//! distribution.
128-
//! - [`Rng::gen_bool`] generates boolean "events" with a given probability.
129-
//! - [`Rng::fill`] and [`Rng::try_fill`] are fast alternatives to fill a slice
130-
//! of integers.
131-
//! - [`Rng::shuffle`] randomly shuffles elements in a slice.
132-
//! - [`Rng::choose`] picks one element at random from a slice.
133-
//!
134-
//! For more slice/sequence related functionality, look in the [`seq` module].
135-
//!
136-
//!
137-
//! # Error handling
138-
//!
139-
//! Error handling in Rand is a compromise between simplicity and necessity.
140-
//! Most RNGs and sampling functions will never produce errors, and making these
141-
//! able to handle errors would add significant overhead (to code complexity
142-
//! and ergonomics of usage at least, and potentially also performance,
143-
//! depending on the approach).
144-
//! However, external RNGs can fail, and being able to handle this is important.
145-
//!
146-
//! It has therefore been decided that *most* methods should not return a
147-
//! `Result` type, with as exceptions [`Rng::try_fill`],
148-
//! [`RngCore::try_fill_bytes`], and [`SeedableRng::from_rng`].
149-
//!
150-
//! Note that it is the RNG that panics when it fails but is not used through a
151-
//! method that can report errors. Currently Rand contains only three RNGs that
152-
//! can return an error (and thus may panic), and documents this property:
153-
//! [`OsRng`], [`EntropyRng`] and [`ReadRng`]. Other RNGs, like [`ThreadRng`]
154-
//! and [`StdRng`], can be used with all methods without concern.
155-
//!
156-
//! One further problem is that if Rand is unable to get any external randomness
157-
//! when initializing an RNG with [`EntropyRng`], it will panic in
158-
//! [`FromEntropy::from_entropy`], and notably in [`thread_rng()`]. Except by
159-
//! compromising security, this problem is as unsolvable as running out of
160-
//! memory.
161-
//!
162-
//!
163-
//! # Distinction between Rand and `rand_core`
164-
//!
165-
//! The [`rand_core`] crate provides the necessary traits and functionality for
166-
//! implementing RNGs; this includes the [`RngCore`] and [`SeedableRng`] traits
167-
//! and the [`Error`] type.
168-
//! Crates implementing RNGs should depend on [`rand_core`].
169-
//!
170-
//! Applications and libraries consuming random values are encouraged to use the
171-
//! Rand crate, which re-exports the common parts of [`rand_core`].
172-
//!
173-
//!
174-
//! # More examples
175-
//!
176-
//! For some inspiration, see the examples:
177-
//!
178-
//! - [Monte Carlo estimation of π](
179-
//! https://github.com/rust-random/rand/blob/master/examples/monte-carlo.rs)
180-
//! - [Monty Hall Problem](
181-
//! https://github.com/rust-random/rand/blob/master/examples/monty-hall.rs)
18237
//!
38+
//! # The Book
39+
//!
40+
//! For the user guide and futher documentation, please read
41+
//! [The Rust Rand Book](https://rust-random.github.io/book).
18342
//!
18443
//! [`distributions` module]: distributions/index.html
185-
//! [`FromEntropy::from_entropy`]: trait.FromEntropy.html#tymethod.from_entropy
186-
//! [`EntropyRng`]: rngs/struct.EntropyRng.html
187-
//! [`Error`]: struct.Error.html
188-
//! [`gen_range`]: trait.Rng.html#method.gen_range
189-
//! [`gen`]: trait.Rng.html#method.gen
190-
//! [`OsRng`]: rngs/struct.OsRng.html
191-
//! [prelude]: prelude/index.html
192-
//! [`rand_core`]: https://crates.io/crates/rand_core
19344
//! [`random()`]: fn.random.html
194-
//! [`ReadRng`]: rngs/adapter/struct.ReadRng.html
195-
//! [`Rng::choose`]: trait.Rng.html#method.choose
196-
//! [`Rng::fill`]: trait.Rng.html#method.fill
197-
//! [`Rng::gen_bool`]: trait.Rng.html#method.gen_bool
198-
//! [`Rng::gen`]: trait.Rng.html#method.gen
199-
//! [`Rng::sample_iter`]: trait.Rng.html#method.sample_iter
200-
//! [`Rng::shuffle`]: trait.Rng.html#method.shuffle
201-
//! [`RngCore`]: trait.RngCore.html
202-
//! [`RngCore::try_fill_bytes`]: trait.RngCore.html#method.try_fill_bytes
203-
//! [`rngs` module]: rngs/index.html
204-
//! [`prng` module]: prng/index.html
20545
//! [`Rng`]: trait.Rng.html
206-
//! [`Rng::try_fill`]: trait.Rng.html#method.try_fill
207-
//! [`sample`]: trait.Rng.html#method.sample
208-
//! [`SeedableRng`]: trait.SeedableRng.html
209-
//! [`SeedableRng::from_rng`]: trait.SeedableRng.html#method.from_rng
21046
//! [`seq` module]: seq/index.html
211-
//! [`SmallRng`]: rngs/struct.SmallRng.html
212-
//! [`StdRng`]: rngs/struct.StdRng.html
21347
//! [`thread_rng()`]: fn.thread_rng.html
214-
//! [`ThreadRng`]: rngs/struct.ThreadRng.html
215-
//! [`Standard`]: distributions/struct.Standard.html
216-
//! [`Uniform`]: distributions/struct.Uniform.html
21748
21849

21950
#![doc(html_logo_url = "https://www.rust-lang.org/logos/rust-logo-128x128-blk.png",

0 commit comments

Comments
 (0)