1 <!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>bdk_chain::bitcoin::secp256k1::rand::distributions - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Regular-0fe48ade.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" crossorigin href="../../../../../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../../../../../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../../../../../static.files/rustdoc-46132b98.css"><meta name="rustdoc-vars" data-root-path="../../../../../" data-static-root-path="../../../../../static.files/" data-current-crate="bdk_chain" data-themes="" data-resource-suffix="" data-rustdoc-version="1.85.0-nightly (a4cb3c831 2024-12-17)" data-channel="nightly" data-search-js="search-036cda7a.js" data-settings-js="settings-0f613d39.js" ><script src="../../../../../static.files/storage-59e33391.js"></script><script defer src="../sidebar-items.js"></script><script defer src="../../../../../static.files/main-5f194d8c.js"></script><noscript><link rel="stylesheet" href="../../../../../static.files/noscript-893ab5e7.css"></noscript><link rel="alternate icon" type="image/png" href="../../../../../static.files/favicon-32x32-6580c154.png"><link rel="icon" type="image/svg+xml" href="../../../../../static.files/favicon-044be391.svg"></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]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button><a class="logo-container" href="../../../../../bdk_chain/index.html"><img src="https://github.com/bitcoindevkit/bdk/raw/master/static/bdk.png" alt=""></a></nav><nav class="sidebar"><div class="sidebar-crate"><a class="logo-container" href="../../../../../bdk_chain/index.html"><img src="https://github.com/bitcoindevkit/bdk/raw/master/static/bdk.png" alt="logo"></a><h2><a href="../../../../../bdk_chain/index.html">bdk_<wbr>chain</a><span class="version">0.21.0</span></h2></div><div class="sidebar-elems"><section id="rustdoc-toc"><h2 class="location"><a href="#">Module distributions</a></h2><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#the-standard-distribution" title="The `Standard` distribution">The <code>Standard</code> distribution</a><ul><li><a href="#random-characters" title="Random characters">Random characters</a></li></ul></li><li><a href="#uniform-numeric-ranges" title="Uniform numeric ranges">Uniform numeric ranges</a><ul><li><a href="#open-and-half-open-ranges" title="Open and half-open ranges">Open and half-open ranges</a></li></ul></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><a href="../index.html">In bdk_<wbr>chain::<wbr>bitcoin::<wbr>secp256k1::<wbr>rand</a></h2></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><span class="rustdoc-breadcrumbs"><a href="../../../../index.html">bdk_chain</a>::<wbr><a href="../../../index.html">bitcoin</a>::<wbr><a href="../../index.html">secp256k1</a>::<wbr><a href="../index.html">rand</a></span><h1>Module <span>distributions</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="https://rust-random.github.io/rand/src/rand/lib.rs.html#97">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>
2 <p>This module is the home of the <a href="../prelude/trait.Distribution.html" title="trait bdk_chain::bitcoin::secp256k1::rand::prelude::Distribution"><code>Distribution</code></a> trait and several of its
3 implementations. It is the workhorse behind some of the convenient
4 functionality of the <a href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng"><code>Rng</code></a> trait, e.g. <a href="../trait.Rng.html#method.gen" title="method bdk_chain::bitcoin::secp256k1::rand::Rng::gen"><code>Rng::gen</code></a> and of course
5 <a href="../trait.Rng.html#method.sample" title="method bdk_chain::bitcoin::secp256k1::rand::Rng::sample"><code>Rng::sample</code></a>.</p>
6 <p>Abstractly, a <a href="https://en.wikipedia.org/wiki/Probability_distribution">probability distribution</a> describes the probability of
7 occurrence of each value in its sample space.</p>
8 <p>More concretely, an implementation of <code>Distribution<T></code> for type <code>X</code> is an
9 algorithm for choosing values from the sample space (a subset of <code>T</code>)
10 according to the distribution <code>X</code> represents, using an external source of
11 randomness (an RNG supplied to the <code>sample</code> function).</p>
12 <p>A type <code>X</code> may implement <code>Distribution<T></code> for multiple types <code>T</code>.
13 Any type implementing <a href="../prelude/trait.Distribution.html" title="trait bdk_chain::bitcoin::secp256k1::rand::prelude::Distribution"><code>Distribution</code></a> is stateless (i.e. immutable),
14 but it may have internal parameters set at construction time (for example,
15 <a href="struct.Uniform.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Uniform"><code>Uniform</code></a> allows specification of its sample space as a range within <code>T</code>).</p>
16 <h2 id="the-standard-distribution"><a class="doc-anchor" href="#the-standard-distribution">§</a>The <code>Standard</code> distribution</h2>
17 <p>The <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a> distribution is important to mention. This is the
18 distribution used by <a href="../trait.Rng.html#method.gen" title="method bdk_chain::bitcoin::secp256k1::rand::Rng::gen"><code>Rng::gen</code></a> and represents the “default” way to
19 produce a random value for many different types, including most primitive
20 types, tuples, arrays, and a few derived types. See the documentation of
21 <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a> for more details.</p>
22 <p>Implementing <code>Distribution<T></code> for <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a> for user types <code>T</code> makes it
23 possible to generate type <code>T</code> with <a href="../trait.Rng.html#method.gen" title="method bdk_chain::bitcoin::secp256k1::rand::Rng::gen"><code>Rng::gen</code></a>, and by extension also
24 with the <a href="../fn.random.html" title="fn bdk_chain::bitcoin::secp256k1::rand::random"><code>random</code></a> function.</p>
25 <h3 id="random-characters"><a class="doc-anchor" href="#random-characters">§</a>Random characters</h3>
26 <p><a href="struct.Alphanumeric.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Alphanumeric"><code>Alphanumeric</code></a> is a simple distribution to sample random letters and
27 numbers of the <code>char</code> type; in contrast <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a> may sample any valid
28 <code>char</code>.</p>
29 <h2 id="uniform-numeric-ranges"><a class="doc-anchor" href="#uniform-numeric-ranges">§</a>Uniform numeric ranges</h2>
30 <p>The <a href="struct.Uniform.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Uniform"><code>Uniform</code></a> distribution is more flexible than <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a>, but also
31 more specialised: it supports fewer target types, but allows the sample
32 space to be specified as an arbitrary range within its target type <code>T</code>.
33 Both <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a> and <a href="struct.Uniform.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Uniform"><code>Uniform</code></a> are in some sense uniform distributions.</p>
34 <p>Values may be sampled from this distribution using [<code>Rng::sample(Range)</code>] or
35 by creating a distribution object with <a href="struct.Uniform.html#method.new" title="associated function bdk_chain::bitcoin::secp256k1::rand::distributions::Uniform::new"><code>Uniform::new</code></a>,
36 <a href="struct.Uniform.html#method.new_inclusive" title="associated function bdk_chain::bitcoin::secp256k1::rand::distributions::Uniform::new_inclusive"><code>Uniform::new_inclusive</code></a> or <code>From<Range></code>. When the range limits are not
37 known at compile time it is typically faster to reuse an existing
38 <code>Uniform</code> object than to call [<code>Rng::sample(Range)</code>].</p>
39 <p>User types <code>T</code> may also implement <code>Distribution<T></code> for <a href="struct.Uniform.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Uniform"><code>Uniform</code></a>,
40 although this is less straightforward than for <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a> (see the
41 documentation in the <a href="uniform/index.html" title="mod bdk_chain::bitcoin::secp256k1::rand::distributions::uniform"><code>uniform</code></a> module). Doing so enables generation of
42 values of type <code>T</code> with [<code>Rng::sample(Range)</code>].</p>
43 <h3 id="open-and-half-open-ranges"><a class="doc-anchor" href="#open-and-half-open-ranges">§</a>Open and half-open ranges</h3>
44 <p>There are surprisingly many ways to uniformly generate random floats. A
45 range between 0 and 1 is standard, but the exact bounds (open vs closed)
46 and accuracy differ. In addition to the <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a> distribution Rand offers
47 <a href="struct.Open01.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Open01"><code>Open01</code></a> and <a href="struct.OpenClosed01.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::OpenClosed01"><code>OpenClosed01</code></a>. See “Floating point implementation” section of
48 <a href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard"><code>Standard</code></a> documentation for more details.</p>
49 <h2 id="non-uniform-sampling"><a class="doc-anchor" href="#non-uniform-sampling">§</a>Non-uniform sampling</h2>
50 <p>Sampling a simple true/false outcome with a given probability has a name:
51 the <a href="struct.Bernoulli.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Bernoulli"><code>Bernoulli</code></a> distribution (this is used by <a href="../trait.Rng.html#method.gen_bool" title="method bdk_chain::bitcoin::secp256k1::rand::Rng::gen_bool"><code>Rng::gen_bool</code></a>).</p>
52 <p>For weighted sampling from a sequence of discrete values, use the
53 <a href="struct.WeightedIndex.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::WeightedIndex"><code>WeightedIndex</code></a> distribution.</p>
54 <p>This crate no longer includes other non-uniform distributions; instead
55 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>
56 </div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="uniform/index.html" title="mod bdk_chain::bitcoin::secp256k1::rand::distributions::uniform">uniform</a></div><div class="desc docblock-short">A distribution uniformly sampling numbers within a given range.</div></li><li><div class="item-name"><a class="mod" href="weighted/index.html" title="mod bdk_chain::bitcoin::secp256k1::rand::distributions::weighted">weighted</a><wbr><span class="stab deprecated" title="">Deprecated</span></div><div class="desc docblock-short">Weighted index sampling</div></li></ul><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.Alphanumeric.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Alphanumeric">Alphanumeric</a></div><div class="desc docblock-short">Sample a <code>u8</code>, uniformly distributed over ASCII letters and numbers:
57 a-z, A-Z and 0-9.</div></li><li><div class="item-name"><a class="struct" href="struct.Bernoulli.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Bernoulli">Bernoulli</a></div><div class="desc docblock-short">The Bernoulli distribution.</div></li><li><div class="item-name"><a class="struct" href="struct.DistIter.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::DistIter">Dist<wbr>Iter</a></div><div class="desc docblock-short">An iterator that generates random values of <code>T</code> with distribution <code>D</code>,
58 using <code>R</code> as the source of randomness.</div></li><li><div class="item-name"><a class="struct" href="struct.DistMap.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::DistMap">DistMap</a></div><div class="desc docblock-short">A distribution of values of type <code>S</code> derived from the distribution <code>D</code>
59 by mapping its output of type <code>T</code> through the closure <code>F</code>.</div></li><li><div class="item-name"><a class="struct" href="struct.Open01.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Open01">Open01</a></div><div class="desc docblock-short">A distribution to sample floating point numbers uniformly in the open
60 interval <code>(0, 1)</code>, i.e. not including either endpoint.</div></li><li><div class="item-name"><a class="struct" href="struct.OpenClosed01.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::OpenClosed01">Open<wbr>Closed01</a></div><div class="desc docblock-short">A distribution to sample floating point numbers uniformly in the half-open
61 interval <code>(0, 1]</code>, i.e. including 1 but not 0.</div></li><li><div class="item-name"><a class="struct" href="struct.Slice.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Slice">Slice</a></div><div class="desc docblock-short">A distribution to sample items uniformly from a slice.</div></li><li><div class="item-name"><a class="struct" href="struct.Standard.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Standard">Standard</a></div><div class="desc docblock-short">A generic random value distribution, implemented for many primitive types.
62 Usually generates values with a numerically uniform distribution, and with a
63 range appropriate to the type.</div></li><li><div class="item-name"><a class="struct" href="struct.Uniform.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::Uniform">Uniform</a></div><div class="desc docblock-short">Sample values uniformly between two bounds.</div></li><li><div class="item-name"><a class="struct" href="struct.WeightedIndex.html" title="struct bdk_chain::bitcoin::secp256k1::rand::distributions::WeightedIndex">Weighted<wbr>Index</a></div><div class="desc docblock-short">A distribution using weighted sampling of discrete items</div></li></ul><h2 id="enums" class="section-header">Enums<a href="#enums" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.BernoulliError.html" title="enum bdk_chain::bitcoin::secp256k1::rand::distributions::BernoulliError">Bernoulli<wbr>Error</a></div><div class="desc docblock-short">Error type returned from <code>Bernoulli::new</code>.</div></li><li><div class="item-name"><a class="enum" href="enum.WeightedError.html" title="enum bdk_chain::bitcoin::secp256k1::rand::distributions::WeightedError">Weighted<wbr>Error</a></div><div class="desc docblock-short">Error type returned from <code>WeightedIndex::new</code>.</div></li></ul><h2 id="traits" class="section-header">Traits<a href="#traits" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="trait" href="trait.DistString.html" title="trait bdk_chain::bitcoin::secp256k1::rand::distributions::DistString">Dist<wbr>String</a></div><div class="desc docblock-short"><code>String</code> sampler</div></li><li><div class="item-name"><a class="trait" href="trait.Distribution.html" title="trait bdk_chain::bitcoin::secp256k1::rand::distributions::Distribution">Distribution</a></div><div class="desc docblock-short">Types (distributions) that can be used to create a random instance of <code>T</code>.</div></li></ul></section></div></main></body></html>
projects / bitcoindevkit.org / blob