Rename fill_bytes → fill; also some doc fixes

benches/generators.rs

@@ -20,7 +20,7 @@ macro_rules! gen_bytes {
             let mut buf = [0u8; BYTES_LEN];
             b.iter(|| {
                 for _ in 0..RAND_BENCH_N {
-                    rng.fill_bytes(&mut buf);
+                    rng.fill(&mut buf);
                     black_box(buf);
                 }
             });
@@ -37,7 +37,7 @@ macro_rules! gen_bytes_new {
             let mut buf = [0u8; BYTES_LEN];
             b.iter(|| {
                 for _ in 0..RAND_BENCH_N {
-                    rng.fill_bytes(&mut buf);
+                    rng.fill(&mut buf);
                     black_box(buf);
                 }
             });

src/distributions/mod.rs

@@ -302,8 +302,8 @@ mod tests {
             self.next_u32() as u64
         }
 
-        fn fill_bytes(&mut self, dest: &mut [u8]) {
-            impls::fill_bytes_via_u32(self, dest)
+        fn fill(&mut self, dest: &mut [u8]) {
+            impls::fill_via_u32(self, dest)
         }
     }
 

src/impls.rs

@@ -36,7 +36,7 @@ pub fn next_u64_via_u32<R: Rng+?Sized>(rng: &mut R) -> u64 {
     (y << 32) | x
 }
 
-macro_rules! fill_bytes_via {
+macro_rules! fill_via {
     ($rng:ident, $next_u:ident, $BYTES:expr, $dest:ident) => {{
         let mut left = $dest;
         while left.len() >= $BYTES {
@@ -57,14 +57,14 @@ macro_rules! fill_bytes_via {
     }}
 }
 
-/// Implement `fill_bytes` via `next_u32`, little-endian order.
-pub fn fill_bytes_via_u32<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) {
-    fill_bytes_via!(rng, next_u32, 4, dest)
+/// Implement `fill` via `next_u32`, little-endian order.
+pub fn fill_via_u32<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) {
+    fill_via!(rng, next_u32, 4, dest)
 }
 
-/// Implement `fill_bytes` via `next_u64`, little-endian order.
-pub fn fill_bytes_via_u64<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) {
-    fill_bytes_via!(rng, next_u64, 8, dest)
+/// Implement `fill` via `next_u64`, little-endian order.
+pub fn fill_via_u64<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) {
+    fill_via!(rng, next_u64, 8, dest)
 }
 
 macro_rules! impl_uint_from_fill {
@@ -75,7 +75,7 @@ macro_rules! impl_uint_from_fill {
         unsafe {
             let ptr = &mut int as *mut $ty as *mut u8;
             let slice = slice::from_raw_parts_mut(ptr, $N);
-            $rng.fill_bytes(slice);
+            $rng.fill(slice);
         }
         int
     });
@@ -101,7 +101,7 @@ macro_rules! fill_via_chunks {
     });
 }
 
-/// Implement `fill_bytes` by reading chunks from the output buffer of a block
+/// Implement `fill` by reading chunks from the output buffer of a block
 /// based RNG.
 ///
 /// The return values are `(consumed_u32, filled_u8)`.
@@ -119,7 +119,7 @@ macro_rules! fill_via_chunks {
 /// (from `IsaacRng`)
 ///
 /// ```rust,ignore
-/// fn fill_bytes(&mut self, dest: &mut [u8]) {
+/// fn fill(&mut self, dest: &mut [u8]) {
 ///     let mut read_len = 0;
 ///     while read_len < dest.len() {
 ///         if self.index >= self.rsl.len() {
@@ -139,7 +139,7 @@ pub fn fill_via_u32_chunks(src: &mut [u32], dest: &mut [u8]) -> (usize, usize) {
     fill_via_chunks!(src, dest, 4)
 }
 
-/// Implement `fill_bytes` by reading chunks from the output buffer of a block
+/// Implement `fill` by reading chunks from the output buffer of a block
 /// based RNG.
 ///
 /// The return values are `(consumed_u64, filled_u8)`.
@@ -157,17 +157,17 @@ pub fn fill_via_u64_chunks(src: &mut [u64], dest: &mut [u8]) -> (usize, usize) {
     fill_via_chunks!(src, dest, 8)
 }
 
-/// Implement `next_u32` via `fill_bytes`, little-endian order.
+/// Implement `next_u32` via `fill`, little-endian order.
 pub fn next_u32_via_fill<R: Rng+?Sized>(rng: &mut R) -> u32 {
     impl_uint_from_fill!(rng, u32, 4)
 }
 
-/// Implement `next_u64` via `fill_bytes`, little-endian order.
+/// Implement `next_u64` via `fill`, little-endian order.
 pub fn next_u64_via_fill<R: Rng+?Sized>(rng: &mut R) -> u64 {
     impl_uint_from_fill!(rng, u64, 8)
 }
 
-/// Implement `fill_bytes` via `try_fill` with implicit error handling.
+/// Implement `fill` via `try_fill` with implicit error handling.
 pub fn fill_via_try_fill<R: Rng+?Sized>(rng: &mut R, dest: &mut [u8]) {
     const WAIT_DUR_MS: u32 = 100;
     const MAX_WAIT: u32 = (1 * 60 * 1000) / WAIT_DUR_MS;

src/jitter.rs

@@ -730,8 +730,8 @@ impl Rng for JitterRng {
        self.gen_entropy()
     }
 
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
-        impls::fill_bytes_via_u64(self, dest)
+    fn fill(&mut self, dest: &mut [u8]) {
+        impls::fill_via_u64(self, dest)
     }
 }
 

src/lib.rs

@@ -344,19 +344,19 @@ pub trait Rng {
     /// Return the next random `u32`.
     ///
     /// Implementations of this trait must implement at least one of
-    /// `next_u32`, `next_u64` and `fill_bytes` directly. In the case this
+    /// `next_u32`, `next_u64`, `fill` and `try_fill` directly. In the case this
     /// function is not implemented directly, it can be implemented using
-    /// `self.next_u64() as u32` or via `fill_bytes` (TODO: expose helper
+    /// `self.next_u64() as u32` or via `fill` (TODO: expose helper
     /// function).
     fn next_u32(&mut self) -> u32;
 
     /// Return the next random `u64`.
     ///
     /// Implementations of this trait must implement at least one of
-    /// `next_u32`, `next_u64` and `fill_bytes` directly. In the case this
+    /// `next_u32`, `next_u64`, `fill` and `try_fill` directly. In the case this
     /// function is not implemented directly, the default implementation will
     /// generate values via `next_u32` in little-endian fashion, or this
-    /// function can be implemented via `fill_bytes` (TODO: expose helper
+    /// function can be implemented via `fill` (TODO: expose helper
     /// function).
     ///
     /// Types wrapping an inner RNG must not use the default implementation,
@@ -420,7 +420,7 @@ pub trait Rng {
     /// Fill `dest` with random data.
     ///
     /// Implementations of this trait must implement at least one of
-    /// `next_u32`, `next_u64` and `fill_bytes` directly. In the case this
+    /// `next_u32`, `next_u64`, `fill` and `try_fill` directly. In the case this
     /// function is not implemented directly, the default implementation will
     /// generate values via `next_u64` in little-endian fashion.
     /// (TODO: expose helper function to allow implementation via `next_u32`.)
@@ -445,27 +445,32 @@ pub trait Rng {
     /// use rand::{thread_rng, Rng};
     ///
     /// let mut v = [0u8; 13579];
-    /// thread_rng().fill_bytes(&mut v);
+    /// thread_rng().fill(&mut v);
     /// println!("{:?}", &v[..]);
     /// ```
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
-        impls::fill_bytes_via_u64(self, dest)
+    fn fill(&mut self, dest: &mut [u8]) {
+        impls::fill_via_u64(self, dest)
     }
 
     /// Fill `dest` entirely with random data.
     ///
+    /// Implementations of this trait must implement at least one of
+    /// `next_u32`, `next_u64`, `fill` and `try_fill` directly. In the case this
+    /// function is not implemented directly, the default implementation will
+    /// generate values via `fill`.
+    /// 
     /// This is the only method which allows an RNG to report errors while
     /// generating random data; other methods either handle the error
     /// internally or panic. This method is
     /// the intended way to use external (true) RNGs, like `OsRng`. Its main
     /// use-cases are to generate keys and to seed (infallible) PRNGs.
     /// 
-    /// Other than error handling, this method is identical to [`fill_bytes`], and
-    /// has a default implementation simply wrapping [`fill_bytes`].
+    /// Other than error handling, this method is identical to [`fill`], and
+    /// has a default implementation simply wrapping [`fill`].
     /// 
-    /// [`fill_bytes`]: trait.Rng.html#method.fill_bytes
+    /// [`fill`]: trait.Rng.html#method.fill
     fn try_fill(&mut self, dest: &mut [u8]) -> Result<(), Error> {
-        Ok(self.fill_bytes(dest))
+        Ok(self.fill(dest))
     }
 
     /// Return a random value of a `Rand` type.
@@ -643,8 +648,8 @@ impl<'a, R: ?Sized> Rng for &'a mut R where R: Rng {
     }
 
     #[inline]
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
-        (**self).fill_bytes(dest)
+    fn fill(&mut self, dest: &mut [u8]) {
+        (**self).fill(dest)
     }
 
     #[inline]
@@ -676,8 +681,8 @@ impl<R: ?Sized> Rng for Box<R> where R: Rng {
     }
 
     #[inline]
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
-        (**self).fill_bytes(dest)
+    fn fill(&mut self, dest: &mut [u8]) {
+        (**self).fill(dest)
     }
 
     #[inline]
@@ -843,8 +848,8 @@ impl Rng for StdRng {
     }
 
     #[inline]
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
-        self.rng.fill_bytes(dest)
+    fn fill(&mut self, dest: &mut [u8]) {
+        self.rng.fill(dest)
     }
 
     #[inline]
@@ -946,8 +951,8 @@ impl Rng for ThreadRng {
     }
 
     #[inline]
-    fn fill_bytes(&mut self, bytes: &mut [u8]) {
-        self.rng.borrow_mut().fill_bytes(bytes)
+    fn fill(&mut self, bytes: &mut [u8]) {
+        self.rng.borrow_mut().fill(bytes)
     }
 
     #[inline]
@@ -1045,8 +1050,8 @@ mod test {
         fn next_u64(&mut self) -> u64 {
             self.inner.next_u64()
         }
-        fn fill_bytes(&mut self, dest: &mut [u8]) {
-            self.inner.fill_bytes(dest)
+        fn fill(&mut self, dest: &mut [u8]) {
+            self.inner.fill(dest)
         }
     }
 
@@ -1059,8 +1064,8 @@ mod test {
         fn next_u32(&mut self) -> u32 { self.i as u32 }
         fn next_u64(&mut self) -> u64 { self.i }
 
-        fn fill_bytes(&mut self, dest: &mut [u8]) {
-            impls::fill_bytes_via_u64(self, dest)
+        fn fill(&mut self, dest: &mut [u8]) {
+            impls::fill_via_u64(self, dest)
         }
     }
 
@@ -1082,15 +1087,15 @@ mod test {
     }
 
     #[test]
-    fn test_fill_bytes_default() {
+    fn test_fill_default() {
         let mut r = ConstRng { i: 0x11_22_33_44_55_66_77_88 };
 
         // check every remainder mod 8, both in small and big vectors.
         let lengths = [0, 1, 2, 3, 4, 5, 6, 7,
                        80, 81, 82, 83, 84, 85, 86, 87];
         for &n in lengths.iter() {
             let mut v = repeat(0u8).take(n).collect::<Vec<_>>();
-            r.fill_bytes(&mut v);
+            r.fill(&mut v);
 
             // use this to get nicer error messages.
             for (i, &byte) in v.iter().enumerate() {

src/os.rs

@@ -60,7 +60,7 @@ impl Rng for OsRng {
         impls::next_u64_via_fill(self)
     }
 
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
+    fn fill(&mut self, dest: &mut [u8]) {
         impls::fill_via_try_fill(self, dest)
     }
 

src/prng/chacha.rs

@@ -208,8 +208,8 @@ impl Rng for ChaChaRng {
     }
 
 
-    fn fill_bytes(&mut self, bytes: &mut [u8]) {
-        impls::fill_bytes_via_u32(self, bytes)
+    fn fill(&mut self, bytes: &mut [u8]) {
+        impls::fill_via_u32(self, bytes)
     }
 }
 
@@ -334,7 +334,7 @@ mod test {
         let seed : &[_] = &[0u32; 8];
         let mut ra: ChaChaRng = SeedableRng::from_seed(seed);
         let mut buf = [0u8; 32];
-        ra.fill_bytes(&mut buf);
+        ra.fill(&mut buf);
         // Same as first values in test_isaac_true_values as bytes in LE order
         assert_eq!(buf,
                    [118, 184, 224, 173, 160, 241, 61, 144,

src/prng/isaac.rs

@@ -158,7 +158,7 @@ impl IsaacRng {
     ///   arithmetic.
     /// - We fill `rsl` backwards. The reference implementation reads values
     ///   from `rsl` in reverse. We read them in the normal direction, to make
-    ///   `fill_bytes` a memcopy. To maintain compatibility we fill in reverse.
+    ///   `fill` a memcopy. To maintain compatibility we fill in reverse.
     fn isaac(&mut self) {
         self.c += w(1);
         // abbreviations
@@ -234,7 +234,7 @@ impl Rng for IsaacRng {
     }
 
 
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
+    fn fill(&mut self, dest: &mut [u8]) {
         let mut read_len = 0;
         while read_len < dest.len() {
             if self.index as usize >= RAND_SIZE {
@@ -340,7 +340,7 @@ impl Rand for IsaacRng {
             let ptr = key.as_mut_ptr() as *mut u8;
 
             let slice = slice::from_raw_parts_mut(ptr, RAND_SIZE * 4);
-            other.fill_bytes(slice);
+            other.fill(slice);
         }
 
         init(key, 2)
@@ -443,7 +443,7 @@ mod test {
         let seed: &[_] = &[1, 23, 456, 7890, 12345];
         let mut rng1 = IsaacRng::from_seed(seed);
         let mut buf = [0u8; 32];
-        rng1.fill_bytes(&mut buf);
+        rng1.fill(&mut buf);
         // Same as first values in test_isaac_true_values as bytes in LE order
         assert_eq!(buf,
                    [82, 186, 128, 152, 71, 240, 20, 52,

src/prng/isaac64.rs

@@ -143,7 +143,7 @@ impl Isaac64Rng {
     ///   arithmetic.
     /// - We fill `rsl` backwards. The reference implementation reads values
     ///   from `rsl` in reverse. We read them in the normal direction, to make
-    ///   `fill_bytes` a memcopy. To maintain compatibility we fill in reverse.
+    ///   `fill` a memcopy. To maintain compatibility we fill in reverse.
     fn isaac64(&mut self) {
         self.c += w(1);
         // abbreviations
@@ -237,7 +237,7 @@ impl Rng for Isaac64Rng {
         value
     }
 
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
+    fn fill(&mut self, dest: &mut [u8]) {
         let mut read_len = 0;
         while read_len < dest.len() {
             if self.index as usize >= RAND_SIZE {
@@ -319,7 +319,7 @@ impl Rand for Isaac64Rng {
             let ptr = key.as_mut_ptr() as *mut u8;
 
             let slice = slice::from_raw_parts_mut(ptr, RAND_SIZE * 8);
-            other.fill_bytes(slice);
+            other.fill(slice);
         }
         init(key, 2)
     }
@@ -447,7 +447,7 @@ mod test {
         let seed: &[_] = &[1, 23, 456, 7890, 12345];
         let mut rng1 = Isaac64Rng::from_seed(seed);
         let mut buf = [0u8; 32];
-        rng1.fill_bytes(&mut buf);
+        rng1.fill(&mut buf);
         // Same as first values in test_isaac64_true_values as bytes in LE order
         assert_eq!(buf,
                    [140, 237, 103, 8, 93, 196, 151, 7,

src/prng/xorshift.rs

@@ -74,8 +74,8 @@ impl Rng for XorShiftRng {
         impls::next_u64_via_u32(self)
     }
 
-    fn fill_bytes(&mut self, dest: &mut [u8]) {
-        impls::fill_bytes_via_u32(self, dest)
+    fn fill(&mut self, dest: &mut [u8]) {
+        impls::fill_via_u32(self, dest)
     }
 }