|
|
|
|
|
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="API documentation for the Rust `SeedableRng` trait in crate `rand_core`."><meta name="keywords" content="rust, rustlang, rust-lang, SeedableRng"><title>rand_core::SeedableRng - Rust</title><link rel="stylesheet" type="text/css" href="../normalize.css"><link rel="stylesheet" type="text/css" href="../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../dark.css"><link rel="stylesheet" type="text/css" href="../light.css" id="themeStyle"><script src="../storage.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="shortcut icon" href="https://www.rust-lang.org/favicon.ico"><style type="text/css">#crate-search{background-image:url("../down-arrow.svg");}</style></head><body class="rustdoc trait"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../rand_core/index.html'><div class='logo-container'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk.png' alt='logo'></div></a><p class='location'>Trait SeedableRng</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#associated-types">Associated Types</a><div class="sidebar-links"><a href="#associatedtype.Seed">Seed</a></div><a class="sidebar-title" href="#required-methods">Required Methods</a><div class="sidebar-links"><a href="#tymethod.from_seed">from_seed</a></div><a class="sidebar-title" href="#provided-methods">Provided Methods</a><div class="sidebar-links"><a href="#method.from_rng">from_rng</a><a href="#method.seed_from_u64">seed_from_u64</a></div><a class="sidebar-title" href="#implementors">Implementors</a></div><p class='location'><a href='index.html'>rand_core</a></p><script>window.sidebarCurrent = {name: 'SeedableRng', ty: 'trait', relpath: ''};</script><script defer src="sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../theme.js"></script><nav class="sub"><form class="search-form js-only"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><a id="settings-menu" href="../settings.html"><img src="../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='out-of-band'><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>−</span>]</a></span><a class='srclink' href='../src/rand_core/lib.rs.html#221-368' title='goto source code'>[src]</a></span><span class='in-band'>Trait <a href='index.html'>rand_core</a>::<wbr><a class="trait" href=''>SeedableRng</a></span></h1><div class="docblock type-decl hidden-by-usual-hider"><pre class='rust trait'>pub trait SeedableRng {
|
|
|
|
|
|
type <a href='#associatedtype.Seed' class="type">Seed</a>: <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> + <a class="trait" href="https://doc.rust-lang.org/nightly/core/default/trait.Default.html" title="trait core::default::Default">Default</a> + <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsMut.html" title="trait core::convert::AsMut">AsMut</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>>;
|
|
|
|
|
|
fn <a href='#tymethod.from_seed' class='fnname'>from_seed</a>(seed: Self::<a class="type" href="../rand_core/trait.SeedableRng.html#associatedtype.Seed" title="type rand_core::SeedableRng::Seed">Seed</a>) -> Self;
|
|
|
|
|
|
|
|
|
|
|
|
fn <a href='#method.seed_from_u64' class='fnname'>seed_from_u64</a>(state: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a>) -> Self { ... }
|
|
|
|
|
|
<div class='item-spacer'></div> fn <a href='#method.from_rng' class='fnname'>from_rng</a><R>(rng: R) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><Self, <a class="struct" href="../rand_core/struct.Error.html" title="struct rand_core::Error">Error</a>><br> <span class="where">where<br> R: <a class="trait" href="../rand_core/trait.RngCore.html" title="trait rand_core::RngCore">RngCore</a></span>,
|
|
|
|
|
|
{ ... }
|
|
|
|
|
|
}</pre></div><div class='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>
|
|
|
|
|
|
<p>The <code>FromEntropy</code> trait from the <a href="https://docs.rs/rand"><code>rand</code></a> crate is automatically
|
|
|
|
|
|
implemented for every type implementing <code>SeedableRng</code>, providing
|
|
|
|
|
|
a convenient <code>from_entropy()</code> constructor.</p>
|
|
|
|
|
|
</div>
|
|
|
|
|
|
<h2 id='associated-types' class='small-section-header'>Associated Types<a href='#associated-types' class='anchor'></a></h2><div class='methods'><h3 id='associatedtype.Seed' class='method'><code id='Seed.t'>type <a href='#associatedtype.Seed' class="type">Seed</a>: <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> + <a class="trait" href="https://doc.rust-lang.org/nightly/core/default/trait.Default.html" title="trait core::default::Default">Default</a> + <a class="trait" href="https://doc.rust-lang.org/nightly/core/convert/trait.AsMut.html" title="trait core::convert::AsMut">AsMut</a><<a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">[</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u8.html">u8</a><a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.slice.html">]</a>></code></h3><div class='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>
|
|
|
|
|
|
<h1 id="implementing-seedablerng-for-rngs-with-large-seeds" class="section-header"><a href="#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
|
|
|
|
|
|
used:</p>
|
|
|
|
|
|
|
|
|
|
|
|
<div class="example-wrap"><pre class="rust rust-example-rendered">
|
|
|
|
|
|
<span class="kw">use</span> <span class="ident">rand_core</span>::<span class="ident">SeedableRng</span>;
|
|
|
|
|
|
|
|
|
|
|
|
<span class="kw">const</span> <span class="ident">N</span>: <span class="ident">usize</span> <span class="op">=</span> <span class="number">64</span>;
|
|
|
|
|
|
<span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">MyRngSeed</span>(<span class="kw">pub</span> [<span class="ident">u8</span>; <span class="ident">N</span>]);
|
|
|
|
|
|
<span class="kw">pub</span> <span class="kw">struct</span> <span class="ident">MyRng</span>(<span class="ident">MyRngSeed</span>);
|
|
|
|
|
|
|
|
|
|
|
|
<span class="kw">impl</span> <span class="ident">Default</span> <span class="kw">for</span> <span class="ident">MyRngSeed</span> {
|
|
|
|
|
|
<span class="kw">fn</span> <span class="ident">default</span>() <span class="op">-</span><span class="op">></span> <span class="ident">MyRngSeed</span> {
|
|
|
|
|
|
<span class="ident">MyRngSeed</span>([<span class="number">0</span>; <span class="ident">N</span>])
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
<span class="kw">impl</span> <span class="ident">AsMut</span><span class="op"><</span>[<span class="ident">u8</span>]<span class="op">></span> <span class="kw">for</span> <span class="ident">MyRngSeed</span> {
|
|
|
|
|
|
<span class="kw">fn</span> <span class="ident">as_mut</span>(<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">self</span>) <span class="op">-</span><span class="op">></span> <span class="kw-2">&</span><span class="kw-2">mut</span> [<span class="ident">u8</span>] {
|
|
|
|
|
|
<span class="kw-2">&</span><span class="kw-2">mut</span> <span class="self">self</span>.<span class="number">0</span>
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
<span class="kw">impl</span> <span class="ident">SeedableRng</span> <span class="kw">for</span> <span class="ident">MyRng</span> {
|
|
|
|
|
|
<span class="kw">type</span> <span class="ident">Seed</span> <span class="op">=</span> <span class="ident">MyRngSeed</span>;
|
|
|
|
|
|
|
|
|
|
|
|
<span class="kw">fn</span> <span class="ident">from_seed</span>(<span class="ident">seed</span>: <span class="ident">MyRngSeed</span>) <span class="op">-</span><span class="op">></span> <span class="ident">MyRng</span> {
|
|
|
|
|
|
<span class="ident">MyRng</span>(<span class="ident">seed</span>)
|
|
|
|
|
|
}
|
|
|
|
|
|
}</pre></div>
|
|
|
|
|
|
</div></div><span class='loading-content'>Loading content...</span>
|
|
|
|
|
|
<h2 id='required-methods' class='small-section-header'>Required methods<a href='#required-methods' class='anchor'></a></h2><div class='methods'><h3 id='tymethod.from_seed' class='method'><code id='from_seed.v'>fn <a href='#tymethod.from_seed' class='fnname'>from_seed</a>(seed: Self::<a class="type" href="../rand_core/trait.SeedableRng.html#associatedtype.Seed" title="type rand_core::SeedableRng::Seed">Seed</a>) -> Self</code></h3><div class='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 about equal, and values like 0, 1 and (size - 1) are unlikely.</p>
|
|
|
|
|
|
<p>PRNG implementations are recommended to be reproducible. A PRNG seeded
|
|
|
|
|
|
using this function with a fixed seed should produce the same sequence
|
|
|
|
|
|
of output in the future and on different architectures (with for example
|
|
|
|
|
|
different endianness).</p>
|
|
|
|
|
|
<p>It is however 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>
|
|
|
|
|
|
</div></div><span class='loading-content'>Loading content...</span>
|
|
|
|
|
|
<h2 id='provided-methods' class='small-section-header'>Provided methods<a href='#provided-methods' class='anchor'></a></h2><div class='methods'><h3 id='method.seed_from_u64' class='method'><code id='seed_from_u64.v'>fn <a href='#method.seed_from_u64' class='fnname'>seed_from_u64</a>(state: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a>) -> Self</code></h3><div class='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><h3 id='method.from_rng' class='method'><code id='from_rng.v'>fn <a href='#method.from_rng' class='fnname'>from_rng</a><R>(rng: R) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><Self, <a class="struct" href="../rand_core/struct.Error.html" title="struct rand_core::Error">Error</a>> <span class="where fmt-newline">where<br> R: <a class="trait" href="../rand_core/trait.RngCore.html" title="trait rand_core::RngCore">RngCore</a>, </span></code></h3><div class='docblock'><p>Create a new PRNG seeded from another <code>Rng</code>.</p>
|
|
|
|
|
|
<p>This is the recommended way to initialize PRNGs with fresh entropy. The
|
|
|
|
|
|
<code>FromEntropy</code> trait from the <a href="https://docs.rs/rand"><code>rand</code></a> crate provides a convenient
|
|
|
|
|
|
<code>from_entropy</code> method based on <code>from_rng</code>.</p>
|
|
|
|
|
|
<p>Usage of this method is not recommended when reproducibility is required
|
|
|
|
|
|
since implementing PRNGs are not required to fix Endianness and are
|
|
|
|
|
|
allowed to modify implementations in new releases.</p>
|
|
|
|
|
|
<p>It is important to use a good source of randomness to initialize the
|
|
|
|
|
|
PRNG. Cryptographic PRNG may be rendered insecure when seeded from a
|
|
|
|
|
|
non-cryptographic PRNG or with insufficient entropy.
|
|
|
|
|
|
Many non-cryptographic PRNGs will show statistical bias in their first
|
|
|
|
|
|
results if their seed numbers are small or if there is a simple pattern
|
|
|
|
|
|
between them.</p>
|
|
|
|
|
|
<p>Prefer to seed from a strong external entropy source like <code>OsRng</code> from
|
|
|
|
|
|
the <a href="https://docs.rs/rand_os"><code>rand_os</code></a> crate or from a cryptographic PRNG; if creating a new
|
|
|
|
|
|
generator for cryptographic uses you <em>must</em> seed from a strong source.</p>
|
|
|
|
|
|
<p>Seeding a small PRNG from another small PRNG is possible, but
|
|
|
|
|
|
something to be careful with. An extreme example of how this can go
|
|
|
|
|
|
wrong is seeding an Xorshift RNG from another Xorshift RNG, which
|
|
|
|
|
|
will effectively clone the generator. In general seeding from a
|
|
|
|
|
|
generator which is hard to predict is probably okay.</p>
|
|
|
|
|
|
<p>PRNG implementations are allowed to assume that a good RNG is provided
|
|
|
|
|
|
for seeding, and that it is cryptographically secure when appropriate.</p>
|
|
|
|
|
|
</div></div><span class='loading-content'>Loading content...</span>
|
|
|
|
|
|
<h2 id='implementors' class='small-section-header'>Implementors<a href='#implementors' class='anchor'></a></h2><div class='item-list' id='implementors-list'><h3 id='impl-SeedableRng' class='impl'><code class='in-band'>impl<R> SeedableRng for <a class="struct" href="../rand_core/block/struct.BlockRng.html" title="struct rand_core::block::BlockRng">BlockRng</a><R> <span class="where fmt-newline">where<br> R: <a class="trait" href="../rand_core/block/trait.BlockRngCore.html" title="trait rand_core::block::BlockRngCore">BlockRngCore</a> + <a class="trait" href="../rand_core/trait.SeedableRng.html" title="trait rand_core::SeedableRng">SeedableRng</a>, </span></code><a href='#impl-SeedableRng' class='anchor'></a><a class='srclink' href='../src/rand_core/block.rs.html#275-289' title='goto source code'>[src]</a></h3><div class='impl-items'><h4 id='associatedtype.Seed-1' class="type"><code id='Seed.t-1'>type <a href='#associatedtype.Seed-1' class="type">Seed</a> = <R as <a class="trait" href="../rand_core/trait.SeedableRng.html" title="trait rand_core::SeedableRng">SeedableRng</a>>::<a class="type" href="../rand_core/trait.SeedableRng.html#associatedtype.Seed" title="type rand_core::SeedableRng::Seed">Seed</a></code></h4><h4 id='method.from_seed' class="method hidden"><code id='from_seed.v-1'>fn <a href='#method.from_seed' class='fnname'>from_seed</a>(seed: <<a class="struct" href="../rand_core/block/struct.BlockRng.html" title="struct rand_core::block::BlockRng">BlockRng</a><R> as <a class="trait" href="../rand_core/trait.SeedableRng.html" title="trait rand_core::SeedableRng">SeedableRng</a>>::<a class="type" href="../rand_core/trait.SeedableRng.html#associatedtype.Seed" title="type rand_core::SeedableRng::Seed">Seed</a>) -> <a class="struct" href="../rand_core/block/struct.BlockRng.html" title="struct rand_core::block::BlockRng">BlockRng</a><R></code><a class='srclink' href='../src/rand_core/block.rs.html#278-280' title='goto source code'>[src]</a></h4><h4 id='method.seed_from_u64-1' class="method hidden"><code id='seed_from_u64.v-1'>fn <a href='#method.seed_from_u64-1' class='fnname'>seed_from_u64</a>(seed: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.u64.html">u64</a>) -> <a class="struct" href="../rand_core/block/struct.BlockRng.html" title="struct rand_core::block::BlockRng">BlockRng</a><R></code><a class='srclink' href='../src/rand_core/block.rs.html#282-284' title='goto source code'>[src]</a></h4><h4 id='method.from_rng-1' class="method hidden"><code id='from_rng.v-1'>fn <a href='#method.from_rng-1' class='fnname'>from_rng</a><S>(rng: S) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a><<a class="struct" href="../rand_core/block/struct.BlockRng.html" title="struct rand_core::block::BlockRng">BlockRng</a><R>, <a class="struct" href="../rand_core/struct.Error.html" title="struct rand_core::Error">Error</a>> <span class="where fmt-newline">where<br> S: <a class="trait" href="../rand_core/trait.RngCore.html" title="trait rand_core::RngCore">RngCore</a>, </span></code><a class='srclink' href='../src/rand_core/block.rs.html#286-288' title='goto source code'>[src]</a></h4></div><h3 id='impl-SeedableRng-1' class='impl'><code class='in-band'>impl<R> SeedableRng for <a class="struct" href="../rand_core/block/struct.BlockRng64.html" title="struct rand_core::block::BlockRng64">BlockRng64</a><R> <span class="where fmt-newline">where<br> R: <a class="trait" href="../rand_core/block/trait.BlockRngCore.html" title="trait rand_core::block::BlockRngCore">BlockRngCore</a> + <a class="trait" href="../rand_core/trait.SeedableRng.html" title="trait rand_core::SeedableRng">SeedableRng</a>, </span></code><a href='#impl-SeedableRng-1' class='anchor'></a><a class='srclink' href='../src/rand_core/block.rs.html#483-497' title='goto source code'>[src]</a></h3><div
|
|
|
|
|
|
src="../implementors/rand_core/trait.SeedableRng.js">
|
|
|
|
|
|
</script></section><section id="search" class="content hidden"></section><section class="footer"></section><aside id="help" class="hidden"><div><h1 class="hidden">Help</h1><div class="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><div class="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_core";</script><script src="../aliases.js"></script><script src="../main.js"></script><script defer src="../search-index.js"></script></body></html>
|
