Rename NewRng::new → FromEntropy::from_entropy

Author: dhardy

UPDATING.md

@@ -77,14 +77,14 @@ A few methods from the old `Rng` have been removed or deprecated:
 
 ##### New randomly-initialised PRNGs
 
-A new trait has been added: `NewRng`. This is automatically implemented for any
-type supporting `SeedableRng`, and provides construction from fresh, strong
+A new trait has been added: `FromEntropy`. This is automatically implemented for
+any type supporting `SeedableRng`, and provides construction from fresh, strong
 entropy:
 
 ```rust
-use rand::{ChaChaRng, NewRng};
+use rand::{ChaChaRng, FromEntropy};
 
-let mut rng = ChaChaRng::new();
+let mut rng = ChaChaRng::from_entropy();
 ```
 
 ##### Seeding PRNGs
@@ -142,15 +142,15 @@ The following use the new error type:
 -   `RngCore::try_fill_bytes`
 -   `Rng::try_fill`
 -   `OsRng::new`
--   `jitter::new`
+-   `JitterRng::new`
 
 ### External generators
 
 We have a new generator, `EntropyRng`, which wraps `OsRng` and `JitterRng`
 (preferring to use the former, but falling back to the latter if necessary).
 This allows easy construction with fallback via `SeedableRng::from_rng`,
 e.g. `IsaacRng::from_rng(EntropyRng::new())?`. This is equivalent to using
-`NewRng` except for error handling.
+`FromEntropy` except for error handling.
 
 It is recommended to use `EntropyRng` over `OsRng` to avoid errors on platforms
 with broken system generator, but it should be noted that the `JitterRng`
@@ -205,7 +205,7 @@ The `random()` function has been removed; users may simply use
 `thread_rng().gen()` instead or may choose to cache
 `let mut rng = thread_rng();` locally, or even use a different generator.
 
-`weak_rng()` has been deprecated; use `SmallRng::new()` instead.
+`weak_rng()` has been deprecated; use `SmallRng::from_entropy()` instead.
 
 ### Distributions
 

benches/distributions.rs

@@ -9,14 +9,14 @@ const RAND_BENCH_N: u64 = 1000;
 use std::mem::size_of;
 use test::{black_box, Bencher};
 
-use rand::{Rng, NewRng, XorShiftRng};
+use rand::{Rng, FromEntropy, XorShiftRng};
 use rand::distributions::*;
 
 macro_rules! distr_int {
     ($fnn:ident, $ty:ty, $distr:expr) => {
         #[bench]
         fn $fnn(b: &mut Bencher) {
-            let mut rng = XorShiftRng::new();
+            let mut rng = XorShiftRng::from_entropy();
             let distr = $distr;
 
             b.iter(|| {
@@ -36,7 +36,7 @@ macro_rules! distr_float {
     ($fnn:ident, $ty:ty, $distr:expr) => {
         #[bench]
         fn $fnn(b: &mut Bencher) {
-            let mut rng = XorShiftRng::new();
+            let mut rng = XorShiftRng::from_entropy();
             let distr = $distr;
 
             b.iter(|| {
@@ -56,7 +56,7 @@ macro_rules! distr {
     ($fnn:ident, $ty:ty, $distr:expr) => {
         #[bench]
         fn $fnn(b: &mut Bencher) {
-            let mut rng = XorShiftRng::new();
+            let mut rng = XorShiftRng::from_entropy();
             let distr = $distr;
 
             b.iter(|| {
@@ -111,7 +111,7 @@ macro_rules! gen_range_int {
     ($fnn:ident, $ty:ident, $low:expr, $high:expr) => {
         #[bench]
         fn $fnn(b: &mut Bencher) {
-            let mut rng = XorShiftRng::new();
+            let mut rng = XorShiftRng::from_entropy();
 
             b.iter(|| {
                 let mut high = $high;
@@ -137,7 +137,7 @@ gen_range_int!(gen_range_i128, i128, -12345678901234i128, 123_456_789_123_456_78
 
 #[bench]
 fn dist_iter(b: &mut Bencher) {
-    let mut rng = XorShiftRng::new();
+    let mut rng = XorShiftRng::from_entropy();
     let distr = Normal::new(-2.71828, 3.14159);
     let mut iter = distr.sample_iter(&mut rng);
 

benches/generators.rs

@@ -9,7 +9,7 @@ const BYTES_LEN: usize = 1024;
 use std::mem::size_of;
 use test::{black_box, Bencher};
 
-use rand::{RngCore, Rng, SeedableRng, NewRng};
+use rand::{RngCore, Rng, SeedableRng, FromEntropy};
 use rand::{StdRng, SmallRng, OsRng, EntropyRng, ReseedingRng};
 use rand::prng::{XorShiftRng, Hc128Rng, IsaacRng, Isaac64Rng, ChaChaRng};
 use rand::prng::hc128::Hc128Core;
@@ -33,12 +33,12 @@ macro_rules! gen_bytes {
     }
 }
 
-gen_bytes!(gen_bytes_xorshift, XorShiftRng::new());
-gen_bytes!(gen_bytes_hc128, Hc128Rng::new());
-gen_bytes!(gen_bytes_isaac, IsaacRng::new());
-gen_bytes!(gen_bytes_isaac64, Isaac64Rng::new());
-gen_bytes!(gen_bytes_std, StdRng::new());
-gen_bytes!(gen_bytes_small, SmallRng::new());
+gen_bytes!(gen_bytes_xorshift, XorShiftRng::from_entropy());
+gen_bytes!(gen_bytes_hc128, Hc128Rng::from_entropy());
+gen_bytes!(gen_bytes_isaac, IsaacRng::from_entropy());
+gen_bytes!(gen_bytes_isaac64, Isaac64Rng::from_entropy());
+gen_bytes!(gen_bytes_std, StdRng::from_entropy());
+gen_bytes!(gen_bytes_small, SmallRng::from_entropy());
 gen_bytes!(gen_bytes_os, OsRng::new().unwrap());
 
 macro_rules! gen_uint {
@@ -58,20 +58,20 @@ macro_rules! gen_uint {
     }
 }
 
-gen_uint!(gen_u32_xorshift, u32, XorShiftRng::new());
-gen_uint!(gen_u32_hc128, u32, Hc128Rng::new());
-gen_uint!(gen_u32_isaac, u32, IsaacRng::new());
-gen_uint!(gen_u32_isaac64, u32, Isaac64Rng::new());
-gen_uint!(gen_u32_std, u32, StdRng::new());
-gen_uint!(gen_u32_small, u32, SmallRng::new());
+gen_uint!(gen_u32_xorshift, u32, XorShiftRng::from_entropy());
+gen_uint!(gen_u32_hc128, u32, Hc128Rng::from_entropy());
+gen_uint!(gen_u32_isaac, u32, IsaacRng::from_entropy());
+gen_uint!(gen_u32_isaac64, u32, Isaac64Rng::from_entropy());
+gen_uint!(gen_u32_std, u32, StdRng::from_entropy());
+gen_uint!(gen_u32_small, u32, SmallRng::from_entropy());
 gen_uint!(gen_u32_os, u32, OsRng::new().unwrap());
 
-gen_uint!(gen_u64_xorshift, u64, XorShiftRng::new());
-gen_uint!(gen_u64_hc128, u64, Hc128Rng::new());
-gen_uint!(gen_u64_isaac, u64, IsaacRng::new());
-gen_uint!(gen_u64_isaac64, u64, Isaac64Rng::new());
-gen_uint!(gen_u64_std, u64, StdRng::new());
-gen_uint!(gen_u64_small, u64, SmallRng::new());
+gen_uint!(gen_u64_xorshift, u64, XorShiftRng::from_entropy());
+gen_uint!(gen_u64_hc128, u64, Hc128Rng::from_entropy());
+gen_uint!(gen_u64_isaac, u64, IsaacRng::from_entropy());
+gen_uint!(gen_u64_isaac64, u64, Isaac64Rng::from_entropy());
+gen_uint!(gen_u64_std, u64, StdRng::from_entropy());
+gen_uint!(gen_u64_small, u64, SmallRng::from_entropy());
 gen_uint!(gen_u64_os, u64, OsRng::new().unwrap());
 
 // Do not test JitterRng like the others by running it RAND_BENCH_N times per,
@@ -89,7 +89,7 @@ macro_rules! init_gen {
     ($fnn:ident, $gen:ident) => {
         #[bench]
         fn $fnn(b: &mut Bencher) {
-            let mut rng = XorShiftRng::new();
+            let mut rng = XorShiftRng::from_entropy();
             b.iter(|| {
                 let r2 = $gen::from_rng(&mut rng).unwrap();
                 black_box(r2);
@@ -115,7 +115,7 @@ macro_rules! chacha_rounds {
     ($fn1:ident, $fn2:ident, $fn3:ident, $rounds:expr) => {
         #[bench]
         fn $fn1(b: &mut Bencher) {
-            let mut rng = ChaChaRng::new();
+            let mut rng = ChaChaRng::from_entropy();
             rng.set_rounds($rounds);
             let mut buf = [0u8; BYTES_LEN];
             b.iter(|| {
@@ -129,7 +129,7 @@ macro_rules! chacha_rounds {
 
         #[bench]
         fn $fn2(b: &mut Bencher) {
-            let mut rng = ChaChaRng::new();
+            let mut rng = ChaChaRng::from_entropy();
             rng.set_rounds($rounds);
             b.iter(|| {
                 let mut accum: u32 = 0;
@@ -143,7 +143,7 @@ macro_rules! chacha_rounds {
 
         #[bench]
         fn $fn3(b: &mut Bencher) {
-            let mut rng = ChaChaRng::new();
+            let mut rng = ChaChaRng::from_entropy();
             rng.set_rounds($rounds);
             b.iter(|| {
                 let mut accum: u64 = 0;
@@ -167,7 +167,7 @@ const RESEEDING_THRESHOLD: u64 = 1024*1024*1024; // something high enough to get
 
 #[bench]
 fn reseeding_hc128_bytes(b: &mut Bencher) {
-    let mut rng = ReseedingRng::new(Hc128Core::new(),
+    let mut rng = ReseedingRng::new(Hc128Core::from_entropy(),
                                     RESEEDING_THRESHOLD,
                                     EntropyRng::new());
     let mut buf = [0u8; BYTES_LEN];
@@ -184,7 +184,7 @@ macro_rules! reseeding_uint {
     ($fnn:ident, $ty:ty) => {
         #[bench]
         fn $fnn(b: &mut Bencher) {
-            let mut rng = ReseedingRng::new(Hc128Core::new(),
+            let mut rng = ReseedingRng::new(Hc128Core::from_entropy(),
                                             RESEEDING_THRESHOLD,
                                             EntropyRng::new());
             b.iter(|| {

rand_core/src/lib.rs

@@ -98,7 +98,7 @@ pub mod le;
 ///   original (i.e. all deterministic PRNGs but not external generators)
 /// - *never* implement `Copy` (accidental copies may cause repeated values)
 /// - also *do not* implement `Default`, but instead implement `SeedableRng`
-///   thus allowing use of `rand::NewRng` (which is automatically implemented)
+///   thus allowing use of `rand::FromEntropy` (which is automatically implemented)
 /// - `Eq` and `PartialEq` could be implemented, but are probably not useful
 /// 
 /// # Example
@@ -270,10 +270,11 @@ pub trait CryptoRng {}
 /// This trait encapsulates the low-level functionality common to all
 /// pseudo-random number generators (PRNGs, or algorithmic generators).
 /// 
-/// The [`rand::NewRng`] trait is automatically implemented for every type
-/// implementing `SeedableRng`, providing a convenient `new()` method.
+/// The [`rand::FromEntropy`] trait is automatically implemented for every type
+/// implementing `SeedableRng`, providing a convenient `from_entropy()`
+/// constructor.
 /// 
-/// [`rand::NewRng`]: ../rand/trait.NewRng.html
+/// [`rand::FromEntropy`]: ../rand/trait.FromEntropy.html
 pub trait SeedableRng: Sized {
     /// Seed type, which is restricted to types mutably-dereferencable as `u8`
     /// arrays (we recommend `[u8; N]` for some `N`).
@@ -348,7 +349,8 @@ pub trait SeedableRng: Sized {
     /// Create a new PRNG seeded from another `Rng`.
     ///
     /// This is the recommended way to initialize PRNGs with fresh entropy. The
-    /// [`NewRng`] trait provides a convenient new method based on `from_rng`.
+    /// [`FromEntropy`] trait provides a convenient `from_entropy` method
+    /// based on `from_rng`.
     /// 
     /// Usage of this method is not recommended when reproducibility is required
     /// since implementing PRNGs are not required to fix Endianness and are
@@ -374,7 +376,7 @@ pub trait SeedableRng: Sized {
     /// PRNG implementations are allowed to assume that a good RNG is provided
     /// for seeding, and that it is cryptographically secure when appropriate.
     /// 
-    /// [`NewRng`]: ../rand/trait.NewRng.html
+    /// [`FromEntropy`]: ../rand/trait.FromEntropy.html
     /// [`OsRng`]: ../rand/os/struct.OsRng.html
     fn from_rng<R: RngCore>(mut rng: R) -> Result<Self, Error> {
         let mut seed = Self::Seed::default();

src/distributions/exponential.rs

@@ -30,10 +30,10 @@ use distributions::{ziggurat, ziggurat_tables, Distribution};
 ///
 /// # Example
 /// ```rust
-/// use rand::{NewRng, SmallRng, Rng};
+/// use rand::{FromEntropy, SmallRng, Rng};
 /// use rand::distributions::Exp1;
 ///
-/// let val: f64 = SmallRng::new().sample(Exp1);
+/// let val: f64 = SmallRng::from_entropy().sample(Exp1);
 /// println!("{}", val);
 /// ```
 #[derive(Clone, Copy, Debug)]

src/distributions/mod.rs

@@ -244,10 +244,10 @@ impl<'a, T, D: Distribution<T>> Distribution<T> for &'a D {
 ///
 /// # Example
 /// ```rust
-/// use rand::{NewRng, SmallRng, Rng};
+/// use rand::{FromEntropy, SmallRng, Rng};
 /// use rand::distributions::Standard;
 ///
-/// let val: f32 = SmallRng::new().sample(Standard);
+/// let val: f32 = SmallRng::from_entropy().sample(Standard);
 /// println!("f32 from (0,1): {}", val);
 /// ```
 ///

src/distributions/normal.rs

@@ -28,10 +28,10 @@ use distributions::{ziggurat, ziggurat_tables, Distribution};
 ///
 /// # Example
 /// ```rust
-/// use rand::{NewRng, SmallRng, Rng};
+/// use rand::{FromEntropy, SmallRng, Rng};
 /// use rand::distributions::StandardNormal;
 ///
-/// let val: f64 = SmallRng::new().sample(StandardNormal);
+/// let val: f64 = SmallRng::from_entropy().sample(StandardNormal);
 /// println!("{}", val);
 /// ```
 #[derive(Clone, Copy, Debug)]