Skip to content

Commit 131035e

Browse files
dhardydhardy
committed
Tweak distributions module doc and remove examples
The examples caused deprecation warnings and are no longer needed
1 parent 637e214 commit 131035e

13 files changed

+46
-290
lines changed

‎src/distributions/binomial.rs

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,6 @@ use distributions::utils::log_gamma;
1818
///
1919
/// This distribution has density function:
2020
/// `f(k) = n!/(k! (n-k)!) p^k (1-p)^(n-k)` for `k >= 0`.
21-
///
22-
/// # Example
23-
///
24-
/// ```
25-
/// use rand::distributions::{Binomial, Distribution};
26-
///
27-
/// let bin = Binomial::new(20, 0.3);
28-
/// let v = bin.sample(&mut rand::thread_rng());
29-
/// println!("{} is from a binomial distribution", v);
30-
/// ```
3121
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
3222
#[derive(Clone, Copy, Debug)]
3323
pub struct Binomial {

‎src/distributions/cauchy.rs

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,16 +18,6 @@ use std::f64::consts::PI;
1818
///
1919
/// This distribution has a density function:
2020
/// `f(x) = 1 / (pi * scale * (1 + ((x - median) / scale)^2))`
21-
///
22-
/// # Example
23-
///
24-
/// ```
25-
/// use rand::distributions::{Cauchy, Distribution};
26-
///
27-
/// let cau = Cauchy::new(2.0, 5.0);
28-
/// let v = cau.sample(&mut rand::thread_rng());
29-
/// println!("{} is from a Cauchy(2, 5) distribution", v);
30-
/// ```
3121
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
3222
#[derive(Clone, Copy, Debug)]
3323
pub struct Cauchy {

‎src/distributions/dirichlet.rs

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -19,18 +19,6 @@ use distributions::gamma::Gamma;
1919
/// The Dirichlet distribution is a family of continuous multivariate
2020
/// probability distributions parameterized by a vector alpha of positive reals.
2121
/// It is a multivariate generalization of the beta distribution.
22-
///
23-
/// # Example
24-
///
25-
/// ```
26-
/// use rand::prelude::*;
27-
/// use rand::distributions::Dirichlet;
28-
///
29-
/// let dirichlet = Dirichlet::new(vec![1.0, 2.0, 3.0]);
30-
/// let samples = dirichlet.sample(&mut rand::thread_rng());
31-
/// println!("{:?} is from a Dirichlet([1.0, 2.0, 3.0]) distribution", samples);
32-
/// ```
33-
3422
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
3523
#[derive(Clone, Debug)]
3624
pub struct Dirichlet {

‎src/distributions/exponential.rs

Lines changed: 0 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,6 @@ use distributions::utils::ziggurat;
2828
/// Generate Normal Random Samples*](
2929
/// https://www.doornik.com/research/ziggurat.pdf).
3030
/// Nuffield College, Oxford
31-
///
32-
/// # Example
33-
/// ```
34-
/// use rand::prelude::*;
35-
/// use rand::distributions::Exp1;
36-
///
37-
/// let val: f64 = SmallRng::from_entropy().sample(Exp1);
38-
/// println!("{}", val);
39-
/// ```
4031
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
4132
#[derive(Clone, Copy, Debug)]
4233
pub struct Exp1;
@@ -67,16 +58,6 @@ impl Distribution<f64> for Exp1 {
6758
/// for `x > 0`.
6859
///
6960
/// Note that [`Exp1`][crate::distributions::Exp1] is an optimised implementation for `lambda = 1`.
70-
///
71-
/// # Example
72-
///
73-
/// ```
74-
/// use rand::distributions::{Exp, Distribution};
75-
///
76-
/// let exp = Exp::new(2.0);
77-
/// let v = exp.sample(&mut rand::thread_rng());
78-
/// println!("{} is from a Exp(2) distribution", v);
79-
/// ```
8061
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
8162
#[derive(Clone, Copy, Debug)]
8263
pub struct Exp {

‎src/distributions/gamma.rs

Lines changed: 0 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -33,16 +33,6 @@ use distributions::{Distribution, Exp, Open01};
3333
/// == 1`, and using the boosting technique described in that paper for
3434
/// `shape < 1`.
3535
///
36-
/// # Example
37-
///
38-
/// ```
39-
/// use rand::distributions::{Distribution, Gamma};
40-
///
41-
/// let gamma = Gamma::new(2.0, 5.0);
42-
/// let v = gamma.sample(&mut rand::thread_rng());
43-
/// println!("{} is from a Gamma(2, 5) distribution", v);
44-
/// ```
45-
///
4636
/// [^1]: George Marsaglia and Wai Wan Tsang. 2000. "A Simple Method for
4737
/// Generating Gamma Variables" *ACM Trans. Math. Softw.* 26, 3
4838
/// (September 2000), 363-372.
@@ -176,16 +166,6 @@ impl Distribution<f64> for GammaLargeShape {
176166
/// of `k` independent standard normal random variables. For other
177167
/// `k`, this uses the equivalent characterisation
178168
/// `χ²(k) = Gamma(k/2, 2)`.
179-
///
180-
/// # Example
181-
///
182-
/// ```
183-
/// use rand::distributions::{ChiSquared, Distribution};
184-
///
185-
/// let chi = ChiSquared::new(11.0);
186-
/// let v = chi.sample(&mut rand::thread_rng());
187-
/// println!("{} is from a χ²(11) distribution", v)
188-
/// ```
189169
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
190170
#[derive(Clone, Copy, Debug)]
191171
pub struct ChiSquared {
@@ -232,16 +212,6 @@ impl Distribution<f64> for ChiSquared {
232212
/// This distribution is equivalent to the ratio of two normalised
233213
/// chi-squared distributions, that is, `F(m,n) = (χ²(m)/m) /
234214
/// (χ²(n)/n)`.
235-
///
236-
/// # Example
237-
///
238-
/// ```
239-
/// use rand::distributions::{FisherF, Distribution};
240-
///
241-
/// let f = FisherF::new(2.0, 32.0);
242-
/// let v = f.sample(&mut rand::thread_rng());
243-
/// println!("{} is from an F(2, 32) distribution", v)
244-
/// ```
245215
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
246216
#[derive(Clone, Copy, Debug)]
247217
pub struct FisherF {
@@ -274,16 +244,6 @@ impl Distribution<f64> for FisherF {
274244

275245
/// The Student t distribution, `t(nu)`, where `nu` is the degrees of
276246
/// freedom.
277-
///
278-
/// # Example
279-
///
280-
/// ```
281-
/// use rand::distributions::{StudentT, Distribution};
282-
///
283-
/// let t = StudentT::new(11.0);
284-
/// let v = t.sample(&mut rand::thread_rng());
285-
/// println!("{} is from a t(11) distribution", v)
286-
/// ```
287247
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
288248
#[derive(Clone, Copy, Debug)]
289249
pub struct StudentT {
@@ -310,16 +270,6 @@ impl Distribution<f64> for StudentT {
310270
}
311271

312272
/// The Beta distribution with shape parameters `alpha` and `beta`.
313-
///
314-
/// # Example
315-
///
316-
/// ```
317-
/// use rand::distributions::{Distribution, Beta};
318-
///
319-
/// let beta = Beta::new(2.0, 5.0);
320-
/// let v = beta.sample(&mut rand::thread_rng());
321-
/// println!("{} is from a Beta(2, 5) distribution", v);
322-
/// ```
323273
#[deprecated(since="0.7.0", note="moved to rand_distr crate")]
324274
#[derive(Clone, Copy, Debug)]
325275
pub struct Beta {

‎src/distributions/mod.rs

Lines changed: 46 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,12 @@
77
// option. This file may not be copied, modified, or distributed
88
// except according to those terms.
99

10-
//! Generating random samples from probability distributions.
10+
//! Generating random samples from probability distributions
1111
//!
1212
//! This module is the home of the [`Distribution`] trait and several of its
1313
//! implementations. It is the workhorse behind some of the convenient
14-
//! functionality of the [`Rng`] trait, including [`gen`], [`gen_range`] and
15-
//! of course [`sample`].
14+
//! functionality of the [`Rng`] trait, e.g. [`Rng::gen`], [`Rng::gen_range`] and
15+
//! of course [`Rng::sample`].
1616
//!
1717
//! Abstractly, a [probability distribution] describes the probability of
1818
//! occurance of each value in its sample space.
@@ -40,8 +40,14 @@
4040
//! possible to generate type `T` with [`Rng::gen()`], and by extension also
4141
//! with the [`random()`] function.
4242
//!
43+
//! ## Random characters
44+
//!
45+
//! [`Alphanumeric`] is a simple distribution to sample random letters and
46+
//! numbers of the `char` type; in contrast [`Standard`] may sample any valid
47+
//! `char`.
48+
//!
4349
//!
44-
//! # Distribution to sample from a `Uniform` range
50+
//! # Uniform numeric ranges
4551
//!
4652
//! The [`Uniform`] distribution is more flexible than [`Standard`], but also
4753
//! more specialised: it supports fewer target types, but allows the sample
@@ -59,119 +65,41 @@
5965
//! documentation in the [`uniform`] module. Doing so enables generation of
6066
//! values of type `T` with [`Rng::gen_range`].
6167
//!
62-
//!
63-
//! # Other distributions
68+
//! ## Open and half-open ranges
6469
//!
6570
//! There are surprisingly many ways to uniformly generate random floats. A
6671
//! range between 0 and 1 is standard, but the exact bounds (open vs closed)
6772
//! and accuracy differ. In addition to the [`Standard`] distribution Rand offers
6873
//! [`Open01`] and [`OpenClosed01`]. See "Floating point implementation" section of
6974
//! [`Standard`] documentation for more details.
7075
//!
71-
//! [`Alphanumeric`] is a simple distribution to sample random letters and
72-
//! numbers of the `char` type; in contrast [`Standard`] may sample any valid
73-
//! `char`.
74-
//!
75-
//! [`WeightedIndex`] can be used to do weighted sampling from a set of items,
76-
//! such as from an array.
77-
//!
78-
//! # Non-uniform probability distributions
79-
//!
80-
//! Rand currently provides the following probability distributions:
81-
//!
82-
//! - Related to real-valued quantities that grow linearly
83-
//! (e.g. errors, offsets):
84-
//! - [`Normal`] distribution, and [`StandardNormal`] as a primitive
85-
//! - [`Cauchy`] distribution
86-
//! - Related to Bernoulli trials (yes/no events, with a given probability):
87-
//! - [`Binomial`] distribution
88-
//! - [`Bernoulli`] distribution, similar to [`Rng::gen_bool`].
89-
//! - Related to positive real-valued quantities that grow exponentially
90-
//! (e.g. prices, incomes, populations):
91-
//! - [`LogNormal`] distribution
92-
//! - Related to the occurrence of independent events at a given rate:
93-
//! - [`Pareto`] distribution
94-
//! - [`Poisson`] distribution
95-
//! - [`Exp`]onential distribution, and [`Exp1`] as a primitive
96-
//! - [`Weibull`] distribution
97-
//! - Gamma and derived distributions:
98-
//! - [`Gamma`] distribution
99-
//! - [`ChiSquared`] distribution
100-
//! - [`StudentT`] distribution
101-
//! - [`FisherF`] distribution
102-
//! - Triangular distribution:
103-
//! - [`Beta`] distribution
104-
//! - [`Triangular`] distribution
105-
//! - Multivariate probability distributions
106-
//! - [`Dirichlet`] distribution
107-
//! - [`UnitSphereSurface`] distribution
108-
//! - [`UnitCircle`] distribution
109-
//!
110-
//! # Examples
76+
//! # Non-uniform sampling
11177
//!
112-
//! Sampling from a distribution:
78+
//! Sampling a simple true/false outcome with a given probability has a name:
79+
//! the [`Bernoulli`] distribution (this is used by [`Rng::gen_bool`]).
11380
//!
114-
//! ```
115-
//! use rand::{thread_rng, Rng};
116-
//! use rand::distributions::Exp;
81+
//! For weighted sampling from a sequence of discrete values, use the
82+
//! [`weighted`] module.
11783
//!
118-
//! let exp = Exp::new(2.0);
119-
//! let v = thread_rng().sample(exp);
120-
//! println!("{} is from an Exp(2) distribution", v);
121-
//! ```
122-
//!
123-
//! Implementing the [`Standard`] distribution for a user type:
124-
//!
125-
//! ```
126-
//! # #![allow(dead_code)]
127-
//! use rand::Rng;
128-
//! use rand::distributions::{Distribution, Standard};
129-
//!
130-
//! struct MyF32 {
131-
//! x: f32,
132-
//! }
133-
//!
134-
//! impl Distribution<MyF32> for Standard {
135-
//! fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> MyF32 {
136-
//! MyF32 { x: rng.gen() }
137-
//! }
138-
//! }
139-
//! ```
84+
//! This crate no longer includes other non-uniform distributions; instead
85+
//! it is recommended that you use either [`rand_distr`] or [`statrs`].
14086
//!
14187
//!
14288
//! [probability distribution]: https://en.wikipedia.org/wiki/Probability_distribution
143-
//! [`gen_range`]: Rng::gen_range
144-
//! [`gen`]: Rng::gen
145-
//! [`sample`]: Rng::sample
146-
//! [`new_inclusive`]: Uniform::new_inclusive
89+
//! [`rand_distr`]: https://crates.io/crates/rand_distr
90+
//! [`statrs`]: https://crates.io/crates/statrs
91+
14792
//! [`Alphanumeric`]: distributions::Alphanumeric
14893
//! [`Bernoulli`]: distributions::Bernoulli
149-
//! [`Beta`]: distributions::Beta
150-
//! [`Binomial`]: distributions::Binomial
151-
//! [`Cauchy`]: distributions::Cauchy
152-
//! [`ChiSquared`]: distributions::ChiSquared
153-
//! [`Dirichlet`]: distributions::Dirichlet
154-
//! [`Exp`]: distributions::Exp
155-
//! [`Exp1`]: distributions::Exp1
156-
//! [`FisherF`]: distributions::FisherF
157-
//! [`Gamma`]: distributions::Gamma
158-
//! [`LogNormal`]: distributions::LogNormal
159-
//! [`Normal`]: distributions::Normal
16094
//! [`Open01`]: distributions::Open01
16195
//! [`OpenClosed01`]: distributions::OpenClosed01
162-
//! [`Pareto`]: distributions::Pareto
163-
//! [`Poisson`]: distributions::Poisson
16496
//! [`Standard`]: distributions::Standard
165-
//! [`StandardNormal`]: distributions::StandardNormal
166-
//! [`StudentT`]: distributions::StudentT
167-
//! [`Triangular`]: distributions::Triangular
16897
//! [`Uniform`]: distributions::Uniform
16998
//! [`Uniform::new`]: distributions::Uniform::new
17099
//! [`Uniform::new_inclusive`]: distributions::Uniform::new_inclusive
171-
//! [`UnitSphereSurface`]: distributions::UnitSphereSurface
172-
//! [`UnitCircle`]: distributions::UnitCircle
173-
//! [`Weibull`]: distributions::Weibull
174-
//! [`WeightedIndex`]: distributions::WeightedIndex
100+
//! [`weighted`]: distributions::weighted
101+
//! [`rand_distr`]: https://crates.io/crates/rand_distr
102+
//! [`statrs`]: https://crates.io/crates/statrs
175103
176104
#[cfg(any(rustc_1_26, features="nightly"))]
177105
use core::iter;
@@ -334,7 +262,7 @@ impl<'a, D, R, T> iter::TrustedLen for DistIter<'a, D, R, T>
334262
/// Usually generates values with a numerically uniform distribution, and with a
335263
/// range appropriate to the type.
336264
///
337-
/// ## Built-in Implementations
265+
/// ## Provided implementations
338266
///
339267
/// Assuming the provided `Rng` is well-behaved, these implementations
340268
/// generate values with the following ranges and distributions:
@@ -359,7 +287,27 @@ impl<'a, D, R, T> iter::TrustedLen for DistIter<'a, D, R, T>
359287
/// * `Option<T>` where `Standard` is implemented for `T`: Returns `None` with
360288
/// probability 0.5; otherwise generates a random `x: T` and returns `Some(x)`.
361289
///
362-
/// # Example
290+
/// ## Custom implementations
291+
///
292+
/// The [`Standard`] distribution may be implemented for user types as follows:
293+
///
294+
/// ```
295+
/// # #![allow(dead_code)]
296+
/// use rand::Rng;
297+
/// use rand::distributions::{Distribution, Standard};
298+
///
299+
/// struct MyF32 {
300+
/// x: f32,
301+
/// }
302+
///
303+
/// impl Distribution<MyF32> for Standard {
304+
/// fn sample<R: Rng + ?Sized>(&self, rng: &mut R) -> MyF32 {
305+
/// MyF32 { x: rng.gen() }
306+
/// }
307+
/// }
308+
/// ```
309+
///
310+
/// ## Example usage
363311
/// ```
364312
/// use rand::prelude::*;
365313
/// use rand::distributions::Standard;

0 commit comments

Comments
 (0)