| |
| 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/bluss/rust-itertools.svg?branch=master |
| .. _build_status: https://travis-ci.org/bluss/rust-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.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. |
