Rename Sample → Distribution. Make WeightedChoice own its arguments.

The change to WeightedChoice is debatable, but since the argument must normally
be constructed specially anyway, the reference model makes little sense.
See issues rust-random#90, rust-random#142 and PR rust-random#152.

Author: dhardy

benches/distributions/exponential.rs

@@ -2,7 +2,7 @@ use std::mem::size_of;
 use test::Bencher;
 use rand;
 use rand::dist::exponential::Exp;
-use rand::dist::Sample;
+use rand::dist::Distribution;
 
 #[bench]
 fn rand_exp(b: &mut Bencher) {

benches/distributions/gamma.rs

@@ -1,7 +1,7 @@
 use std::mem::size_of;
 use test::Bencher;
 use rand;
-use rand::dist::Sample;
+use rand::dist::Distribution;
 use rand::dist::gamma::Gamma;
 
 #[bench]

benches/distributions/normal.rs

@@ -1,7 +1,7 @@
 use std::mem::size_of;
 use test::Bencher;
 use rand;
-use rand::dist::Sample;
+use rand::dist::Distribution;
 use rand::dist::normal::Normal;
 
 #[bench]

src/dist/exponential.rs

@@ -11,7 +11,7 @@
 //! The exponential distribution.
 
 use {Rng};
-use dist::{ziggurat, ziggurat_tables, Sample, uniform01};
+use dist::{ziggurat, ziggurat_tables, Distribution, uniform01};
 
 /// Generates Exp(1) random numbers.
 ///
@@ -60,7 +60,7 @@ pub fn exp1<R: Rng>(rng: &mut R) -> f64 {
 /// # Example
 ///
 /// ```rust
-/// use rand::dist::{Exp, Sample};
+/// use rand::dist::{Exp, Distribution};
 ///
 /// let exp = Exp::new(2.0);
 /// let v = exp.sample(&mut rand::thread_rng());
@@ -82,15 +82,15 @@ impl Exp {
     }
 }
 
-impl Sample<f64> for Exp {
+impl Distribution<f64> for Exp {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         exp1(rng) * self.lambda_inverse
     }
 }
 
 #[cfg(test)]
 mod test {
-    use dist::{Sample};
+    use dist::{Distribution};
     use super::Exp;
 
     #[test]

src/dist/gamma.rs

@@ -17,7 +17,7 @@ use self::ChiSquaredRepr::*;
 
 use {Rng};
 use dist::normal::standard_normal;
-use dist::{Sample, Exp, open01};
+use dist::{Distribution, Exp, open01};
 
 /// The Gamma distribution `Gamma(shape, scale)` distribution.
 ///
@@ -38,7 +38,7 @@ use dist::{Sample, Exp, open01};
 /// # Example
 ///
 /// ```rust
-/// use rand::dist::{Sample, Gamma};
+/// use rand::dist::{Distribution, Gamma};
 ///
 /// let gamma = Gamma::new(2.0, 5.0);
 /// let v = gamma.sample(&mut rand::thread_rng());
@@ -134,7 +134,7 @@ impl GammaLargeShape {
 }
 
 
-impl Sample<f64> for Gamma {
+impl Distribution<f64> for Gamma {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         match self.repr {
             Small(ref g) => g.sample(rng),
@@ -143,14 +143,14 @@ impl Sample<f64> for Gamma {
         }
     }
 }
-impl Sample<f64> for GammaSmallShape {
+impl Distribution<f64> for GammaSmallShape {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         let u: f64 = open01(rng);
 
         self.large_shape.sample(rng) * u.powf(self.inv_shape)
     }
 }
-impl Sample<f64> for GammaLargeShape {
+impl Distribution<f64> for GammaLargeShape {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         loop {
             let x = standard_normal(rng);
@@ -182,7 +182,7 @@ impl Sample<f64> for GammaLargeShape {
 /// # Example
 ///
 /// ```rust
-/// use rand::dist::{ChiSquared, Sample};
+/// use rand::dist::{ChiSquared, Distribution};
 ///
 /// let chi = ChiSquared::new(11.0);
 /// let v = chi.sample(&mut rand::thread_rng());
@@ -215,7 +215,7 @@ impl ChiSquared {
         ChiSquared { repr: repr }
     }
 }
-impl Sample<f64> for ChiSquared {
+impl Distribution<f64> for ChiSquared {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         match self.repr {
             DoFExactlyOne => {
@@ -237,7 +237,7 @@ impl Sample<f64> for ChiSquared {
 /// # Example
 ///
 /// ```rust
-/// use rand::dist::{FisherF, Sample};
+/// use rand::dist::{FisherF, Distribution};
 ///
 /// let f = FisherF::new(2.0, 32.0);
 /// let v = f.sample(&mut rand::thread_rng());
@@ -266,7 +266,7 @@ impl FisherF {
         }
     }
 }
-impl Sample<f64> for FisherF {
+impl Distribution<f64> for FisherF {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         self.numer.sample(rng) / self.denom.sample(rng) * self.dof_ratio
     }
@@ -278,7 +278,7 @@ impl Sample<f64> for FisherF {
 /// # Example
 ///
 /// ```rust
-/// use rand::dist::{StudentT, Sample};
+/// use rand::dist::{StudentT, Distribution};
 ///
 /// let t = StudentT::new(11.0);
 /// let v = t.sample(&mut rand::thread_rng());
@@ -301,7 +301,7 @@ impl StudentT {
         }
     }
 }
-impl Sample<f64> for StudentT {
+impl Distribution<f64> for StudentT {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         let norm = standard_normal(rng);
         norm * (self.dof / self.chi.sample(rng)).sqrt()
@@ -310,7 +310,7 @@ impl Sample<f64> for StudentT {
 
 #[cfg(test)]
 mod test {
-    use dist::{Sample};
+    use dist::{Distribution};
     use super::{ChiSquared, StudentT, FisherF};
 
     #[test]

src/dist/mod.rs

@@ -12,7 +12,7 @@
 //!
 //! A distribution may have internal state describing the distribution of
 //! generated values; for example `Range` needs to know its upper and lower
-//! bounds. Distributions use the `Sample` trait to yield values: call
+//! bounds. Distributions use the `Distribution` trait to yield values: call
 //! `dist.sample(&mut rng)` to get a random variable.
 //!
 //! TODO: is it worth exposing both submodules and re-exporting their members?
@@ -33,7 +33,7 @@ pub mod exponential;
 pub mod weighted;
 
 /// Types (distributions) that can be used to create a random instance of `T`.
-pub trait Sample<T> {
+pub trait Distribution<T> {
     /// Generate a random value of `T`, using `rng` as the
     /// source of randomness.
     fn sample<R: Rng>(&self, rng: &mut R) -> T;

src/dist/normal.rs

@@ -11,7 +11,7 @@
 //! The normal and derived distributions.
 
 use {Rng};
-use dist::{ziggurat, ziggurat_tables, Sample, open01};
+use dist::{ziggurat, ziggurat_tables, Distribution, open01};
 
 /// Generates N(0, 1) random numbers
 /// (a.k.a.  a standard normal, or Gaussian).
@@ -76,7 +76,7 @@ pub fn standard_normal<R:Rng>(rng: &mut R) -> f64 {
 /// # Example
 ///
 /// ```rust
-/// use rand::dist::{Normal, Sample};
+/// use rand::dist::{Normal, Distribution};
 ///
 /// // mean 2, standard deviation 3
 /// let normal = Normal::new(2.0, 3.0);
@@ -105,7 +105,7 @@ impl Normal {
         }
     }
 }
-impl Sample<f64> for Normal {
+impl Distribution<f64> for Normal {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         self.mean + self.std_dev * standard_normal(rng)
     }
@@ -120,7 +120,7 @@ impl Sample<f64> for Normal {
 /// # Example
 ///
 /// ```rust
-/// use rand::dist::{LogNormal, Sample};
+/// use rand::dist::{LogNormal, Distribution};
 ///
 /// // mean 2, standard deviation 3
 /// let log_normal = LogNormal::new(2.0, 3.0);
@@ -145,15 +145,15 @@ impl LogNormal {
         LogNormal { norm: Normal::new(mean, std_dev) }
     }
 }
-impl Sample<f64> for LogNormal {
+impl Distribution<f64> for LogNormal {
     fn sample<R: Rng>(&self, rng: &mut R) -> f64 {
         self.norm.sample(rng).exp()
     }
 }
 
 #[cfg(test)]
 mod tests {
-    use dist::{Sample};
+    use dist::{Distribution};
     use super::{Normal, LogNormal};
 
     #[test]

src/dist/range.rs

@@ -15,7 +15,7 @@
 use std::num::Wrapping as w;
 
 use Rng;
-use dist::{Sample, uniform01};
+use dist::{Distribution, uniform01};
 
 /// Sample values uniformly between two bounds.
 ///
@@ -34,7 +34,7 @@ use dist::{Sample, uniform01};
 /// # Example
 ///
 /// ```rust
-/// use rand::dist::{Sample, Range};
+/// use rand::dist::{Distribution, Range};
 ///
 /// fn main() {
 ///     let between = Range::new(10, 10000);
@@ -62,7 +62,7 @@ impl<X: SampleRange + PartialOrd> Range<X> {
     }
 }
 
-impl<T: SampleRange> Sample<T> for Range<T> {
+impl<T: SampleRange> Distribution<T> for Range<T> {
     fn sample<R: Rng>(&self, rng: &mut R) -> T {
         SampleRange::sample_range(self, rng)
     }
@@ -162,7 +162,7 @@ float_impl! { f64 }
 
 #[cfg(test)]
 mod tests {
-    use dist::{Sample};
+    use dist::{Distribution};
     use super::Range as Range;
 
     #[should_panic]

src/dist/uniform.rs

@@ -11,11 +11,12 @@
 //! Generating uniformly distributed numbers
 
 use std::char;
+use std::fmt;
 use std::mem;
 use std::marker::PhantomData;
 
 use Rng;
-use dist::Sample;
+use dist::Distribution;
 
 // ----- convenience functions -----
 
@@ -71,13 +72,13 @@ pub fn codepoint<R: Rng>(rng: &mut R) -> char {
 }
 
 
-// ----- Sample implementations -----
+// ----- Distribution implementations -----
 // TODO: do we want these? If so, implement for other ranges.
 
 /// Sample values uniformly over the whole range supported by the type.
 /// 
 /// No internal state.
-#[derive(Clone, Copy, Debug, Default)]
+#[derive(Default)]
 pub struct Uniform<T: SampleUniform> {
     _marker: PhantomData<T>,
 }
@@ -92,7 +93,23 @@ impl<T: SampleUniform> Uniform<T> {
     }
 }
 
-impl<T: SampleUniform> Sample<T> for Uniform<T> {
+impl<T: SampleUniform> Copy for Uniform<T> {}
+
+// derive only auto-impls for types T: Clone, but we don't have that restriction
+impl<T: SampleUniform> Clone for Uniform<T> {
+    fn clone(&self) -> Self {
+        Uniform::new()
+    }
+}
+
+// derive only auto-impls for types T: Debug, but we don't have that restriction
+impl<T: SampleUniform> fmt::Debug for Uniform<T> {
+    fn fmt(&self, f: &mut fmt::Formatter) -> Result<(), fmt::Error> {
+        write!(f, "Uniform {{}}")
+    }
+}
+
+impl<T: SampleUniform> Distribution<T> for Uniform<T> {
     fn sample<R: Rng>(&self, rng: &mut R) -> T {
         T::sample_uniform(rng)
     }
@@ -267,7 +284,7 @@ float_impls! { SCALE_F32, f32, 24, next_f32 }
 #[cfg(test)]
 mod tests {
     use {Rng, thread_rng};
-    use dist::{uniform, Sample};
+    use dist::{uniform, Distribution};
     use dist::uniform::{SampleUniform, Uniform};
     use dist::{uniform01, open01, closed01};