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::seq - 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 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_<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="#">Iterator<wbr>Random</a></h2><h3><a href="#provided-methods">Provided Methods</a></h3><ul class="block"><li><a href="#method.choose" title="choose">choose</a></li><li><a href="#method.choose_multiple" title="choose_multiple">choose_multiple</a></li><li><a href="#method.choose_multiple_fill" title="choose_multiple_fill">choose_multiple_fill</a></li><li><a href="#method.choose_stable" title="choose_stable">choose_stable</a></li></ul><h3><a href="#dyn-compatibility">Dyn Compatibility</a></h3><h3><a href="#implementors">Implementors</a></h3></section><div id="rustdoc-modnav"><h2><a href="index.html">In bdk_<wbr>chain::<wbr>bitcoin::<wbr>secp256k1::<wbr>rand::<wbr>seq</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>::<wbr><a href="index.html">seq</a></span><h1>Trait <span class="trait">IteratorRandom</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/seq/mod.rs.html#288">Source</a> </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 π!</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
28 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>
29 <p>Returns <code>None</code> if and only if the iterator is empty.</p>
30 <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
31 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
32 this method can offer <code>O(1)</code> performance. Where no size hint is
33 available, complexity is <code>O(n)</code> where <code>n</code> is the iterator length.
34 Partial hints (where <code>lower > 0</code>) also improve performance.</p>
35 <p>Note that the output values and the number of RNG samples used
36 depends on size hints. In particular, <code>Iterator</code> combinators that donβt
37 change the values yielded but change the size hints may result in
38 <code>choose</code> returning different elements. If you want consistent results
39 and RNG usage consider using <a href="trait.IteratorRandom.html#method.choose_stable" title="method bdk_chain::bitcoin::secp256k1::rand::seq::IteratorRandom::choose_stable"><code>IteratorRandom::choose_stable</code></a>.</p>
40 </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
41 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>
42 <p>Returns <code>None</code> if and only if the iterator is empty.</p>
43 <p>This method is very similar to <a href="trait.IteratorRandom.html#method.choose" title="method bdk_chain::bitcoin::secp256k1::rand::seq::IteratorRandom::choose"><code>choose</code></a> except that the result
44 only depends on the length of the iterator and the values produced by
45 <code>rng</code>. Notably for any iterator of a given length this will make the
46 same requests to <code>rng</code> and if the same sequence of values are produced
47 the same index will be selected from <code>self</code>. This may be useful if you
48 need consistent results no matter what type of iterator you are working
49 with. If you do not need this stability prefer <a href="trait.IteratorRandom.html#method.choose" title="method bdk_chain::bitcoin::secp256k1::rand::seq::IteratorRandom::choose"><code>choose</code></a>.</p>
50 <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
51 constructing elements where possible, however the selection and <code>rng</code>
52 calls are the same in the face of this optimization. If you want to
53 force every element to be created regardless call <code>.inspect(|e| ())</code>.</p>
54 </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
55 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
56 until that buffer is filled.</p>
57 <p>Although the elements are selected randomly, the order of elements in
58 the buffer is neither stable nor fully random. If random ordering is
59 desired, shuffle the result.</p>
60 <p>Returns the number of elements added to the buffer. This equals the length
61 of the buffer unless the iterator contains insufficient elements, in which
62 case this equals the number of elements available.</p>
63 <p>Complexity is <code>O(n)</code> where <code>n</code> is the length of the iterator.
64 For slices, prefer <a href="trait.SliceRandom.html#tymethod.choose_multiple" title="method bdk_chain::bitcoin::secp256k1::rand::seq::SliceRandom::choose_multiple"><code>SliceRandom::choose_multiple</code></a>.</p>
65 </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
66 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>
67 <p>This is equivalent to <code>choose_multiple_fill</code> except for the result type.</p>
68 <p>Although the elements are selected randomly, the order of elements in
69 the buffer is neither stable nor fully random. If random ordering is
70 desired, shuffle the result.</p>
71 <p>The length of the returned vector equals <code>amount</code> unless the iterator
72 contains insufficient elements, in which case it equals the number of
73 elements available.</p>
74 <p>Complexity is <code>O(n)</code> where <code>n</code> is the length of the iterator.
75 For slices, prefer <a href="trait.SliceRandom.html#tymethod.choose_multiple" title="method bdk_chain::bitcoin::secp256k1::rand::seq::SliceRandom::choose_multiple"><code>SliceRandom::choose_multiple</code></a>.</p>
76 </div></details></div><h2 id="dyn-compatibility" class="section-header">Dyn Compatibility<a href="#dyn-compatibility" class="anchor">Β§</a></h2><div class="dyn-compatibility-info"><p>This trait is <b>not</b> <a href="https://doc.rust-lang.org/nightly/reference/items/traits.html#object-safety">dyn compatible</a>.</p><p><i>In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.</i></p></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="trait.IteratorRandom.html" title="trait bdk_chain::bitcoin::secp256k1::rand::seq::IteratorRandom">IteratorRandom</a> for I<div class="where">where
77 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