Itertools

Extra iterator adaptors, functions and macros.

Please read the API documentation here__

__ https://docs.rs/itertools/

|buildstatus| |crates|_

.. |buildstatus| image:: https://travis-ci.org/rust-itertools/itertools.svg?branch=master .. _buildstatus: https://travis-ci.org/rust-itertools/itertools

.. |crates| image:: http://meritbadge.herokuapp.com/itertools .. _crates: https://crates.io/crates/itertools

How to use with cargo:

.. code:: toml

[dependencies]
itertools = "0.8"

How to use in your crate:

.. code:: rust

#[macro_use] extern crate itertools;

use itertools::Itertools;

How to contribute

• Fix a bug or implement a new thing
• Include tests for your new feature, preferably a quickcheck test
• Make a Pull Request

For new features, please first consider filing a PR to rust-lang/rust <https://github.com/rust-lang/rust/>_, adding your new feature to the Iterator trait of the standard library, if you believe it is reasonable. If it isn't accepted there, proposing it for inclusion in itertools is a good idea. The reason for doing is this is so that we avoid future breakage as with .flatten(). However, if your feature involves heap allocation, such as storing elements in a Vec<T>, then it can't be accepted into libcore, and you should propose it for itertools directly instead.

Recent Changes

• 0.8.1

  • Added a .exactly_one() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.exactly_one>_ iterator method that, on success, extracts the single value of an iterator ; by @Xaeroxe <https://github.com/Xaeroxe>_

  • Added combinatory iterator adaptors:

  • .permutations(k) <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.permutations>_:

    [0, 1, 2].iter().permutations(2) yields

    .. code:: rust

    [ vec![0, 1], vec![0, 2], vec![1, 0], vec![1, 2], vec![2, 0], vec![2, 1], ]

    ; by @tobz1000 <https://github.com/tobz1000>_

  • .combinations_with_replacement(k) <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.combinations_with_replacement>_:

    [0, 1, 2].iter().combinations_with_replacement(2) yields

    .. code:: rust

    [ vec![0, 0], vec![0, 1], vec![0, 2], vec![1, 1], vec![1, 2], vec![2, 2], ]

    ; by @tommilligan <https://github.com/tommilligan>_

  • For reference, these methods join the already existing .combinations(k) <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.combinations>_:

    [0, 1, 2].iter().combinations(2) yields

    .. code:: rust

    [ vec![0, 1], vec![0, 2], vec![1, 2], ]

  • Improved the performance of .fold() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.fold>-based internal iteration for the .intersperse() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.intersperse> iterator ; by @jswrenn <https://github.com/jswrenn>_

  • Added .dedup_by() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.dedup_by>, .merge_by() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.merge_by> and .kmerge_by() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.kmerge_by>_ adaptors that work like .dedup() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.dedup>, .merge() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.merge> and .kmerge() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.kmerge>, but taking an additional custom comparison closure parameter. ; by @phimuemue <https://github.com/phimuemue>

  • Improved the performance of .all_equal() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.all_equal>_ ; by @fyrchik <https://github.com/fyrchik>_

  • Loosened the bounds on .partition_map() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.partition_map>_ to take just a FnMut closure rather than a Fn closure, and made its implementation use internal iteration for better performance ; by @danielhenrymantilla <https://github.com/danielhenrymantilla>_

  • Added convenience methods to EitherOrBoth <https://docs.rs/itertools/0.8.1/itertools/enum.EitherOrBoth.html>_ elements yielded from the .zip_longest() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.zip_longest>_ iterator adaptor ; by @Avi-D-coder <https://github.com/Avi-D-coder>_

  • Added .sum1() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.sum1>_ and .product1() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.product1>_ iterator methods that respectively try to return the sum and the product of the elements of an iterator when it is not empty, otherwise they return None ; by @Emerentius <https://github.com/Emerentius>_

• 0.8.0

  • Added new adaptor .map_into() for conversions using Into by @vorner
  • Improved Itertools docs by @JohnHeitmann
  • The return type of .sorted/_by/_by_key() is now an iterator, not a Vec.
  • The return type of the izip!(x, y) macro with exactly two arguments is now the usual Iterator::zip.
  • Remove .flatten() in favour of std's .flatten()
  • Deprecate .foreach() in favour of std's .for_each()
  • Deprecate .step() in favour of std's .step_by()
  • Deprecate repeat_call in favour of std's repeat_with
  • Deprecate .fold_while() in favour of std's .try_fold()
  • Require Rust 1.24 as minimal version.

• 0.7.11

  • Add convenience methods to EitherOrBoth, making it more similar to Option and Either by @jethrogb

• 0.7.10

  • No changes.

• 0.7.9

  • New inclusion policy: See the readme about suggesting features for std before accepting them in itertools.
  • The FoldWhile type now implements Eq and PartialEq by @jturner314

• 0.7.8

  • Add new iterator method .tree_fold1() which is like .fold1() except items are combined in a tree structure (see its docs). By @scottmcm
  • Add more Debug impls by @phimuemue: KMerge, KMergeBy, MergeJoinBy, ConsTuples, Intersperse, ProcessResults, RcIter, Tee, TupleWindows, Tee, ZipLongest, ZipEq, Zip.

• 0.7.7

  • Add new iterator method .into_group_map() -> HashMap<K, Vec<V>> which turns an iterator of (K, V) elements into such a hash table, where values are grouped by key. By @tobz1000
  • Add new free function flatten for the .flatten() adaptor. NOTE: recent Rust nightlies have Iterator::flatten and thus a clash with our flatten adaptor. One workaround is to use the itertools flatten free function.

• 0.7.6

  • Add new adaptor .multi_cartesian_product() which is an n-ary product iterator by @tobz1000
  • Add new method .sorted_by_key() by @Xion
  • Provide simpler and faster .count() for .unique() and .unique_by()

• 0.7.5

  • .multipeek() now implements PeekingNext, by @nicopap.

• 0.7.4

  • Add new adaptor .update() by @lucasem; this adaptor is used to modify an element before passing it on in an iterator chain.

• 0.7.3

  • Add new method .collect_tuple() by @matklad; it makes a tuple out of the iterator's elements if the number of them matches exactly.
  • Implement fold and collect for .map_results() which means it reuses the code of the standard .map() for these methods.

• 0.7.2

  • Add new adaptor .merge_join_by by @srijs; a heterogeneous merge join for two ordered sequences.

• 0.7.1

  • Iterator adaptors and iterators in itertools now use the same must_use reminder that the standard library adaptors do, by @matematikaedit and @bluss “iterator adaptors are lazy and do nothing unless consumed”.

• 0.7.0

  • Faster izip!() by @krdln

  • izip!() is now a wrapper for repeated regular .zip() and a single .map(). This means it optimizes as well as the standard library .zip() it uses. Note: multizip and izip!() are now different! The former has a named type but the latter optimizes better.

  • Faster .unique()

  • no_std support, which is opt-in!

  • Many lovable features are still there without std, like izip!() or .format() or .merge(), but not those that use collections.

  • Trait bounds were required up front instead of just on the type: group_by's PartialEq by @Phlosioneer and repeat_call's FnMut.

  • Removed deprecated constructor Zip::new — use izip!() or multizip()

• 0.6.5

  • Fix bug in .cartesian_product()'s fold (which only was visible for unfused iterators).

• 0.6.4

  • Add specific fold implementations for .cartesian_product() and cons_tuples(), which improves their performance in fold, foreach, and iterator consumers derived from them.

• 0.6.3

  • Add iterator adaptor .positions(predicate) by @tmccombs

• 0.6.2

  • Add function process_results which can “lift” a function of the regular values of an iterator so that it can process the Ok values from an iterator of Results instead, by @shepmaster
  • Add iterator method .concat() which combines all iterator elements into a single collection using the Extend trait, by @srijs

• 0.6.1

  • Better size hint testing and subsequent size hint bugfixes by @rkarp. Fixes bugs in product, interleave_shortest size hints.
  • New iterator method .all_equal() by @phimuemue

• 0.6.0

  • Deprecated names were removed in favour of their replacements
  • .flatten() does not implement double ended iteration anymore
  • .fold_while() uses &mut self and returns FoldWhile<T>, for composability (#168)
  • .foreach() and .fold1() use self, like .fold() does.
  • .combinations(0) now produces a single empty vector. (#174)

• 0.5.10

  • Add itertools method .kmerge_by() (and corresponding free function)
  • Relaxed trait requirement of .kmerge() and .minmax() to PartialOrd.

• 0.5.9

  • Add multipeek method .reset_peek()
  • Add categories

• 0.5.8

  • Add iterator adaptor .peeking_take_while() and its trait PeekingNext.

• 0.5.7

  • Add iterator adaptor .with_position()
  • Fix multipeek's performance for long peeks by using VecDeque.

• 0.5.6

  • Add .map_results()

• 0.5.5

  • Many more adaptors now implement Debug
  • Add free function constructor repeat_n. RepeatN::new is now deprecated.

• 0.5.4

  • Add infinite generator function iterate, that takes a seed and a closure.

• 0.5.3

  • Special-cased .fold() for flatten and put back. .foreach() now uses fold on the iterator, to pick up any iterator specific loop implementation.
  • .combinations(n) asserts up front that n != 0, instead of running into an error on the second iterator element.

• 0.5.2

  • Add .tuples::<T>() that iterates by two, three or four elements at a time (where T is a tuple type).
  • Add .tuple_windows::<T>() that iterates using a window of the two, three or four most recent elements.
  • Add .next_tuple::<T>() method, that picks the next two, three or four elements in one go.
  • .interleave() now has an accurate size hint.

• 0.5.1

  • Workaround module/function name clash that made racer crash on completing itertools. Only internal changes needed.

• 0.5.0

  • Release announcement <http://bluss.github.io/rust/2016/09/26/itertools-0.5.0/>_

  • Renamed:

  • combinations is now tuple_combinations

  • combinations_n to combinations
  • groupbylazy, chunkslazy to groupby, chunks
  • Unfold::new to unfold()
  • RepeatCall::new to repeat_call()
  • Zip::new to multizip
  • PutBack::new, PutBackN::new to putback, putback_n
  • PutBack::with_value is now a builder setter, not a constructor
  • MultiPeek::new, .multipeek() to multipeek()
  • format to formatwith and formatdefault to format
  • .into_rc() to rciter

  • Partition enum is now Either

  • Module reorganization:

  • All iterator structs are under itertools::structs but also reexported to the top level, for backwards compatibility

  • All free functions are reexported at the root, itertools::free will be removed in the next version

  • Removed:

  • ZipSlices, use .zip() instead

  • .enumerate_from(), ZipTrusted, due to being unstable
  • .mend_slices(), moved to crate odds
  • Stride, StrideMut, moved to crate odds
  • linspace(), moved to crate itertools-num
  • .sortby(), use .sortedby()
  • .isemptyhint(), use .size_hint()
  • .dropn(), use .dropping()
  • .map_fn(), use .map()
  • .slice(), use .take() / .skip()
  • helper traits in misc
  • new constructors on iterator structs, use Itertools trait or free functions instead

  • itertools::size_hint is now private

  • Behaviour changes:

  • format and format_with helpers now panic if you try to format them more than once.

  • repeat_call is not double ended anymore

  • New features:

  • tuple flattening iterator is constructible with cons_tuples

  • itertools reexports Either from the either crate. Either<L, R> is an iterator when L, R are.
  • MinMaxResult now implements Copy and Clone
  • tuple_combinations supports 1-4 tuples of combinations (previously just 2)

• 0.4.19

  • Add .minmax_by()
  • Add itertools::free::cloned
  • Add itertools::free::rciter
  • Improve .step(n) slightly to take advantage of specialized Fuse better.

• 0.4.18

  • Only changes related to the "unstable" crate feature. This feature is more or less deprecated.

  • Use deprecated warnings when unstable is enabled. .enumerate_from() will be removed imminently since it's using a deprecated libstd trait.

• 0.4.17

  • Fix bug in .kmerge() that caused it to often produce the wrong order (#134)

• 0.4.16

  • Improve precision of the interleave_shortest adaptor's size hint (it is now computed exactly when possible).

• 0.4.15

  • Fixup on top of the workaround in 0.4.14. A function in itertools::free was removed by mistake and now it is added back again.

• 0.4.14

  • Workaround an upstream regression in a rust nightly build that broke compilation of of itertools::free::{interleave, merge}

• 0.4.13

  • Add .minmax() and .minmaxbykey(), iterator methods for finding both minimum and maximum in one scan.
  • Add .format_default(), a simpler version of .format() (lazy formatting for iterators).

• 0.4.12

  • Add .zip_eq(), an adaptor like .zip() except it ensures iterators of inequal length don't pass silently (instead it panics).
  • Add .fold_while(), an iterator method that is a fold that can short-circuit.
  • Add .partition_map(), an iterator method that can separate elements into two collections.

• 0.4.11

  • Add .get() for Stride{,Mut} and .get_mut() for StrideMut

• 0.4.10

  • Improve performance of .kmerge()

• 0.4.9

  • Add k-ary merge adaptor .kmerge()
  • Fix a bug in .islice() with ranges a..b where a > b.

• 0.4.8

  • Implement Clone, Debug for Linspace

• 0.4.7

  • Add function diff_with() that compares two iterators
  • Add .combinations_n(), an n-ary combinations iterator
  • Add methods PutBack::withvalue and PutBack::intoparts.

• 0.4.6

  • Add method .sorted()
  • Add module itertools::free with free function variants of common iterator adaptors and methods. For example enumerate(iterable), rev(iterable), and so on.

• 0.4.5

  • Add .flatten()

• 0.4.4

  • Allow composing ZipSlices with itself

• 0.4.3

  • Write iproduct!() as a single expression; this allows temporary values in its arguments.

• 0.4.2

  • Add .fold_options()
  • Require Rust 1.1 or later

• 0.4.1

  • Update .dropping() to take advantage of .nth()

• 0.4.0

  • .merge(), .unique() and .dedup() now perform better due to not using function pointers
  • Add free functions enumerate() and rev()

  • Breaking changes:

  • Return types of .merge() and .merge_by() renamed and changed

  • Method Merge::new removed
  • .merge_by() now takes a closure that returns bool.
  • Return type of .dedup() changed
  • Return type of .mend_slices() changed
  • Return type of .unique() changed
  • Removed function times(), struct Times: use a range instead
  • Removed deprecated macro icompr!()
  • Removed deprecated FnMap and method .fnmap(): use .mapfn()
  • .interleave_shortest() is no longer guaranteed to act like fused

• 0.3.25

  • Rename .sortby() to .sortedby(). Old name is deprecated.
  • Fix well-formedness warnings from RFC 1214, no user visible impact

• 0.3.24

  • Improve performance of .merge()'s ordering function slightly

• 0.3.23

  • Added .chunks(), similar to (and based on) .groupbylazy().
  • Tweak linspace to match numpy.linspace and make it double ended.

• 0.3.22

  • Added ZipSlices, a fast zip for slices

• 0.3.21

  • Remove Debug impl for Format, it will have different use later

• 0.3.20

  • Optimize .groupbylazy()

• 0.3.19

  • Added .groupbylazy(), a possibly nonallocating group by
  • Added .format(), a nonallocating formatting helper for iterators
  • Remove uses of RandomAccessIterator since it has been deprecated in rust.

• 0.3.17

  • Added (adopted) Unfold from rust

• 0.3.16

  • Added adaptors .unique(), .unique_by()

• 0.3.15

  • Added method .sort_by()

• 0.3.14

  • Added adaptor .while_some()

• 0.3.13

  • Added adaptor .interleave_shortest()
  • Added adaptor .pad_using()

• 0.3.11

  • Added assert_equal function

• 0.3.10

  • Bugfix .combinations() size_hint.

• 0.3.8

  • Added source RepeatCall

• 0.3.7

  • Added adaptor PutBackN
  • Added adaptor .combinations()

• 0.3.6

  • Added itertools::partition, partition a sequence in place based on a predicate.
  • Deprecate icompr!() with no replacement.

• 0.3.5

  • .mapfn() replaces deprecated .fnmap().

• 0.3.4

  • .takewhileref() by-ref adaptor
  • .coalesce() adaptor
  • .mend_slices() adaptor

• 0.3.3

  • .dropping_back() method
  • .fold1() method
  • .isemptyhint() method

License

Dual-licensed to be compatible with the Rust project.

Licensed under the Apache License, Version 2.0 http://www.apache.org/licenses/LICENSE-2.0 or the MIT license http://opensource.org/licenses/MIT, at your option. This file may not be copied, modified, or distributed except according to those terms.