You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

68 lines
9.2 KiB

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

<!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="Generates a random value using the thread-local random number generator."><meta name="keywords" content="rust, rustlang, rust-lang, random"><title>random in rand - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Regular.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../FiraSans-Medium.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Regular.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceSerif4-Bold.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../SourceCodePro-Semibold.ttf.woff2"><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="../ayu.css" disabled><link rel="stylesheet" type="text/css" href="../dark.css" disabled><link rel="stylesheet" type="text/css" href="../light.css" id="themeStyle"><script id="default-settings" ></script><script src="../storage.js"></script><script src="../crates.js"></script><script defer src="../main.js"></script>
<noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="icon" href="https://www.rust-lang.org/favicon.ico"></head><body class="rustdoc fn"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle">&#9776;</button><a class="sidebar-logo" href="../rand/index.html"><div class="logo-container"><img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk.png" alt="logo"></div>
</a><h2 class="location"></h2>
</nav>
<nav class="sidebar"><a class="sidebar-logo" href="../rand/index.html"><div class="logo-container">
<img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk.png" alt="logo"></div>
</a><div class="sidebar-elems"><h2 class="location"><a href="index.html">In rand</a></h2><div id="sidebar-vars" data-name="random" data-ty="fn" data-relpath=""></div><script defer src="sidebar-items.js"></script></div></nav><main><div class="width-limiter"><div class="sub-container"><a class="sub-logo-container" href="../rand/index.html">
<img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk.png" alt="logo"></a><nav class="sub"><div class="theme-picker hidden"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu" title="themes"><img width="22" height="22" alt="Pick another theme!" src="../brush.svg"></button><div id="theme-choices" role="menu"></div></div><form class="search-form"><div class="search-container"><span></span><input class="search-input" name="search" autocomplete="off" spellcheck="false" placeholder="Click or press S to search, ? for more options…" type="search"><button type="button" id="help-button" title="help">?</button><a id="settings-menu" href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../wheel.svg"></a></div></form></nav></div><section id="main-content" class="content"><div class="main-heading">
<h1 class="fqn"><span class="in-band">Function <a href="index.html">rand</a>::<wbr><a class="fn" href="#">random</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../clipboard.svg" width="19" height="18" alt="Copy item path"></button></span></h1><span class="out-of-band"><a class="srclink" href="../src/rand/lib.rs.html#183-186">source</a> · <a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">&#x2212;</span>]</a></span></div><div class="docblock item-decl"><pre class="rust fn"><code>pub fn random&lt;T&gt;() -&gt; T <span class="where fmt-newline">where<br>&nbsp;&nbsp;&nbsp;&nbsp;<a class="struct" href="distributions/struct.Standard.html" title="struct rand::distributions::Standard">Standard</a>: <a class="trait" href="distributions/trait.Distribution.html" title="trait rand::distributions::Distribution">Distribution</a>&lt;T&gt;,&nbsp;</span></code></pre></div><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Generates a random value using the thread-local random number generator.</p>
<p>This is simply a shortcut for <code>thread_rng().gen()</code>. See <a href="fn.thread_rng.html" title="thread_rng"><code>thread_rng</code></a> for
documentation of the entropy source and <a href="distributions/struct.Standard.html"><code>Standard</code></a> for documentation of
distributions and type-specific generation.</p>
<h2 id="provided-implementations"><a href="#provided-implementations">Provided implementations</a></h2>
<p>The following types have provided implementations that
generate values with the following ranges and distributions:</p>
<ul>
<li>Integers (<code>i32</code>, <code>u32</code>, <code>isize</code>, <code>usize</code>, etc.): Uniformly distributed
over all values of the type.</li>
<li><code>char</code>: Uniformly distributed over all Unicode scalar values, i.e. all
code points in the range <code>0...0x10_FFFF</code>, except for the range
<code>0xD800...0xDFFF</code> (the surrogate code points). This includes
unassigned/reserved code points.</li>
<li><code>bool</code>: Generates <code>false</code> or <code>true</code>, each with probability 0.5.</li>
<li>Floating point types (<code>f32</code> and <code>f64</code>): Uniformly distributed in the
half-open range <code>[0, 1)</code>. See notes below.</li>
<li>Wrapping integers (<code>Wrapping&lt;T&gt;</code>), besides the type identical to their
normal integer variants.</li>
</ul>
<p>Also supported is the generation of the following
compound types where all component types are supported:</p>
<ul>
<li>Tuples (up to 12 elements): each element is generated sequentially.</li>
<li>Arrays (up to 32 elements): each element is generated sequentially;
see also <a href="trait.Rng.html#method.fill" title="Rng::fill"><code>Rng::fill</code></a> which supports arbitrary array length for integer
types and tends to be faster for <code>u32</code> and smaller types.</li>
<li><code>Option&lt;T&gt;</code> first generates a <code>bool</code>, and if true generates and returns
<code>Some(value)</code> where <code>value: T</code>, otherwise returning <code>None</code>.</li>
</ul>
<h2 id="examples"><a href="#examples">Examples</a></h2>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">let</span> <span class="ident">x</span> <span class="op">=</span> <span class="ident">rand::random</span>::<span class="op">&lt;</span><span class="ident">u8</span><span class="op">&gt;</span>();
<span class="macro">println!</span>(<span class="string">&quot;{}&quot;</span>, <span class="ident">x</span>);
<span class="kw">let</span> <span class="ident">y</span> <span class="op">=</span> <span class="ident">rand::random</span>::<span class="op">&lt;</span><span class="ident">f64</span><span class="op">&gt;</span>();
<span class="macro">println!</span>(<span class="string">&quot;{}&quot;</span>, <span class="ident">y</span>);
<span class="kw">if</span> <span class="ident">rand::random</span>() { <span class="comment">// generates a boolean</span>
<span class="macro">println!</span>(<span class="string">&quot;Better lucky than good!&quot;</span>);
}</code></pre></div>
<p>If youre calling <code>random()</code> in a loop, caching the generator as in the
following example can increase performance.</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use</span> <span class="ident">rand::Rng</span>;
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">v</span> <span class="op">=</span> <span class="macro">vec!</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>];
<span class="kw">for</span> <span class="ident">x</span> <span class="kw">in</span> <span class="ident">v</span>.<span class="ident">iter_mut</span>() {
<span class="kw-2">*</span><span class="ident">x</span> <span class="op">=</span> <span class="ident">rand::random</span>()
}
<span class="comment">// can be made faster by caching thread_rng</span>
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">rng</span> <span class="op">=</span> <span class="ident">rand::thread_rng</span>();
<span class="kw">for</span> <span class="ident">x</span> <span class="kw">in</span> <span class="ident">v</span>.<span class="ident">iter_mut</span>() {
<span class="kw-2">*</span><span class="ident">x</span> <span class="op">=</span> <span class="ident">rng</span>.<span class="ident">gen</span>();
}</code></pre></div>
</div></details></section></div></main><div id="rustdoc-vars" data-root-path="../" data-current-crate="rand" data-themes="ayu,dark,light" data-resource-suffix="" data-rustdoc-version="1.62.1 (e092d0b6b 2022-07-16)" ></div>
</body></html>