edlang/itertools/index.html
2024-02-13 06:38:44 +00:00

56 lines
21 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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="Extra iterator adaptors, functions and macros."><title>itertools - Rust</title><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-ac92e1bbe349e143.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="itertools" data-themes="" data-resource-suffix="" data-rustdoc-version="1.76.0 (07dca489a 2024-02-04)" data-channel="1.76.0" data-search-js="search-2b6ce74ff89ae146.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-f2adc0d6ca4d09fb.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-305769736d49e732.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-feafe1bb7466e4bd.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><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 mod crate"><!--[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></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../itertools/index.html">itertools</a><span class="version">0.12.1</span></h2></div><div class="sidebar-elems"><ul class="block">
<li><a id="all-types" href="all.html">All Items</a></li></ul><section><ul class="block"><li><a href="#modules">Modules</a></li><li><a href="#macros">Macros</a></li><li><a href="#enums">Enums</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li></ul></section></div></nav><div class="sidebar-resizer"></div>
<main><div class="width-limiter"><nav class="sub"><form class="search-form"><span></span><div id="sidebar-button" tabindex="-1"><a href="../itertools/all.html" title="show sidebar"></a></div><input class="search-input" name="search" aria-label="Run search in the documentation" autocomplete="off" spellcheck="false" placeholder="Click or press S to search, ? for more options…" type="search"><div id="help-button" tabindex="-1"><a href="../help.html" title="help">?</a></div><div id="settings-menu" tabindex="-1"><a href="../settings.html" title="settings"><img width="22" height="22" alt="Change settings" src="../static.files/wheel-7b819b6101059cd0.svg"></a></div></form></nav><section id="main-content" class="content"><div class="main-heading"><h1>Crate <a class="mod" href="#">itertools</a><button id="copy-path" title="Copy item path to clipboard"><img src="../static.files/clipboard-7571035ce49a181d.svg" width="19" height="18" alt="Copy item path"></button></h1><span class="out-of-band"><a class="src" href="../src/itertools/lib.rs.html#1-4100">source</a> · <button id="toggle-all-docs" title="collapse all docs">[<span>&#x2212;</span>]</button></span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>Extra iterator adaptors, functions and macros.</p>
<p>To extend <a href="https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html" title="trait core::iter::traits::iterator::Iterator"><code>Iterator</code></a> with methods in this crate, import
the <a href="trait.Itertools.html" title="trait itertools::Itertools"><code>Itertools</code></a> trait:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>itertools::Itertools;</code></pre></div>
<p>Now, new methods like <a href="trait.Itertools.html#method.interleave" title="method itertools::Itertools::interleave"><code>interleave</code></a>
are available on all iterators:</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>itertools::Itertools;
<span class="kw">let </span>it = (<span class="number">1</span>..<span class="number">3</span>).interleave(<span class="macro">vec!</span>[-<span class="number">1</span>, -<span class="number">2</span>]);
itertools::assert_equal(it, <span class="macro">vec!</span>[<span class="number">1</span>, -<span class="number">1</span>, <span class="number">2</span>, -<span class="number">2</span>]);</code></pre></div>
<p>Most iterator methods are also provided as functions (with the benefit
that they convert parameters using <a href="https://doc.rust-lang.org/1.76.0/core/iter/traits/collect/trait.IntoIterator.html" title="trait core::iter::traits::collect::IntoIterator"><code>IntoIterator</code></a>):</p>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>itertools::interleave;
<span class="kw">for </span>elt <span class="kw">in </span>interleave(<span class="kw-2">&amp;</span>[<span class="number">1</span>, <span class="number">2</span>, <span class="number">3</span>], <span class="kw-2">&amp;</span>[<span class="number">2</span>, <span class="number">3</span>, <span class="number">4</span>]) {
<span class="comment">/* loop body */
</span>}</code></pre></div>
<h3 id="crate-features"><a href="#crate-features">Crate Features</a></h3>
<ul>
<li><code>use_std</code>
<ul>
<li>Enabled by default.</li>
<li>Disable to compile itertools using <code>#![no_std]</code>. This disables
any items that depend on collections (like <code>group_by</code>, <code>unique</code>,
<code>kmerge</code>, <code>join</code> and many more).</li>
</ul>
</li>
</ul>
<h3 id="rust-version"><a href="#rust-version">Rust Version</a></h3>
<p>This version of itertools requires Rust 1.43.1 or later.</p>
</div></details><h2 id="reexports" class="section-header"><a href="#reexports">Re-exports</a></h2><ul class="item-table"><li><div class="item-name"><code>pub use crate::<a class="mod" href="structs/index.html" title="mod itertools::structs">structs</a>::*;</code></div></li></ul><h2 id="modules" class="section-header"><a href="#modules">Modules</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="structs/index.html" title="mod itertools::structs">structs</a></div><div class="desc docblock-short">The concrete iterator types.</div></li><li><div class="item-name"><a class="mod" href="traits/index.html" title="mod itertools::traits">traits</a></div><div class="desc docblock-short">Traits helpful for using certain <code>Itertools</code> methods in generic contexts.</div></li></ul><h2 id="macros" class="section-header"><a href="#macros">Macros</a></h2><ul class="item-table"><li><div class="item-name"><a class="macro" href="macro.chain.html" title="macro itertools::chain">chain</a></div><div class="desc docblock-short"><a href="https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html#method.chain" title="method core::iter::traits::iterator::Iterator::chain">Chain</a> zero or more iterators together into one sequence.</div></li><li><div class="item-name"><a class="macro" href="macro.iproduct.html" title="macro itertools::iproduct">iproduct</a></div><div class="desc docblock-short">Create an iterator over the “cartesian product” of iterators.</div></li><li><div class="item-name"><a class="macro" href="macro.izip.html" title="macro itertools::izip">izip</a></div><div class="desc docblock-short">Create an iterator running multiple iterators in lockstep.</div></li></ul><h2 id="enums" class="section-header"><a href="#enums">Enums</a></h2><ul class="item-table"><li><div class="item-name"><a class="enum" href="enum.Diff.html" title="enum itertools::Diff">Diff</a></div><div class="desc docblock-short">A type returned by the <a href="fn.diff_with.html" title="fn itertools::diff_with"><code>diff_with</code></a> function.</div></li><li><div class="item-name"><a class="enum" href="enum.Either.html" title="enum itertools::Either">Either</a></div><div class="desc docblock-short">The enum <code>Either</code> with variants <code>Left</code> and <code>Right</code> is a general purpose
sum type with two cases.</div></li><li><div class="item-name"><a class="enum" href="enum.EitherOrBoth.html" title="enum itertools::EitherOrBoth">EitherOrBoth</a></div><div class="desc docblock-short">Value that either holds a single A or B, or both.</div></li><li><div class="item-name"><a class="enum" href="enum.FoldWhile.html" title="enum itertools::FoldWhile">FoldWhile</a></div><div class="desc docblock-short">An enum used for controlling the execution of <code>fold_while</code>.</div></li><li><div class="item-name"><a class="enum" href="enum.MinMaxResult.html" title="enum itertools::MinMaxResult">MinMaxResult</a></div><div class="desc docblock-short"><code>MinMaxResult</code> is an enum returned by <code>minmax</code>.</div></li><li><div class="item-name"><a class="enum" href="enum.Position.html" title="enum itertools::Position">Position</a></div><div class="desc docblock-short">The first component of the value yielded by <code>WithPosition</code>.
Indicates the position of this element in the iterator results.</div></li></ul><h2 id="traits" class="section-header"><a href="#traits">Traits</a></h2><ul class="item-table"><li><div class="item-name"><a class="trait" href="trait.Itertools.html" title="trait itertools::Itertools">Itertools</a></div><div class="desc docblock-short">An <a href="https://doc.rust-lang.org/1.76.0/core/iter/traits/iterator/trait.Iterator.html" title="trait core::iter::traits::iterator::Iterator"><code>Iterator</code></a> blanket implementation that provides extra adaptors and
methods.</div></li><li><div class="item-name"><a class="trait" href="trait.MultiUnzip.html" title="trait itertools::MultiUnzip">MultiUnzip</a></div><div class="desc docblock-short">An iterator that can be unzipped into multiple collections.</div></li><li><div class="item-name"><a class="trait" href="trait.PeekingNext.html" title="trait itertools::PeekingNext">PeekingNext</a></div><div class="desc docblock-short">An iterator that allows peeking at an element before deciding to accept it.</div></li></ul><h2 id="functions" class="section-header"><a href="#functions">Functions</a></h2><ul class="item-table"><li><div class="item-name"><a class="fn" href="fn.all.html" title="fn itertools::all">all</a></div><div class="desc docblock-short">Test whether the predicate holds for all elements in the iterable.</div></li><li><div class="item-name"><a class="fn" href="fn.any.html" title="fn itertools::any">any</a></div><div class="desc docblock-short">Test whether the predicate holds for any elements in the iterable.</div></li><li><div class="item-name"><a class="fn" href="fn.assert_equal.html" title="fn itertools::assert_equal">assert_equal</a></div><div class="desc docblock-short">Assert that two iterables produce equal sequences, with the same
semantics as <a href="fn.equal.html" title="fn itertools::equal"><code>equal(a, b)</code></a>.</div></li><li><div class="item-name"><a class="fn" href="fn.chain.html" title="fn itertools::chain">chain</a></div><div class="desc docblock-short">Takes two iterables and creates a new iterator over both in sequence.</div></li><li><div class="item-name"><a class="fn" href="fn.cloned.html" title="fn itertools::cloned">cloned</a></div><div class="desc docblock-short">Create an iterator that clones each element from &amp;T to T</div></li><li><div class="item-name"><a class="fn" href="fn.concat.html" title="fn itertools::concat">concat</a></div><div class="desc docblock-short">Combine all an iterators elements into one element by using <a href="https://doc.rust-lang.org/1.76.0/core/iter/traits/collect/trait.Extend.html" title="trait core::iter::traits::collect::Extend"><code>Extend</code></a>.</div></li><li><div class="item-name"><a class="fn" href="fn.cons_tuples.html" title="fn itertools::cons_tuples">cons_tuples</a></div><div class="desc docblock-short">Create an iterator that maps for example iterators of
<code>((A, B), C)</code> to <code>(A, B, C)</code>.</div></li><li><div class="item-name"><a class="fn" href="fn.diff_with.html" title="fn itertools::diff_with">diff_with</a></div><div class="desc docblock-short">Compares every element yielded by both <code>i</code> and <code>j</code> with the given function in lock-step and
returns a <a href="enum.Diff.html" title="enum itertools::Diff"><code>Diff</code></a> which describes how <code>j</code> differs from <code>i</code>.</div></li><li><div class="item-name"><a class="fn" href="fn.enumerate.html" title="fn itertools::enumerate">enumerate</a></div><div class="desc docblock-short">Iterate <code>iterable</code> with a running index.</div></li><li><div class="item-name"><a class="fn" href="fn.equal.html" title="fn itertools::equal">equal</a></div><div class="desc docblock-short">Return <code>true</code> if both iterables produce equal sequences
(elements pairwise equal and sequences of the same length),
<code>false</code> otherwise.</div></li><li><div class="item-name"><a class="fn" href="fn.fold.html" title="fn itertools::fold">fold</a></div><div class="desc docblock-short">Perform a fold operation over the iterable.</div></li><li><div class="item-name"><a class="fn" href="fn.interleave.html" title="fn itertools::interleave">interleave</a></div><div class="desc docblock-short">Create an iterator that interleaves elements in <code>i</code> and <code>j</code>.</div></li><li><div class="item-name"><a class="fn" href="fn.intersperse.html" title="fn itertools::intersperse">intersperse</a></div><div class="desc docblock-short">Iterate <code>iterable</code> with a particular value inserted between each element.</div></li><li><div class="item-name"><a class="fn" href="fn.intersperse_with.html" title="fn itertools::intersperse_with">intersperse_with</a></div><div class="desc docblock-short">Iterate <code>iterable</code> with a particular value created by a function inserted
between each element.</div></li><li><div class="item-name"><a class="fn" href="fn.iterate.html" title="fn itertools::iterate">iterate</a></div><div class="desc docblock-short">Creates a new iterator that infinitely applies function to value and yields results.</div></li><li><div class="item-name"><a class="fn" href="fn.join.html" title="fn itertools::join">join</a></div><div class="desc docblock-short">Combine all iterator elements into one String, separated by <code>sep</code>.</div></li><li><div class="item-name"><a class="fn" href="fn.kmerge.html" title="fn itertools::kmerge">kmerge</a></div><div class="desc docblock-short">Create an iterator that merges elements of the contained iterators using
the ordering function.</div></li><li><div class="item-name"><a class="fn" href="fn.kmerge_by.html" title="fn itertools::kmerge_by">kmerge_by</a></div><div class="desc docblock-short">Create an iterator that merges elements of the contained iterators.</div></li><li><div class="item-name"><a class="fn" href="fn.max.html" title="fn itertools::max">max</a></div><div class="desc docblock-short">Return the maximum value of the iterable.</div></li><li><div class="item-name"><a class="fn" href="fn.merge.html" title="fn itertools::merge">merge</a></div><div class="desc docblock-short">Create an iterator that merges elements in <code>i</code> and <code>j</code>.</div></li><li><div class="item-name"><a class="fn" href="fn.merge_join_by.html" title="fn itertools::merge_join_by">merge_join_by</a></div><div class="desc docblock-short">Return an iterator adaptor that merge-joins items from the two base iterators in ascending order.</div></li><li><div class="item-name"><a class="fn" href="fn.min.html" title="fn itertools::min">min</a></div><div class="desc docblock-short">Return the minimum value of the iterable.</div></li><li><div class="item-name"><a class="fn" href="fn.multipeek.html" title="fn itertools::multipeek">multipeek</a></div><div class="desc docblock-short">An iterator adaptor that allows the user to peek at multiple <code>.next()</code>
values without advancing the base iterator.</div></li><li><div class="item-name"><a class="fn" href="fn.multiunzip.html" title="fn itertools::multiunzip">multiunzip</a></div><div class="desc docblock-short">Converts an iterator of tuples into a tuple of containers.</div></li><li><div class="item-name"><a class="fn" href="fn.multizip.html" title="fn itertools::multizip">multizip</a></div><div class="desc docblock-short">An iterator that generalizes <em>.zip()</em> and allows running multiple iterators in lockstep.</div></li><li><div class="item-name"><a class="fn" href="fn.partition.html" title="fn itertools::partition">partition</a></div><div class="desc docblock-short">Partition a sequence using predicate <code>pred</code> so that elements
that map to <code>true</code> are placed before elements which map to <code>false</code>.</div></li><li><div class="item-name"><a class="fn" href="fn.peek_nth.html" title="fn itertools::peek_nth">peek_nth</a></div><div class="desc docblock-short">A drop-in replacement for <a href="https://doc.rust-lang.org/1.76.0/core/iter/adapters/peekable/struct.Peekable.html" title="struct core::iter::adapters::peekable::Peekable"><code>std::iter::Peekable</code></a> which adds a <code>peek_nth</code>
method allowing the user to <code>peek</code> at a value several iterations forward
without advancing the base iterator.</div></li><li><div class="item-name"><a class="fn" href="fn.process_results.html" title="fn itertools::process_results">process_results</a></div><div class="desc docblock-short">“Lift” a function of the values of an iterator so that it can process
an iterator of <code>Result</code> values instead.</div></li><li><div class="item-name"><a class="fn" href="fn.put_back.html" title="fn itertools::put_back">put_back</a></div><div class="desc docblock-short">Create an iterator where you can put back a single item</div></li><li><div class="item-name"><a class="fn" href="fn.put_back_n.html" title="fn itertools::put_back_n">put_back_n</a></div><div class="desc docblock-short">Create an iterator where you can put back multiple values to the front
of the iteration.</div></li><li><div class="item-name"><a class="fn" href="fn.rciter.html" title="fn itertools::rciter">rciter</a></div><div class="desc docblock-short">Return an iterator inside a <code>Rc&lt;RefCell&lt;_&gt;&gt;</code> wrapper.</div></li><li><div class="item-name"><a class="fn" href="fn.repeat_call.html" title="fn itertools::repeat_call">repeat_call</a><span class="stab deprecated" title="">Deprecated</span></div><div class="desc docblock-short">An iterator source that produces elements indefinitely by calling
a given closure.</div></li><li><div class="item-name"><a class="fn" href="fn.repeat_n.html" title="fn itertools::repeat_n">repeat_n</a></div><div class="desc docblock-short">Create an iterator that produces <code>n</code> repetitions of <code>element</code>.</div></li><li><div class="item-name"><a class="fn" href="fn.rev.html" title="fn itertools::rev">rev</a></div><div class="desc docblock-short">Iterate <code>iterable</code> in reverse.</div></li><li><div class="item-name"><a class="fn" href="fn.sorted.html" title="fn itertools::sorted">sorted</a></div><div class="desc docblock-short">Sort all iterator elements into a new iterator in ascending order.</div></li><li><div class="item-name"><a class="fn" href="fn.sorted_unstable.html" title="fn itertools::sorted_unstable">sorted_unstable</a></div><div class="desc docblock-short">Sort all iterator elements into a new iterator in ascending order.
This sort is unstable (i.e., may reorder equal elements).
<a href="https://doc.rust-lang.org/1.76.0/core/iter/traits/collect/trait.IntoIterator.html" title="trait core::iter::traits::collect::IntoIterator"><code>IntoIterator</code></a> enabled version of <a href="trait.Itertools.html#method.sorted_unstable" title="method itertools::Itertools::sorted_unstable"><code>Itertools::sorted_unstable</code></a>.</div></li><li><div class="item-name"><a class="fn" href="fn.unfold.html" title="fn itertools::unfold">unfold</a></div><div class="desc docblock-short">Creates a new unfold source with the specified closure as the “iterator
function” and an initial state to eventually pass to the closure</div></li><li><div class="item-name"><a class="fn" href="fn.zip.html" title="fn itertools::zip">zip</a><span class="stab deprecated" title="">Deprecated</span></div><div class="desc docblock-short">Converts the arguments to iterators and zips them.</div></li><li><div class="item-name"><a class="fn" href="fn.zip_eq.html" title="fn itertools::zip_eq">zip_eq</a></div><div class="desc docblock-short">Iterate <code>i</code> and <code>j</code> in lock step.</div></li></ul></section></div></main></body></html>