<!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 `SeedableRng` trait in crate `rand`."><metaname="keywords"content="rust, rustlang, rust-lang, SeedableRng"><title>rand::SeedableRng - 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 SeedableRng</p><divclass="sidebar-elems"><divclass="block items"><aclass="sidebar-title"href="#associated-types">Associated Types</a><divclass="sidebar-links"><ahref="#associatedtype.Seed">Seed</a></div><aclass="sidebar-title"href="#required-methods">Required Methods</a><divclass="sidebar-links"><ahref="#tymethod.from_seed">from_seed</a></div><aclass="sidebar-title"href="#provided-methods">Provided Methods</a><divclass="sidebar-links"><ahref="#method.from_entropy">from_entropy</a><ahref="#method.from_rng">from_rng</a><ahref="#method.seed_from_u64">seed_from_u64</a></div><aclass="sidebar-title"href="#foreign-impls">Implementations on Foreign Types</a><divclass="sidebar-links"><ahref="#impl-SeedableRng-for-BlockRng%3CR%3E">BlockRng<R></a><ahref="#impl-SeedableRng-for-BlockRng64%3CR%3E">BlockRng64<R></a><ahref="#impl-SeedableRng-for-ChaCha12Core">ChaCha12Core</a><ahref="#impl-SeedableRng-for-ChaCha12Rng">ChaCha12Rng</a><ahref="#impl-SeedableRng-for-ChaCha20Core">ChaCha20Core</a><ahref="#impl-SeedableRng-for-ChaCha20Rng">ChaCha20Rng</a><ahref="#impl-SeedableRng-for-ChaCha8Core">ChaCha8Core</a><ahref="#impl-SeedableRng-for-ChaCha8Rng">ChaCha8Rng</a></div><aclass="sidebar-title"href="#implementors">Implementors</a></div><pclass='location'><ahref='index.html'>rand</a></p><script>window.sidebarCurrent={name:'SeedableRng',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#217-384'title='goto source code'>[src]</a></span><spanclass='in-band'>Trait <ahref='index.html'>rand</a>::<wbr><aclass="trait"href=''>SeedableRng</a></span></h1><divclass="docblock type-decl hidden-by-usual-hider"><preclass='rust trait'>pub trait SeedableRng {
type <ahref='#associatedtype.Seed'class="type">Seed</a>: <aclass="trait"href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html"title="trait core::marker::Sized">Sized</a> + <aclass="trait"href="https://doc.rust-lang.org/nightly/core/default/trait.Default.html"title="trait core::default::Default">Default</a> + <aclass="trait"href="https://doc.rust-lang.org/nightly/core/convert/trait.AsMut.html"title="trait core::convert::AsMut">AsMut</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">[</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>>;
}</pre></div><divclass='docblock'><p>A random number generator that can be explicitly seeded.</p>
<p>This trait encapsulates the low-level functionality common to all
pseudo-random number generators (PRNGs, or algorithmic generators).</p>
</div>
<h2id='associated-types'class='small-section-header'>Associated Types<ahref='#associated-types'class='anchor'></a></h2><divclass='methods'><h3id='associatedtype.Seed'class='method'><codeid='Seed.t'>type <ahref='#associatedtype.Seed'class="type">Seed</a>: <aclass="trait"href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html"title="trait core::marker::Sized">Sized</a> + <aclass="trait"href="https://doc.rust-lang.org/nightly/core/default/trait.Default.html"title="trait core::default::Default">Default</a> + <aclass="trait"href="https://doc.rust-lang.org/nightly/core/convert/trait.AsMut.html"title="trait core::convert::AsMut">AsMut</a><<aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">[</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>Seed type, which is restricted to types mutably-dereferencable as <code>u8</code>
arrays (we recommend <code>[u8; N]</code> for some <code>N</code>).</p>
<p>It is recommended to seed PRNGs with a seed of at least circa 100 bits,
which means an array of <code>[u8; 12]</code> or greater to avoid picking RNGs with
partially overlapping periods.</p>
<p>For cryptographic RNG's a seed of 256 bits is recommended, <code>[u8; 32]</code>.</p>
<h1id="implementing-seedablerng-for-rngs-with-large-seeds"class="section-header"><ahref="#implementing-seedablerng-for-rngs-with-large-seeds">Implementing <code>SeedableRng</code> for RNGs with large seeds</a></h1>
<p>Note that the required traits <code>core::default::Default</code> and
<code>core::convert::AsMut<u8></code> are not implemented for large arrays
<code>[u8; N]</code> with <code>N</code>> 32. To be able to implement the traits required by
<code>SeedableRng</code> for RNGs with such large seeds, the newtype pattern can be
<h2id='required-methods'class='small-section-header'>Required methods<ahref='#required-methods'class='anchor'></a></h2><divclass='methods'><h3id='tymethod.from_seed'class='method'><codeid='from_seed.v'>fn <ahref='#tymethod.from_seed'class='fnname'>from_seed</a>(seed: Self::<aclass="type"href="../rand/trait.SeedableRng.html#associatedtype.Seed"title="type rand::SeedableRng::Seed">Seed</a>) -> Self</code></h3><divclass='docblock'><p>Create a new PRNG using the given seed.</p>
<p>PRNG implementations are allowed to assume that bits in the seed are
well distributed. That means usually that the number of one and zero
bits are roughly equal, and values like 0, 1 and (size - 1) are unlikely.
Note that many non-cryptographic PRNGs will show poor quality output
if this is not adhered to. If you wish to seed from simple numbers, use
<code>seed_from_u64</code> instead.</p>
<p>All PRNG implementations should be reproducible unless otherwise noted:
given a fixed <code>seed</code>, the same sequence of output should be produced
on all runs, library versions and architectures (e.g. check endianness).
Any "value-breaking" changes to the generator should require bumping at
least the minor version and documentation of the change.</p>
<p>It is not required that this function yield the same state as a
reference implementation of the PRNG given equivalent seed; if necessary
another constructor replicating behaviour from a reference
implementation can be added.</p>
<p>PRNG implementations should make sure <code>from_seed</code> never panics. In the
case that some special values (like an all zero seed) are not viable
seeds it is preferable to map these to alternative constant value(s),
for example <code>0xBAD5EEDu32</code> or <code>0x0DDB1A5E5BAD5EEDu64</code> ("odd biases? bad
seed"). This is assuming only a small number of values must be rejected.</p>
<h2id='provided-methods'class='small-section-header'>Provided methods<ahref='#provided-methods'class='anchor'></a></h2><divclass='methods'><h3id='method.seed_from_u64'class='method'><codeid='seed_from_u64.v'>fn <ahref='#method.seed_from_u64'class='fnname'>seed_from_u64</a>(state: <aclass="primitive"href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a>) -> Self</code></h3><divclass='docblock'><p>Create a new PRNG using a <code>u64</code> seed.</p>
<p>This is a convenience-wrapper around <code>from_seed</code> to allow construction
of any <code>SeedableRng</code> from a simple <code>u64</code> value. It is designed such that
low Hamming Weight numbers like 0 and 1 can be used and should still
result in good, independent seeds to the PRNG which is returned.</p>
<p>This <strong>is not suitable for cryptography</strong>, as should be clear given that
the input size is only 64 bits.</p>
<p>Implementations for PRNGs <em>may</em> provide their own implementations of
this function, but the default implementation should be good enough for
all purposes. <em>Changing</em> the implementation of this function should be
considered a value-breaking change.</p>
</div><h3id='method.from_rng'class='method'><codeid='from_rng.v'>fn <ahref='#method.from_rng'class='fnname'>from_rng</a><R>(rng: R) -><aclass="enum"href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html"title="enum core::result::Result">Result</a><Self, <aclass="struct"href="../rand/struct.Error.html"title="struct rand::Error">Error</a>><spanclass="where fmt-newline">where<br> R: <aclass="trait"href="../rand/trait.RngCore.html"title="trait rand::RngCore">RngCore</a>, </span></code></h3><divclass='docblock'><p>Create a new PRNG seeded from another <code>Rng</code>.</p>
<p>This may be useful when needing to rapidly seed many PRNGs from a master
PRNG, and to allow forking of PRNGs. It may be considered deterministic.</p>
<p>The master PRNG should be at least as high quality as the child PRNGs.
When seeding non-cryptographic child PRNGs, we recommend using a
different algorithm for the master PRNG (ideally a CSPRNG) to avoid
correlations between the child PRNGs. If this is not possible (e.g.
forking using small non-crypto PRNGs) ensure that your PRNG has a good
mixing function on the output or consider use of a hash function with
<code>from_seed</code>.</p>
<p>Note that seeding <code>XorShiftRng</code> from another <code>XorShiftRng</code> provides an
extreme example of what can go wrong: the new PRNG will be a clone
of the parent.</p>
<p>PRNG implementations are allowed to assume that a good RNG is provided
for seeding, and that it is cryptographically secure when appropriate.
As of <code>rand</code> 0.7 / <code>rand_core</code> 0.5, implementations overriding this
method should ensure the implementation satisfies reproducibility
(in prior versions this was not required).</p>
</div><h3id='method.from_entropy'class='method'><codeid='from_entropy.v'>fn <ahref='#method.from_entropy'class='fnname'>from_entropy</a>() -> Self</code></h3><divclass='docblock'><p>Creates a new instance of the RNG seeded via <ahref="https://docs.rs/getrandom"><code>getrandom</code></a>.</p>
<p>This method is the recommended way to construct non-deterministic PRNGs
since it is convenient and secure.</p>
<p>In case the overhead of using <ahref="https://docs.rs/getrandom"><code>getrandom</code></a> to seed <em>many</em> PRNGs is an
issue, one may prefer to seed from a local PRNG, e.g.
</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>
