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="Extension trait on iterators, providing random sampling methods."><title>IteratorRandom in bdk_chain::bitcoin::secp256k1::rand::prelude - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.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-76eba96aa4d2e634.css"><link rel="stylesheet" href="../../../../../static.files/rustdoc-dd39b87e5fcfba68.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.80.0-nightly (78a775127 2024-05-11)" data-channel="nightly" data-search-js="search-d52510db62a78183.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../../../../../static.files/storage-118b08c4c78b968e.js"></script><script defer src="sidebar-items.js"></script><script defer src="../../../../../static.files/main-20a3ad099b048cf2.js"></script><noscript><link rel="stylesheet" href="../../../../../static.files/noscript-df360f571f6edeae.css"></noscript><link rel="alternate icon" type="image/png" href="../../../../../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../../../../../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc trait"><!--[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_chain</a><span class="version">0.18.0</span></h2></div><h2 class="location"><a href="#">IteratorRandom</a></h2><div class="sidebar-elems"><section><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.choose">choose</a></li><li><a href="#method.choose_multiple">choose_multiple</a></li><li><a href="#method.choose_multiple_fill">choose_multiple_fill</a></li><li><a href="#method.choose_stable">choose_stable</a></li></ul><h3><a href="#object-safety">Object Safety</a></h3><h3><a href="#implementors">Implementors</a></h3></section><h2><a href="index.html">In bdk_chain::bitcoin::secp256k1::rand::prelude</a></h2></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"><h1>Trait <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>::<wbr><a href="index.html">prelude</a>::<wbr><a class="trait" href="#">IteratorRandom</a><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><span class="out-of-band"><a class="src" href="https://rust-random.github.io/rand/src/rand/seq/mod.rs.html#288">source</a> Β· <button id="toggle-all-docs" title="collapse all docs">[<span>−</span>]</button></span></div><pre class="rust item-decl"><code>pub trait IteratorRandom: <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/iter/traits/iterator/trait.Iterator.html" title="trait core::iter::traits::iterator::Iterator">Iterator</a> {
3 fn <a href="#method.choose" class="fn">choose</a><R>(self, rng: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut R</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::traits::iterator::Iterator::Item">Item</a>>
4 <span class="where">where R: <a class="trait" href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng">Rng</a> + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
5 <span class="item-spacer"></span> fn <a href="#method.choose_stable" class="fn">choose_stable</a><R>(self, rng: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut R</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::traits::iterator::Iterator::Item">Item</a>>
6 <span class="where">where R: <a class="trait" href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng">Rng</a> + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
7 <span class="item-spacer"></span> fn <a href="#method.choose_multiple_fill" class="fn">choose_multiple_fill</a><R>(
9 rng: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut R</a>,
10 buf: &mut [Self::<a class="associatedtype" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::traits::iterator::Iterator::Item">Item</a>]
11 ) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>
12 <span class="where">where R: <a class="trait" href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng">Rng</a> + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
13 <span class="item-spacer"></span> fn <a href="#method.choose_multiple" class="fn">choose_multiple</a><R>(self, rng: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut R</a>, amount: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>) -> <a class="struct" href="../../../base58/struct.Vec.html" title="struct bdk_chain::bitcoin::base58::Vec">Vec</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::traits::iterator::Iterator::Item">Item</a>>
14 <span class="where">where R: <a class="trait" href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng">Rng</a> + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a></span> { ... }
15 }</code></pre><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Extension trait on iterators, providing random sampling methods.</p>
16 <p>This trait is implemented on all iterators <code>I</code> where <code>I: Iterator + Sized</code>
17 and provides methods for
18 choosing one or more elements. You must <code>use</code> this trait:</p>
20 <div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>rand::seq::IteratorRandom;
22 <span class="kw">let </span><span class="kw-2">mut </span>rng = rand::thread_rng();
24 <span class="kw">let </span>faces = <span class="string">"πππππ π’"</span>;
25 <span class="macro">println!</span>(<span class="string">"I am {}!"</span>, faces.chars().choose(<span class="kw-2">&mut </span>rng).unwrap());</code></pre></div>
26 <p>Example output (non-deterministic):</p>
27 <div class="example-wrap"><pre class="language-none"><code>I am π!
28 </code></pre></div></div></details><h2 id="provided-methods" class="section-header">Provided Methods<a href="#provided-methods" class="anchor">Β§</a></h2><div class="methods"><details class="toggle method-toggle" open><summary><section id="method.choose" class="method"><a class="src rightside" href="https://rust-random.github.io/rand/src/rand/seq/mod.rs.html#304-305">source</a><h4 class="code-header">fn <a href="#method.choose" class="fn">choose</a><R>(self, rng: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut R</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::traits::iterator::Iterator::Item">Item</a>><div class="where">where
29 R: <a class="trait" href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng">Rng</a> + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Choose one element at random from the iterator.</p>
30 <p>Returns <code>None</code> if and only if the iterator is empty.</p>
31 <p>This method uses <a href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#method.size_hint" title="method core::iter::traits::iterator::Iterator::size_hint"><code>Iterator::size_hint</code></a> for optimisation. With an
32 accurate hint and where <a href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#method.nth" title="method core::iter::traits::iterator::Iterator::nth"><code>Iterator::nth</code></a> is a constant-time operation
33 this method can offer <code>O(1)</code> performance. Where no size hint is
34 available, complexity is <code>O(n)</code> where <code>n</code> is the iterator length.
35 Partial hints (where <code>lower > 0</code>) also improve performance.</p>
36 <p>Note that the output values and the number of RNG samples used
37 depends on size hints. In particular, <code>Iterator</code> combinators that donβt
38 change the values yielded but change the size hints may result in
39 <code>choose</code> returning different elements. If you want consistent results
40 and RNG usage consider using <a href="../seq/trait.IteratorRandom.html#method.choose_stable" title="method bdk_chain::bitcoin::secp256k1::rand::seq::IteratorRandom::choose_stable"><code>IteratorRandom::choose_stable</code></a>.</p>
41 </div></details><details class="toggle method-toggle" open><summary><section id="method.choose_stable" class="method"><a class="src rightside" href="https://rust-random.github.io/rand/src/rand/seq/mod.rs.html#373-374">source</a><h4 class="code-header">fn <a href="#method.choose_stable" class="fn">choose_stable</a><R>(self, rng: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut R</a>) -> <a class="enum" href="https://doc.rust-lang.org/nightly/core/option/enum.Option.html" title="enum core::option::Option">Option</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::traits::iterator::Iterator::Item">Item</a>><div class="where">where
42 R: <a class="trait" href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng">Rng</a> + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Choose one element at random from the iterator.</p>
43 <p>Returns <code>None</code> if and only if the iterator is empty.</p>
44 <p>This method is very similar to <a href="../seq/trait.IteratorRandom.html#method.choose" title="method bdk_chain::bitcoin::secp256k1::rand::seq::IteratorRandom::choose"><code>choose</code></a> except that the result
45 only depends on the length of the iterator and the values produced by
46 <code>rng</code>. Notably for any iterator of a given length this will make the
47 same requests to <code>rng</code> and if the same sequence of values are produced
48 the same index will be selected from <code>self</code>. This may be useful if you
49 need consistent results no matter what type of iterator you are working
50 with. If you do not need this stability prefer <a href="../seq/trait.IteratorRandom.html#method.choose" title="method bdk_chain::bitcoin::secp256k1::rand::seq::IteratorRandom::choose"><code>choose</code></a>.</p>
51 <p>Note that this method still uses <a href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#method.size_hint" title="method core::iter::traits::iterator::Iterator::size_hint"><code>Iterator::size_hint</code></a> to skip
52 constructing elements where possible, however the selection and <code>rng</code>
53 calls are the same in the face of this optimization. If you want to
54 force every element to be created regardless call <code>.inspect(|e| ())</code>.</p>
55 </div></details><details class="toggle method-toggle" open><summary><section id="method.choose_multiple_fill" class="method"><a class="src rightside" href="https://rust-random.github.io/rand/src/rand/seq/mod.rs.html#426-427">source</a><h4 class="code-header">fn <a href="#method.choose_multiple_fill" class="fn">choose_multiple_fill</a><R>(self, rng: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut R</a>, buf: &mut [Self::<a class="associatedtype" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::traits::iterator::Iterator::Item">Item</a>]) -> <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a><div class="where">where
56 R: <a class="trait" href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng">Rng</a> + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Collects values at random from the iterator into a supplied buffer
57 until that buffer is filled.</p>
58 <p>Although the elements are selected randomly, the order of elements in
59 the buffer is neither stable nor fully random. If random ordering is
60 desired, shuffle the result.</p>
61 <p>Returns the number of elements added to the buffer. This equals the length
62 of the buffer unless the iterator contains insufficient elements, in which
63 case this equals the number of elements available.</p>
64 <p>Complexity is <code>O(n)</code> where <code>n</code> is the length of the iterator.
65 For slices, prefer <a href="../seq/trait.SliceRandom.html#tymethod.choose_multiple" title="method bdk_chain::bitcoin::secp256k1::rand::seq::SliceRandom::choose_multiple"><code>SliceRandom::choose_multiple</code></a>.</p>
66 </div></details><details class="toggle method-toggle" open><summary><section id="method.choose_multiple" class="method"><a class="src rightside" href="https://rust-random.github.io/rand/src/rand/seq/mod.rs.html#466-467">source</a><h4 class="code-header">fn <a href="#method.choose_multiple" class="fn">choose_multiple</a><R>(self, rng: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.reference.html">&mut R</a>, amount: <a class="primitive" href="https://doc.rust-lang.org/nightly/std/primitive.usize.html">usize</a>) -> <a class="struct" href="../../../base58/struct.Vec.html" title="struct bdk_chain::bitcoin::base58::Vec">Vec</a><Self::<a class="associatedtype" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html#associatedtype.Item" title="type core::iter::traits::iterator::Iterator::Item">Item</a>><div class="where">where
67 R: <a class="trait" href="../trait.Rng.html" title="trait bdk_chain::bitcoin::secp256k1::rand::Rng">Rng</a> + ?<a class="trait" href="https://doc.rust-lang.org/nightly/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h4></section></summary><div class="docblock"><p>Collects <code>amount</code> values at random from the iterator into a vector.</p>
68 <p>This is equivalent to <code>choose_multiple_fill</code> except for the result type.</p>
69 <p>Although the elements are selected randomly, the order of elements in
70 the buffer is neither stable nor fully random. If random ordering is
71 desired, shuffle the result.</p>
72 <p>The length of the returned vector equals <code>amount</code> unless the iterator
73 contains insufficient elements, in which case it equals the number of
74 elements available.</p>
75 <p>Complexity is <code>O(n)</code> where <code>n</code> is the length of the iterator.
76 For slices, prefer <a href="../seq/trait.SliceRandom.html#tymethod.choose_multiple" title="method bdk_chain::bitcoin::secp256k1::rand::seq::SliceRandom::choose_multiple"><code>SliceRandom::choose_multiple</code></a>.</p>
77 </div></details></div><h2 id="object-safety" class="section-header">Object Safety<a href="#object-safety" class="anchor">Β§</a></h2><div class="object-safety-info">This trait is <b>not</b> <a href="https://doc.rust-lang.org/nightly/reference/items/traits.html#object-safety">object safe</a>.</div><h2 id="implementors" class="section-header">Implementors<a href="#implementors" class="anchor">Β§</a></h2><div id="implementors-list"><section id="impl-IteratorRandom-for-I" class="impl"><a class="src rightside" href="https://rust-random.github.io/rand/src/rand/seq/mod.rs.html#615">source</a><a href="#impl-IteratorRandom-for-I" class="anchor">Β§</a><h3 class="code-header">impl<I> <a class="trait" href="../seq/trait.IteratorRandom.html" title="trait bdk_chain::bitcoin::secp256k1::rand::seq::IteratorRandom">IteratorRandom</a> for I<div class="where">where
78 I: <a class="trait" href="https://doc.rust-lang.org/nightly/core/iter/traits/iterator/trait.Iterator.html" title="trait core::iter::traits::iterator::Iterator">Iterator</a>,</div></h3></section></div><script src="../../../../../trait.impl/rand/seq/trait.IteratorRandom.js" async></script></section></div></main></body></html>
projects / bitcoindevkit.org / blob