Rust-Itertools: Extra iterator adaptors, iterator methods, free functions, and macros.


Extra iterator adaptors, functions and macros.

Please read the API documentation here

build_status crates

How to use with cargo:

itertools = "0.9"

How to use in your crate:

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, 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.


Dual-licensed to be compatible with the Rust project.

Licensed under the Apache License, Version 2.0 or the MIT license, at your option. This file may not be copied, modified, or distributed except according to those terms.


  • impl debug trait for diff enum
    impl debug trait for diff enum

    May 11, 2020

    I added a fairly simple yet informative fmt::Debug implementation to the Diff enum. The reasoning behind this is to simplify tests where you just want to say:

    // Diff some expected iter with the actual outputted one
    let diff = itertools::diff_with(ex, out, |a, b| a == b);
    // Now, all you care about is that there is no difference
    // If there is, the index of the diff will be logged by assert_eq!
    // since diff now impls fmt::Debug
    assert_eq!(None, diff);
  • Implement DedupBy in terms of Coalesce
    Implement DedupBy in terms of Coalesce

    May 18, 2020

    During the discussion of, we found that DedupBy/DedupByWithCount could actually be implemented in terms of Coalesce. This simplifies the implementation quite a bit and lets derived adaptors inherit specializations.

    • Implement fold on Coalesce so that all the adaptors derived from it inherit the specialization (currently, only DedupBy has this specialization).
    • Introduce CoalescePredicate (similar to DedupPredicate) to allow for different customizations of Coalesce.
    • Introduce parametrizable CoalesceBy: Base for Coalesce, DedupBy, DedupByWithCount.
    • Implement DedupBy/DedupByWithCount in terms of CoalesceBy (using particular impls).
    • At last, the indirection through CoalesceCore is not needed anymore.
  • Add assert_empty?
    Add assert_empty?

    May 29, 2020

    I think this would be a useful addition.

    pub fn assert_empty<I>(i: impl IntoIterator<Item = I>)
        I: Debug + PartialEq<I>,
        assert_equal(i, iter::empty::<I>());

    Except it probably needs to have it's own error message implementation since "left" and "right" wouldn't make sense.

  • Added Range iterator
    Added Range iterator

    Jun 5, 2020

    I thought an iterator that iterates over a range of values would be pretty neat to have. Use if you want to!

  • Interleave doc should explains how it is different from `std::iter::zip`
    Interleave doc should explains how it is different from `std::iter::zip`

    Jun 11, 2020

    When reading the documentation of interleave I wasn't able to understand what is the difference with std::iter::zip(), and why/when should one be preferred to the other.

  • Improve `tuple_windows()` doc (add a reference to `pairwise`)
    Improve `tuple_windows()` doc (add a reference to `pairwise`)

    Jun 11, 2020

    As shown in #388, tuple_windows can be hard to find if you come from other environment (python, RxJs, …) since people may expect to find a pairwise() method instead.

  • Added `` module with `diff` and `copy_on_diff` - for efficiently
    Added `` module with `diff` and `copy_on_diff` - for efficiently "diff"ing and caching non-`Clone` iterators.

    Jan 3, 2016

    I originally wrote this module for a couple of cases in conrod where I wanted to cache a non-Clone iterator without having to collect the iterator into a Vec for comparison in case the cache needed updating.

    I've just come across another similar case in a personal project, so before copying code across I thought I'd approach the itertools team in case you deem it worthy of adding to your luscious collection.

    Either way, any feedback appreciated!

  • Add `exhaust` which simply exhausts the iterator
    Add `exhaust` which simply exhausts the iterator

    Jun 20, 2016

    This is useful for iterators which are simply used for their side effects.

    The new function is added to make intent clearer for places where you'd previously call count or similar to exhaust the iterator.

  • Add k-way merge adaptor.
    Add k-way merge adaptor.

    Feb 12, 2016

    Merges an arbitrary number of iterators in ascending order.

    Uses std's BinaryHeap to decide which iterator to take from next. This seems quite heavyweight. Two-way merge benchmarks take roughly ten times longer than the dedicated two-way merge adaptor. Profiling identifies BinaryHeaps sift_up as the hot-spot.

    Not completely sure about the interface, the double use of IntoIterator in the free-standing function in particular.

  • map_into method
    map_into method

    Jun 2, 2018

    To allow easy conversion of all elements.

    fixes #280 (map_into sounded better than map_from).

  • Preparation for next release series (0.5.x)
    Preparation for next release series (0.5.x)

    Sep 19, 2016

    We will remove a lot of deprecated items, and rename some.

    This is on the road towards an eventual 1.0 version of the library.


    • Numerical things will move because we don't want num-traits in itertools. linspace will move to a crate that uses num-traits
    • Use free functions to construct iterators that are sources. For example Unfold::new(x, y)unfold(x, y). Follows libstd convention (std::iter::once).
    • Unstable/nightly parts will need to live in another crate
    • Rename and move stuff around to increase consistency. This is the best for the long run.
    • See the commits for an overview

    See also #87

    Fixes #86

  • Add exactly_one function
    Add exactly_one function

    Oct 2, 2018

    Adds a small function I found uses for personally. Can't be added to the core library because in the error case it allocates a vec and stores data in it.