Merge pull request #381 from vks/large-seed

Docs for implementing `SeedableRng` for large seeds

Author: pitdicker

rand_core/src/lib.rs

@@ -284,6 +284,43 @@ pub trait SeedableRng: Sized {
     /// partially overlapping periods.
     ///
     /// For cryptographic RNG's a seed of 256 bits is recommended, `[u8; 32]`.
+    ///
+    ///
+    /// # Implementing `SeedableRng` for RNGs with large seeds
+    ///
+    /// Note that the required traits `core::default::Default` and
+    /// `core::convert::AsMut<u8>` are not implemented for large arrays
+    /// `[u8; N]` with `N` > 32. To be able to implement the traits required by
+    /// `SeedableRng` for RNGs with such large seeds, the newtype pattern can be
+    /// used:
+    ///
+    /// ```
+    /// use rand_core::SeedableRng;
+    ///
+    /// const N: usize = 64;
+    /// pub struct MyRngSeed(pub [u8; N]);
+    /// pub struct MyRng(MyRngSeed);
+    ///
+    /// impl Default for MyRngSeed {
+    ///     fn default() -> MyRngSeed {
+    ///         MyRngSeed([0; N])
+    ///     }
+    /// }
+    ///
+    /// impl AsMut<[u8]> for MyRngSeed {
+    ///     fn as_mut(&mut self) -> &mut [u8] {
+    ///         &mut self.0
+    ///     }
+    /// }
+    ///
+    /// impl SeedableRng for MyRng {
+    ///     type Seed = MyRngSeed;
+    ///
+    ///     fn from_seed(seed: MyRngSeed) -> MyRng {
+    ///         MyRng(seed)
+    ///     }
+    /// }
+    /// ```
     type Seed: Sized + Default + AsMut<[u8]>;
 
     /// Create a new PRNG using the given seed.