rusty-man/tests/snapshots/output__1.40.0_html_trait_rand_core_rngcore.snap

---
source: tests/output.rs
expression: "get_stdout(&[item])"
---
rand_core                             Trait rand_core::RngCore                             rusty-man

SYNOPSIS
      pub trait RngCore {
          fn next_u32(&mut self) -> u32;
          fn next_u64(&mut self) -> u64;
          fn fill_bytes(&mut self, dest: &mut [u8]);
          fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>;
      }

DESCRIPTION
      The core of a random number generator.
      
      This trait encapsulates the low-level functionality common to all generators, and is the "back
      end", to be implemented by generators. End users should normally use the `Rng` trait from the
      [`rand`][1] crate, which is automatically implemented for every type implementing `RngCore`.
      
      Three different methods for generating random data are provided since the optimal
      implementation of each is dependent on the type of generator. There is no required
      relationship between the output of each; e.g. many implementations of `fill_bytes` consume a
      whole number of `u32` or `u64` values and drop any remaining unused bytes.
      
      The `try_fill_bytes` method is a variant of `fill_bytes` allowing error handling; it is not
      deemed sufficiently useful to add equivalents for `next_u32` or `next_u64` since the latter
      methods are almost always used with algorithmic generators (PRNGs), which are normally
      infallible.
      
      Algorithmic generators implementing [`SeedableRng`] should normally have *portable,
      reproducible* output, i.e. fix Endianness when converting values to avoid platform
      differences, and avoid making any changes which affect output (except by communicating that
      the release has breaking changes).
      
      Typically implementators will implement only one of the methods available in this trait
      directly, then use the helper functions from the [`impls`] module to implement the other
      methods.
      
      It is recommended that implementations also implement:
      
      * `Debug` with a custom implementation which *does not* print any internal state (at least,
        [`CryptoRng`]s should not risk leaking state through `Debug`).
      * `Serialize` and `Deserialize` (from Serde), preferably making Serde support optional at the
        crate level in PRNG libs.
      * `Clone`, if possible.
      * *never* implement `Copy` (accidental copies may cause repeated values).
      * *do not* implement `Default` for pseudorandom generators, but instead implement
        [`SeedableRng`], to guide users towards proper seeding. External / hardware RNGs can choose
        to implement `Default`.
      * `Eq` and `PartialEq` could be implemented, but are probably not useful.
      
      
      # Example
      
      A simple example, obviously not generating very *random* output:
      
      #![allow(dead_code)]
      use rand_core::{RngCore, Error, impls};
      struct CountingRng(u64);
      impl RngCore for CountingRng {
          fn next_u32(&mut self) -> u32 {
              self.next_u64() as u32
          }
          fn next_u64(&mut self) -> u64 {
              self.0 += 1;
              self.0
          }
          fn fill_bytes(&mut self, dest: &mut [u8]) {
              impls::fill_bytes_via_next(self, dest)
          }
          fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error> {
              Ok(self.fill_bytes(dest))
          }
      }
      
      [1] https://docs.rs/rand

METHODS
   Required Methods
      next_u32
            fn next_u32(&mut self) -> u32

            Return the next random `u32`.
            
            RNGs must implement at least one method from this trait directly. In the case this
            method is not implemented directly, it can be implemented using `self.next_u64() as u32`
            or via `fill_bytes`.

      next_u64
            fn next_u64(&mut self) -> u64

            Return the next random `u64`.
            
            RNGs must implement at least one method from this trait directly. In the case this
            method is not implemented directly, it can be implemented via `next_u32` or via
            `fill_bytes`.

      fill_bytes
            fn fill_bytes(&mut self, dest: &mut [u8])

            Fill `dest` with random data.
            
            RNGs must implement at least one method from this trait directly. In the case this
            method is not implemented directly, it can be implemented via `next_u*` or via
            `try_fill_bytes`; if this generator can fail the implementation must choose how best to
            handle errors here (e.g. panic with a descriptive message or log a warning and retry a
            few times).
            
            This method should guarantee that `dest` is entirely filled with new data, and may panic
            if this is impossible (e.g. reading past the end of a file that is being used as the
            source of randomness).

      try_fill_bytes
            fn try_fill_bytes(&mut self, dest: &mut [u8]) -> Result<(), Error>

            Fill `dest` entirely with random data.
            
            This is the only method which allows an RNG to report errors while generating random
            data thus making this the primary method implemented by external (true) RNGs (e.g.
            `OsRng`) which can fail. It may be used directly to generate keys and to seed
            (infallible) PRNGs.
            
            Other than error handling, this method is identical to `fill_bytes`; thus this may be
            implemented using `Ok(self.fill_bytes(dest))` or `fill_bytes` may be implemented with
            `self.try_fill_bytes(dest).unwrap()` or more specific error handling.

IMPLEMENTATIONS
   Trait Implementations
      Read
            impl Read for dyn RngCore