RONCC
/
HPC-Tools-for-Quantum-Computing


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115
							<!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><link rel="shortcut icon" href="https://www.rust-lang.org/favicon.ico"></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">&#9776;</div><a href='../rand_core/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk.png' alt='logo' width='100'></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></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"><input class="search-input" name="search" autocomplete="off" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><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='in-band'>Trait <a href='index.html'>rand_core</a>::<wbr><a class="trait" href=''>SeedableRng</a></span><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'>&#x2212;</span>]</a></span><a class='srclink' href='../src/rand_core/lib.rs.html#230-338' title='goto source code'>[src]</a></span></h1><div class="docblock type-decl"><pre class='rust trait'>pub trait SeedableRng: <a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a> {
    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>&lt;<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>&gt;;
    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>) -&gt; Self;

    fn <a href='#method.from_rng' class='fnname'>from_rng</a>&lt;R:&nbsp;<a class="trait" href="../rand_core/trait.RngCore.html" title="trait rand_core::RngCore">RngCore</a>&gt;(rng: R) -&gt; <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;Self, <a class="struct" href="../rand_core/struct.Error.html" title="struct rand_core::Error">Error</a>&gt; { ... }
}</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 <a href="../rand/trait.FromEntropy.html"><code>rand::FromEntropy</code></a> trait 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'><span id='Seed.t' class='invisible'><code>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>&lt;<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>&gt;</code></span></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&lt;u8&gt;</code> are not implemented for large arrays
<code>[u8; N]</code> with <code>N</code> &gt; 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>

<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">-&gt;</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">&lt;</span>[<span class="ident">u8</span>]<span class="op">&gt;</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">&amp;</span><span class="kw-2">mut</span> <span class="self">self</span>) <span class="op">-&gt;</span> <span class="kw-2">&amp;</span><span class="kw-2">mut</span> [<span class="ident">u8</span>] {
        <span class="kw-2">&amp;</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">-&gt;</span> <span class="ident">MyRng</span> {
        <span class="ident">MyRng</span>(<span class="ident">seed</span>)
    }
}</pre>
</div></div>
            <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'><span id='from_seed.v' class='invisible'><code>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>) -&gt; Self</code></span></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> (&quot;odd biases? bad
seed&quot;). This is assuming only a small number of values must be rejected.</p>
</div></div>
            <h2 id='provided-methods' class='small-section-header'>
              Provided Methods<a href='#provided-methods' class='anchor'></a>
            </h2>
            <div class='methods'>
        <h3 id='method.from_rng' class='method'><span id='from_rng.v' class='invisible'><code>fn <a href='#method.from_rng' class='fnname'>from_rng</a>&lt;R:&nbsp;<a class="trait" href="../rand_core/trait.RngCore.html" title="trait rand_core::RngCore">RngCore</a>&gt;(rng: R) -&gt; <a class="enum" href="https://doc.rust-lang.org/nightly/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;Self, <a class="struct" href="../rand_core/struct.Error.html" title="struct rand_core::Error">Error</a>&gt;</code></span></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
<a href="../rand/trait.FromEntropy.html"><code>FromEntropy</code></a> trait 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 <a href="../rand/rngs/struct.OsRng.html"><code>OsRng</code></a> 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>
        <h2 id='implementors' class='small-section-header'>
          Implementors<a href='#implementors' class='anchor'></a>
        </h2>
        <ul class='item-list' id='implementors-list'>
    <li><table class='table-display'><tbody><tr><td><code>impl&lt;R:&nbsp;<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>&gt; SeedableRng for <a class="struct" href="../rand_core/block/struct.BlockRng.html" title="struct rand_core::block::BlockRng">BlockRng</a>&lt;R&gt;<span class="where fmt-newline">  type <a href='#associatedtype.Seed' class="type">Seed</a> = R::<a class="type" href="../rand_core/trait.SeedableRng.html#associatedtype.Seed" title="type rand_core::SeedableRng::Seed">Seed</a>;</span></code><td><div class='out-of-band'><a class='srclink' href='../src/rand_core/block.rs.html#283-293' title='goto source code'>[src]</a></div></td></tr></tbody></table></li>
<li><table class='table-display'><tbody><tr><td><code>impl&lt;R:&nbsp;<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>&gt; SeedableRng for <a class="struct" href="../rand_core/block/struct.BlockRng64.html" title="struct rand_core::block::BlockRng64">BlockRng64</a>&lt;R&gt;<span class="where fmt-newline">  type <a href='#associatedtype.Seed' class="type">Seed</a> = R::<a class="type" href="../rand_core/trait.SeedableRng.html#associatedtype.Seed" title="type rand_core::SeedableRng::Seed">Seed</a>;</span></code><td><div class='out-of-band'><a class='srclink' href='../src/rand_core/block.rs.html#490-500' title='goto source code'>[src]</a></div></td></tr></tbody></table></li>
</ul><script type="text/javascript">window.inlined_types=new Set([]);</script><script type="text/javascript" async
                         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>&#9166;</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>