Itertools
=========
Extra iterator adaptors, functions and macros.
Please read the `API documentation here`__
__ https://docs.rs/itertools/
|build_status|_ |crates|_
.. |build_status| image:: https://travis-ci.org/rust-itertools/itertools.svg?branch=master
.. _build_status: 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.2
- Use :code:`slice::iter` instead of :code:`into_iter` to avoid future breakage (`#378 <https://github.com/rust-itertools/itertools/pull/378>`_, by `@LukasKalbertodt <https://github.com/LukasKalbertodt>`_)
- 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
- group_by_lazy, chunks_lazy to group_by, chunks
- Unfold::new to unfold()
- RepeatCall::new to repeat_call()
- Zip::new to multizip
- PutBack::new, PutBackN::new to put_back, put_back_n
- PutBack::with_value is now a builder setter, not a constructor
- MultiPeek::new, .multipeek() to multipeek()
- format to format_with and format_default 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
- .sort_by(), use .sorted_by()
- .is_empty_hint(), 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 .minmax_by_key(), 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::with_value and PutBack::into_parts.
- 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 .fn_map(): use .map_fn()
- .interleave_shortest() is no longer guaranteed to act like fused
- 0.3.25
- Rename .sort_by() to .sorted_by(). 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) .group_by_lazy().
- 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 .group_by_lazy()
- 0.3.19
- Added .group_by_lazy(), 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
- .map_fn() replaces deprecated .fn_map().
- 0.3.4
- .take_while_ref() *by-ref adaptor*
- .coalesce() *adaptor*
- .mend_slices() *adaptor*
- 0.3.3
- .dropping_back() *method*
- .fold1() *method*
- .is_empty_hint() *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.