55 lines
14 KiB
HTML
55 lines
14 KiB
HTML
<!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="Generating random samples from probability distributions"><title>rand::distr - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Italic-81dc35de.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-MediumItalic-ccf7e434.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2"href="../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../static.files/rustdoc-ca0dd0c4.css"><meta name="rustdoc-vars" data-root-path="../../" data-static-root-path="../../static.files/" data-current-crate="rand" data-themes="" data-resource-suffix="" data-rustdoc-version="1.93.1 (01f6ddf75 2026-02-11) (Arch Linux rust 1:1.93.1-1)" data-channel="1.93.1" data-search-js="search-9e2438ea.js" data-stringdex-js="stringdex-a3946164.js" data-settings-js="settings-c38705f0.js" ><script src="../../static.files/storage-e2aeef58.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../static.files/main-a410ff4d.js"></script><noscript><link rel="stylesheet" href="../../static.files/noscript-263c88ec.css"></noscript><link rel="icon" href="https://www.rust-lang.org/favicon.ico"></head><body class="rustdoc mod"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><rustdoc-topbar><h2><a href="#">Module distr</a></h2></rustdoc-topbar><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="../../rand/index.html"><img src="https://www.rust-lang.org/logos/rust-logo-128x128-blk.png" alt="logo"></a><h2><a href="../../rand/index.html">rand</a><span class="version">0.9.2</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module distr</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#the-standard-uniform-distribution" title="The Standard Uniform distribution">The Standard Uniform distribution</a><ul><li><a href="#other-standard-uniform-distributions" title="Other standard uniform distributions">Other standard uniform distributions</a></li></ul></li><li><a href="#parameterized-uniform-distributions" title="Parameterized Uniform distributions">Parameterized Uniform distributions</a></li><li><a href="#non-uniform-sampling" title="Non-uniform sampling">Non-uniform sampling</a></li></ul><h3><a href="#modules">Module Items</a></h3><ul class="block"><li><a href="#modules" title="Modules">Modules</a></li><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#enums" title="Enums">Enums</a></li><li><a href="#traits" title="Traits">Traits</a></li></ul></section><div id="rustdoc-modnav"><h2 class="in-crate"><a href="../index.html">In crate rand</a></h2></div></div></nav><div class="sidebar-resizer" title="Drag to resize sidebar"></div><main><div class="width-limiter"><section id="main-content" class="content"><div class="main-heading"><div class="rustdoc-breadcrumbs"><a href="../index.html">rand</a></div><h1>Module <span>distr</span> <button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../../src/rand/distr/mod.rs.html#10-214">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Generating random samples from probability distributions</p>
|
||
<p>This module is the home of the <a href="trait.Distribution.html" title="trait rand::distr::Distribution"><code>Distribution</code></a> trait and several of its
|
||
implementations. It is the workhorse behind some of the convenient
|
||
functionality of the <a href="../trait.Rng.html" title="trait rand::Rng"><code>Rng</code></a> trait, e.g. <a href="../trait.Rng.html#method.random" title="method rand::Rng::random"><code>Rng::random</code></a> and of course
|
||
<a href="../trait.Rng.html#method.sample" title="method rand::Rng::sample"><code>Rng::sample</code></a>.</p>
|
||
<p>Abstractly, a <a href="https://en.wikipedia.org/wiki/Probability_distribution">probability distribution</a> describes the probability of
|
||
occurrence of each value in its sample space.</p>
|
||
<p>More concretely, an implementation of <code>Distribution<T></code> for type <code>X</code> is an
|
||
algorithm for choosing values from the sample space (a subset of <code>T</code>)
|
||
according to the distribution <code>X</code> represents, using an external source of
|
||
randomness (an RNG supplied to the <code>sample</code> function).</p>
|
||
<p>A type <code>X</code> may implement <code>Distribution<T></code> for multiple types <code>T</code>.
|
||
Any type implementing <a href="trait.Distribution.html" title="trait rand::distr::Distribution"><code>Distribution</code></a> is stateless (i.e. immutable),
|
||
but it may have internal parameters set at construction time (for example,
|
||
<a href="struct.Uniform.html" title="struct rand::distr::Uniform"><code>Uniform</code></a> allows specification of its sample space as a range within <code>T</code>).</p>
|
||
<h2 id="the-standard-uniform-distribution"><a class="doc-anchor" href="#the-standard-uniform-distribution">§</a>The Standard Uniform distribution</h2>
|
||
<p>The <a href="struct.StandardUniform.html" title="struct rand::distr::StandardUniform"><code>StandardUniform</code></a> distribution is important to mention. This is the
|
||
distribution used by <a href="../trait.Rng.html#method.random" title="method rand::Rng::random"><code>Rng::random</code></a> and represents the “default” way to
|
||
produce a random value for many different types, including most primitive
|
||
types, tuples, arrays, and a few derived types. See the documentation of
|
||
<a href="struct.StandardUniform.html" title="struct rand::distr::StandardUniform"><code>StandardUniform</code></a> for more details.</p>
|
||
<p>Implementing <a href="trait.Distribution.html" title="trait rand::distr::Distribution"><code>Distribution<T></code></a> for <a href="struct.StandardUniform.html" title="struct rand::distr::StandardUniform"><code>StandardUniform</code></a> for user types <code>T</code> makes it
|
||
possible to generate type <code>T</code> with <a href="../trait.Rng.html#method.random" title="method rand::Rng::random"><code>Rng::random</code></a>, and by extension also
|
||
with the <a href="../fn.random.html" title="fn rand::random"><code>random</code></a> function.</p>
|
||
<h3 id="other-standard-uniform-distributions"><a class="doc-anchor" href="#other-standard-uniform-distributions">§</a>Other standard uniform distributions</h3>
|
||
<p><a href="struct.Alphanumeric.html" title="struct rand::distr::Alphanumeric"><code>Alphanumeric</code></a> is a simple distribution to sample random letters and
|
||
numbers of the <code>char</code> type; in contrast <a href="struct.StandardUniform.html" title="struct rand::distr::StandardUniform"><code>StandardUniform</code></a> may sample any valid
|
||
<code>char</code>.</p>
|
||
<p>There’s also an <a href="struct.Alphabetic.html" title="struct rand::distr::Alphabetic"><code>Alphabetic</code></a> distribution which acts similarly to <a href="struct.Alphanumeric.html" title="struct rand::distr::Alphanumeric"><code>Alphanumeric</code></a> but
|
||
doesn’t include digits.</p>
|
||
<p>For floats (<code>f32</code>, <code>f64</code>), <a href="struct.StandardUniform.html" title="struct rand::distr::StandardUniform"><code>StandardUniform</code></a> samples from <code>[0, 1)</code>. Also
|
||
provided are <a href="struct.Open01.html" title="struct rand::distr::Open01"><code>Open01</code></a> (samples from <code>(0, 1)</code>) and <a href="struct.OpenClosed01.html" title="struct rand::distr::OpenClosed01"><code>OpenClosed01</code></a>
|
||
(samples from <code>(0, 1]</code>). No option is provided to sample from <code>[0, 1]</code>; it
|
||
is suggested to use one of the above half-open ranges since the failure to
|
||
sample a value which would have a low chance of being sampled anyway is
|
||
rarely an issue in practice.</p>
|
||
<h2 id="parameterized-uniform-distributions"><a class="doc-anchor" href="#parameterized-uniform-distributions">§</a>Parameterized Uniform distributions</h2>
|
||
<p>The <a href="struct.Uniform.html" title="struct rand::distr::Uniform"><code>Uniform</code></a> distribution provides uniform sampling over a specified
|
||
range on a subset of the types supported by the above distributions.</p>
|
||
<p>Implementations support single-value-sampling via
|
||
<a href="../trait.Rng.html#method.random_range" title="method rand::Rng::random_range"><code>Rng::random_range(Range)</code></a>.
|
||
Where a fixed (non-<code>const</code>) range will be sampled many times, it is likely
|
||
faster to pre-construct a <a href="trait.Distribution.html" title="trait rand::distr::Distribution"><code>Distribution</code></a> object using
|
||
<a href="struct.Uniform.html#method.new" title="associated function rand::distr::Uniform::new"><code>Uniform::new</code></a>, <a href="struct.Uniform.html#method.new_inclusive" title="associated function rand::distr::Uniform::new_inclusive"><code>Uniform::new_inclusive</code></a> or <code>From<Range></code>.</p>
|
||
<h2 id="non-uniform-sampling"><a class="doc-anchor" href="#non-uniform-sampling">§</a>Non-uniform sampling</h2>
|
||
<p>Sampling a simple true/false outcome with a given probability has a name:
|
||
the <a href="struct.Bernoulli.html" title="struct rand::distr::Bernoulli"><code>Bernoulli</code></a> distribution (this is used by <a href="../trait.Rng.html#method.random_bool" title="method rand::Rng::random_bool"><code>Rng::random_bool</code></a>).</p>
|
||
<p>For weighted sampling of discrete values see the <a href="weighted/index.html" title="mod rand::distr::weighted"><code>weighted</code></a> module.</p>
|
||
<p>This crate no longer includes other non-uniform distributions; instead
|
||
it is recommended that you use either <a href="https://crates.io/crates/rand_distr"><code>rand_distr</code></a> or <a href="https://crates.io/crates/statrs"><code>statrs</code></a>.</p>
|
||
</div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><dl class="item-table"><dt><a class="mod" href="slice/index.html" title="mod rand::distr::slice">slice</a></dt><dd>Distributions over slices</dd><dt><a class="mod" href="uniform/index.html" title="mod rand::distr::uniform">uniform</a></dt><dd>A distribution uniformly sampling numbers within a given range.</dd><dt><a class="mod" href="weighted/index.html" title="mod rand::distr::weighted">weighted</a></dt><dd>Weighted (index) sampling</dd></dl><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><dl class="item-table"><dt><a class="struct" href="struct.Alphabetic.html" title="struct rand::distr::Alphabetic">Alphabetic</a></dt><dd>Sample a <a href="https://doc.rust-lang.org/1.93.1/std/primitive.u8.html" title="primitive u8"><code>u8</code></a>, uniformly distributed over letters:
|
||
a-z and A-Z.</dd><dt><a class="struct" href="struct.Alphanumeric.html" title="struct rand::distr::Alphanumeric">Alphanumeric</a></dt><dd>Sample a <code>u8</code>, uniformly distributed over ASCII letters and numbers:
|
||
a-z, A-Z and 0-9.</dd><dt><a class="struct" href="struct.Bernoulli.html" title="struct rand::distr::Bernoulli">Bernoulli</a></dt><dd>The <a href="https://en.wikipedia.org/wiki/Bernoulli_distribution">Bernoulli distribution</a> <code>Bernoulli(p)</code>.</dd><dt><a class="struct" href="struct.Iter.html" title="struct rand::distr::Iter">Iter</a></dt><dd>An iterator over a <a href="trait.Distribution.html" title="trait rand::distr::Distribution"><code>Distribution</code></a></dd><dt><a class="struct" href="struct.Map.html" title="struct rand::distr::Map">Map</a></dt><dd>A <a href="trait.Distribution.html" title="trait rand::distr::Distribution"><code>Distribution</code></a> which maps sampled values to type <code>S</code></dd><dt><a class="struct" href="struct.Open01.html" title="struct rand::distr::Open01">Open01</a></dt><dd>A distribution to sample floating point numbers uniformly in the open
|
||
interval <code>(0, 1)</code>, i.e. not including either endpoint.</dd><dt><a class="struct" href="struct.OpenClosed01.html" title="struct rand::distr::OpenClosed01">Open<wbr>Closed01</a></dt><dd>A distribution to sample floating point numbers uniformly in the half-open
|
||
interval <code>(0, 1]</code>, i.e. including 1 but not 0.</dd><dt><a class="struct" href="struct.StandardUniform.html" title="struct rand::distr::StandardUniform">Standard<wbr>Uniform</a></dt><dd>The Standard Uniform distribution</dd><dt><a class="struct" href="struct.Uniform.html" title="struct rand::distr::Uniform">Uniform</a></dt><dd>Sample values uniformly between two bounds.</dd></dl><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><dl class="item-table"><dt><a class="enum" href="enum.BernoulliError.html" title="enum rand::distr::BernoulliError">Bernoulli<wbr>Error</a></dt><dd>Error type returned from <a href="struct.Bernoulli.html#method.new" title="associated function rand::distr::Bernoulli::new"><code>Bernoulli::new</code></a>.</dd></dl><h2 id="traits" class="section-header">Traits<a href="#traits" class="anchor">§</a></h2><dl class="item-table"><dt><a class="trait" href="trait.Distribution.html" title="trait rand::distr::Distribution">Distribution</a></dt><dd>Types (distributions) that can be used to create a random instance of <code>T</code>.</dd><dt><a class="trait" href="trait.SampleString.html" title="trait rand::distr::SampleString">Sample<wbr>String</a></dt><dd>Sample or extend a <a href="https://doc.rust-lang.org/1.93.1/alloc/string/struct.String.html" title="struct alloc::string::String"><code>String</code></a></dd></dl></section></div></main></body></html> |