<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="API documentation for the Rust `RngCore` trait in crate `rand`."><metaname="keywords"content="rust, rustlang, rust-lang, RngCore"><title>rand::RngCore - Rust</title><linkrel="stylesheet"type="text/css"href="../normalize.css"><linkrel="stylesheet"type="text/css"href="../rustdoc.css"id="mainThemeStyle"><linkrel="stylesheet"type="text/css"href="../dark.css"><linkrel="stylesheet"type="text/css"href="../light.css"id="themeStyle"><scriptsrc="../storage.js"></script><noscript><linkrel="stylesheet"href="../noscript.css"></noscript><linkrel="shortcut icon"href="https://www.rust-lang.org/favicon.ico"><styletype="text/css">#crate-search{background-image:url("../down-arrow.svg");}</style></head><bodyclass="rustdoc trait"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="sidebar"><divclass="sidebar-menu">☰</div><ahref='../rand/index.html'><divclass='logo-container'><imgsrc='https://www.rust-lang.org/logos/rust-logo-128x128-blk.png'alt='logo'></div></a><pclass='location'>Trait RngCore</p><divclass="sidebar-elems"><divclass="block items"><aclass="sidebar-title"href="#required-methods">Required Methods</a><divclass="sidebar-links"><ahref="#tymethod.fill_bytes">fill_bytes</a><ahref="#tymethod.next_u32">next_u32</a><ahref="#tymethod.next_u64">next_u64</a><ahref="#tymethod.try_fill_bytes">try_fill_bytes</a></div><aclass="sidebar-title"href="#foreign-impls">Implementations on Foreign Types</a><divclass="sidebar-links"><ahref="#impl-RngCore-for-%26%27a%20mut%20R">&'a mut R</a><ahref="#impl-RngCore-for-BlockRng%3CR%3E">BlockRng<R></a><ahref="#impl-RngCore-for-BlockRng64%3CR%3E">BlockRng64<R></a><ahref="#impl-RngCore-for-Box%3CR%3E">Box<R></a><ahref="#impl-RngCore-for-ChaCha12Rng">ChaCha12Rng</a><ahref="#impl-RngCore-for-ChaCha20Rng">ChaCha20Rng</a><ahref="#impl-RngCore-for-ChaCha8Rng">ChaCha8Rng</a></div><aclass="sidebar-title"href="#implementors">Implementors</a><aclass="sidebar-title"href="#implementations">Trait Implementations</a><divclass="sidebar-links"><ahref="#impl-Read">Read</a></div></div><pclass='location'><ahref='index.html'>rand</a></p><script>window.sidebarCurrent={name:'RngCore',ty:'trait',relpath:''};</script><scriptdefersrc="sidebar-items.js"></script></div></nav><divclass="theme-picker"><buttonid="theme-picker"aria-label="Pick another theme!"><imgsrc="../brush.svg"width="18"alt="Pick another theme!"></button><divid="theme-choices"></div></div><scriptsrc="../theme.js"></script><navclass="sub"><formclass="search-form js-only"><divclass="search-container"><div><selectid="crate-search"><optionvalue="All crates">All crates</option></select><inputclass="search-input"name="search"autocomplete="off"spellcheck="false"placeholder="Click or press ‘S’ to search, ‘?’ for more options…"type="search"></div><aid="settings-menu"href="../settings.html"><imgsrc="../wheel.svg"width="18"alt="Change settings"></a></div></form></nav><sectionid="main"class="content"><h1class='fqn'><spanclass='out-of-band'><spanid='render-detail'><aid="toggle-all-docs"href="javascript:void(0)"title="collapse all docs">[<spanclass='inner'>−</span>]</a></span><aclass='srclink'href='../src/rand_core/lib.rs.html#138-185'title='goto source code'>[src]</a></span><spanclass='in-band'>Trait <ahref='index.html'>rand</a>::<wbr><aclass="trait"href=''>RngCore</a></span></h1><divclass="docblock type-decl hidden-by-usual-hider"><preclass='rust trait'>pub trait RngCore {
}</pre></div><divclass='docblock'><p>The core of a random number generator.</p>
<p>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 <code>Rng</code> trait from the <ahref="https://docs.rs/rand"><code>rand</code></a> crate,
which is automatically implemented for every type implementing <code>RngCore</code>.</p>
<p>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 <ahref="../rand/trait.RngCore.html#tymethod.fill_bytes"><code>fill_bytes</code></a> consume a whole number of <code>u32</code> or <code>u64</code>
values and drop any remaining unused bytes.</p>
<p>The <ahref="../rand/trait.RngCore.html#tymethod.try_fill_bytes"><code>try_fill_bytes</code></a> method is a variant of <ahref="../rand/trait.RngCore.html#tymethod.fill_bytes"><code>fill_bytes</code></a> allowing error
handling; it is not deemed sufficiently useful to add equivalents for
<ahref="../rand/trait.RngCore.html#tymethod.next_u32"><code>next_u32</code></a> or <ahref="../rand/trait.RngCore.html#tymethod.next_u64"><code>next_u64</code></a> since the latter methods are almost always used
with algorithmic generators (PRNGs), which are normally infallible.</p>
<p>Algorithmic generators implementing <ahref="../rand/trait.SeedableRng.html"title="`SeedableRng`"><code>SeedableRng</code></a> should normally have
<em>portable, reproducible</em> 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).</p>
<p>Typically implementators will implement only one of the methods available
in this trait directly, then use the helper functions from the
[<code>impls</code>] module to implement the other methods.</p>
<p>It is recommended that implementations also implement:</p>
<ul>
<li><code>Debug</code> with a custom implementation which <em>does not</em> print any internal
state (at least, <ahref="../rand/trait.CryptoRng.html"title="`CryptoRng`"><code>CryptoRng</code></a>s should not risk leaking state through
<code>Debug</code>).</li>
<li><code>Serialize</code> and <code>Deserialize</code> (from Serde), preferably making Serde
support optional at the crate level in PRNG libs.</li>
<li><code>Clone</code>, if possible.</li>
<li><em>never</em> implement <code>Copy</code> (accidental copies may cause repeated values).</li>
<li><em>do not</em> implement <code>Default</code> for pseudorandom generators, but instead
implement <ahref="../rand/trait.SeedableRng.html"title="`SeedableRng`"><code>SeedableRng</code></a>, to guide users towards proper seeding.
External / hardware RNGs can choose to implement <code>Default</code>.</li>
<li><code>Eq</code> and <code>PartialEq</code> could be implemented, but are probably not useful.</li>
<h2id='required-methods'class='small-section-header'>Required methods<ahref='#required-methods'class='anchor'></a></h2><divclass='methods'><h3id='tymethod.next_u32'class='method'><codeid='next_u32.v'>fn <ahref='#tymethod.next_u32'class='fnname'>next_u32</a>(&mut self) -><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u32.html">u32</a></code></h3><divclass='docblock'><p>Return the next random <code>u32</code>.</p>
<p>RNGs must implement at least one method from this trait directly. In
the case this method is not implemented directly, it can be implemented
</div><h3id='tymethod.next_u64'class='method'><codeid='next_u64.v'>fn <ahref='#tymethod.next_u64'class='fnname'>next_u64</a>(&mut self) -><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a></code></h3><divclass='docblock'><p>Return the next random <code>u64</code>.</p>
<p>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 [<code>next_u32</code>][impls::next_u64_via_u32] or via
</div><h3id='tymethod.fill_bytes'class='method'><codeid='fill_bytes.v'>fn <ahref='#tymethod.fill_bytes'class='fnname'>fill_bytes</a>(&mut self, dest: <aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&mut [</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>)</code></h3><divclass='docblock'><p>Fill <code>dest</code> with random data.</p>
<p>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 [<code>next_u*</code>][impls::fill_bytes_via_next] or
via <ahref="../rand/trait.RngCore.html#tymethod.try_fill_bytes"title="RngCore::try_fill_bytes"><code>try_fill_bytes</code></a>; 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).</p>
<p>This method should guarantee that <code>dest</code> 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).</p>
</div><h3id='tymethod.try_fill_bytes'class='method'><codeid='try_fill_bytes.v'>fn <ahref='#tymethod.try_fill_bytes'class='fnname'>try_fill_bytes</a>(&mut self, dest: <aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&mut [</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -><aclass="enum"href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>, <aclass="struct"href="../rand/struct.Error.html"title="struct rand::Error">Error</a>></code></h3><divclass='docblock'><p>Fill <code>dest</code> entirely with random data.</p>
<p>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. <code>OsRng</code>) which can fail. It may be used
directly to generate keys and to seed (infallible) PRNGs.</p>
<p>Other than error handling, this method is identical to <ahref="../rand/trait.RngCore.html#tymethod.fill_bytes"><code>fill_bytes</code></a>;
thus this may be implemented using <code>Ok(self.fill_bytes(dest))</code> or
<code>fill_bytes</code> may be implemented with
<code>self.try_fill_bytes(dest).unwrap()</code> or more specific error handling.</p>
</div></div><spanclass='loading-content'>Loading content...</span><h2id='implementations'class='small-section-header'>Trait Implementations<ahref='#implementations'class='anchor'></a></h2><divid='implementations-list'><h3id='impl-Read'class='impl'><codeclass='in-band'>impl <aclass="trait"href="https://doc.rust-lang.org/nightly/std/io/trait.Read.html"title="trait std::io::Read">Read</a> for dyn <aclass="trait"href="../rand/trait.RngCore.html"title="trait rand::RngCore">RngCore</a> + 'static</code><ahref='#impl-Read'class='anchor'></a><aclass='srclink'href='../src/rand_core/lib.rs.html#438-443'title='goto source code'>[src]</a></h3><divclass='impl-items'><h4id='method.read'class="method hidden"><codeid='read.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#tymethod.read'class='fnname'>read</a>(&mut self, buf: <aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&mut [</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -><aclass="enum"href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, <aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/error/struct.Error.html"title="struct std::io::error::Error">Error</a>></code><aclass='srclink'href='../src/rand_core/lib.rs.html#439-442'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Pull some bytes from this source into the specified buffer, returning how many bytes were read. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#tymethod.read">Read more</a></p>
</div><h4id='method.read_vectored'class="method hidden"><codeid='read_vectored.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_vectored'class='fnname'>read_vectored</a>(&mut self, bufs: <aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&mut [</a><aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/struct.IoSliceMut.html"title="struct std::io::IoSliceMut">IoSliceMut</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -><aclass="enum"href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, <aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/error/struct.Error.html"title="struct std::io::error::Error">Error</a>></code><spanclass='since'title='Stable since Rust version 1.36.0'>1.36.0</span><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#572-574'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Like <code>read</code>, except that it reads into a slice of buffers. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_vectored">Read more</a></p>
</div><h4id='method.initializer'class="method hidden"><codeid='initializer.v'>unsafe fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.initializer'class='fnname'>initializer</a>(&self) -><aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/struct.Initializer.html"title="struct std::io::Initializer">Initializer</a></code><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#600-602'title='goto source code'>[src]</a></h4><divclass='stability hidden'><divclass='stab unstable'><spanclass='emoji'>🔬</span> This is a nightly-only experimental API. (<code>read_initializer</code>)</div></div><divclass='docblock hidden'><p>Determines if this <code>Read</code>er can work with buffers of uninitialized memory. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.initializer">Read more</a></p>
</div><h4id='method.read_to_end'class="method hidden"><codeid='read_to_end.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_to_end'class='fnname'>read_to_end</a>(&mut self, buf: &mut <aclass="struct"href="https://doc.rust-lang.org/nightly/alloc/vec/struct.Vec.html"title="struct alloc::vec::Vec">Vec</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a>>) -><aclass="enum"href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, <aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/error/struct.Error.html"title="struct std::io::error::Error">Error</a>></code><spanclass='since'title='Stable since Rust version 1.0.0'>1.0.0</span><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#652-654'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Read all bytes until EOF in this source, placing them into <code>buf</code>. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_to_end">Read more</a></p>
</div><h4id='method.read_to_string'class="method hidden"><codeid='read_to_string.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_to_string'class='fnname'>read_to_string</a>(&mut self, buf: &mut <aclass="struct"href="https://doc.rust-lang.org/nightly/alloc/string/struct.String.html"title="struct alloc::string::String">String</a>) -><aclass="enum"href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>, <aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/error/struct.Error.html"title="struct std::io::error::Error">Error</a>></code><spanclass='since'title='Stable since Rust version 1.0.0'>1.0.0</span><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#695-706'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Read all bytes until EOF in this source, appending them to <code>buf</code>. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_to_string">Read more</a></p>
</div><h4id='method.read_exact'class="method hidden"><codeid='read_exact.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_exact'class='fnname'>read_exact</a>(&mut self, buf: <aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">&mut [</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>) -><aclass="enum"href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html"title="enum core::result::Result">Result</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.unit.html">()</a>, <aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/error/struct.Error.html"title="struct std::io::error::Error">Error</a>></code><spanclass='since'title='Stable since Rust version 1.6.0'>1.6.0</span><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#758-773'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Read the exact number of bytes required to fill <code>buf</code>. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.read_exact">Read more</a></p>
</div><h4id='method.by_ref'class="method hidden"><codeid='by_ref.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.by_ref'class='fnname'>by_ref</a>(&mut self) -><aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut </a>Self</code><spanclass='since'title='Stable since Rust version 1.0.0'>1.0.0</span><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#810'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Creates a "by reference" adaptor for this instance of <code>Read</code>. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.by_ref">Read more</a></p>
</div><h4id='method.bytes'class="method hidden"><codeid='bytes.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.bytes'class='fnname'>bytes</a>(self) -><aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/struct.Bytes.html"title="struct std::io::Bytes">Bytes</a><Self></code><spanclass='since'title='Stable since Rust version 1.0.0'>1.0.0</span><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#847-849'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Transforms this <code>Read</code> instance to an [<code>Iterator</code>] over its bytes. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.bytes">Read more</a></p>
</div><h4id='method.chain'class="method hidden"><codeid='chain.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.chain'class='fnname'>chain</a><R>(self, next: R) -><aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/struct.Chain.html"title="struct std::io::Chain">Chain</a><Self, R><spanclass="where fmt-newline">where<br> R: <aclass="trait"href="https://doc.rust-lang.org/nightly/std/io/trait.Read.html"title="trait std::io::Read">Read</a>, </span></code><spanclass='since'title='Stable since Rust version 1.0.0'>1.0.0</span><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#882-884'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Creates an adaptor which will chain this stream with another. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.chain">Read more</a></p>
</div><h4id='method.take'class="method hidden"><codeid='take.v'>fn <ahref='https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.take'class='fnname'>take</a>(self, limit: <aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a>) -><aclass="struct"href="https://doc.rust-lang.org/nightly/std/io/struct.Take.html"title="struct std::io::Take">Take</a><Self></code><spanclass='since'title='Stable since Rust version 1.0.0'>1.0.0</span><aclass='srclink'href='https://doc.rust-lang.org/nightly/src/std/io/mod.rs.html#918-920'title='goto source code'>[src]</a></h4><divclass='docblock hidden'><p>Creates an adaptor which will read at most <code>limit</code> bytes from it. <ahref="https://doc.rust-lang.org/nightly/std/io/trait.Read.html#method.take">Read more</a></p>
</script></section><sectionid="search"class="content hidden"></section><sectionclass="footer"></section><asideid="help"class="hidden"><div><h1class="hidden">Help</h1><divclass="shortcuts"><h2>Keyboard Shortcuts</h2><dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</dd></dl></div><divclass="infos"><h2>Search Tricks</h2><p>Prefix searches with a type followed by a colon (e.g., <code>fn:</code>) to restrict the search to a given type.</p><p>Accepted types are: <code>fn</code>, <code>mod</code>, <code>struct</code>, <code>enum</code>, <code>trait</code>, <code>type</code>, <code>macro</code>, and <code>const</code>.</p><p>Search functions by type signature (e.g., <code>vec -> usize</code> or <code>* -> vec</code>)</p><p>Search multiple things at once by splitting your query with comma (e.g., <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath="../";window.currentCrate="rand";</script><scriptsrc="../aliases.js"></script><scriptsrc="../main.js"></script><scriptdefersrc="../search-index.js"></script></body></html>
