5 Extra iterator adaptors, functions and macros.
7 Please read the `API documentation here`__
9 __ https://docs.rs/itertools/
11 |build_status|_ |crates|_
13 .. |build_status| image:: https://travis-ci.org/bluss/rust-itertools.svg?branch=master
14 .. _build_status: https://travis-ci.org/bluss/rust-itertools
16 .. |crates| image:: http://meritbadge.herokuapp.com/itertools
17 .. _crates: https://crates.io/crates/itertools
19 How to use with cargo:
26 How to use in your crate:
30 #[macro_use] extern crate itertools;
32 use itertools::Itertools;
36 - Fix a bug or implement a new thing
37 - Include tests for your new feature, preferably a quickcheck test
46 - Add new adaptor ``.multi_cartesian_product()`` which is an n-ary product
48 - Add new method ``.sorted_by_key()`` by @Xion
49 - Provide simpler and faster ``.count()`` for ``.unique()`` and ``.unique_by()``
53 - ``.multipeek()`` now implements ``PeekingNext``, by @nicopap.
57 - Add new adaptor ``.update()`` by @lucasem; this adaptor is used
58 to modify an element before passing it on in an iterator chain.
62 - Add new method ``.collect_tuple()`` by @matklad; it makes a tuple out of
63 the iterator's elements if the number of them matches **exactly**.
64 - Implement ``fold`` and ``collect`` for ``.map_results()`` which means
65 it reuses the code of the standard ``.map()`` for these methods.
69 - Add new adaptor ``.merge_join_by`` by @srijs; a heterogeneous merge join
70 for two ordered sequences.
74 - Iterator adaptors and iterators in itertools now use the same ``must_use``
75 reminder that the standard library adaptors do, by @matematikaedit and @bluss
76 *“iterator adaptors are lazy and do nothing unless consumed”*.
80 - Faster ``izip!()`` by @krdln
82 - ``izip!()`` is now a wrapper for repeated regular ``.zip()`` and
83 a single ``.map()``. This means it optimizes as well as the standard
84 library ``.zip()`` it uses.
85 **Note:** ``multizip`` and ``izip!()`` are now different! The former
86 has a named type but the latter optimizes better.
88 - Faster ``.unique()``
90 - ``no_std`` support, which is opt-in!
92 - Many lovable features are still there without std, like ``izip!()``
93 or ``.format()`` or ``.merge()``, but not those that use collections.
95 - Trait bounds were required up front instead of just on the type:
96 ``group_by``'s ``PartialEq`` by @Phlosioneer and ``repeat_call``'s
98 - Removed deprecated constructor ``Zip::new`` — use ``izip!()`` or ``multizip()``
102 - Fix bug in ``.cartesian_product()``'s fold (which only was visible for
107 - Add specific ``fold`` implementations for ``.cartesian_product()`` and
108 ``cons_tuples()``, which improves their performance in fold, foreach, and
109 iterator consumers derived from them.
113 - Add iterator adaptor ``.positions(predicate)`` by @tmccombs
117 - Add function ``process_results`` which can “lift” a function of the regular
118 values of an iterator so that it can process the ``Ok`` values from an
119 iterator of ``Results`` instead, by @shepmaster
120 - Add iterator method ``.concat()`` which combines all iterator elements
121 into a single collection using the ``Extend`` trait, by @srijs
125 - Better size hint testing and subsequent size hint bugfixes by @rkarp.
126 Fixes bugs in product, interleave_shortest size hints.
127 - New iterator method ``.all_equal()`` by @phimuemue
131 - Deprecated names were removed in favour of their replacements
132 - ``.flatten()`` does not implement double ended iteration anymore
133 - ``.fold_while()`` uses ``&mut self`` and returns ``FoldWhile<T>``, for
135 - ``.foreach()`` and ``.fold1()`` use ``self``, like ``.fold()`` does.
136 - ``.combinations(0)`` now produces a single empty vector. (#174)
140 - Add itertools method ``.kmerge_by()`` (and corresponding free function)
141 - Relaxed trait requirement of ``.kmerge()`` and ``.minmax()`` to PartialOrd.
145 - Add multipeek method ``.reset_peek()``
150 - Add iterator adaptor ``.peeking_take_while()`` and its trait ``PeekingNext``.
154 - Add iterator adaptor ``.with_position()``
155 - Fix multipeek's performance for long peeks by using ``VecDeque``.
159 - Add ``.map_results()``
163 - Many more adaptors now implement ``Debug``
164 - Add free function constructor ``repeat_n``. ``RepeatN::new`` is now
169 - Add infinite generator function ``iterate``, that takes a seed and a
174 - Special-cased ``.fold()`` for flatten and put back. ``.foreach()``
175 now uses fold on the iterator, to pick up any iterator specific loop
177 - ``.combinations(n)`` asserts up front that ``n != 0``, instead of
178 running into an error on the second iterator element.
182 - Add ``.tuples::<T>()`` that iterates by two, three or four elements at
183 a time (where ``T`` is a tuple type).
184 - Add ``.tuple_windows::<T>()`` that iterates using a window of the
185 two, three or four most recent elements.
186 - Add ``.next_tuple::<T>()`` method, that picks the next two, three or four
188 - ``.interleave()`` now has an accurate size hint.
192 - Workaround module/function name clash that made racer crash on completing
193 itertools. Only internal changes needed.
197 - `Release announcement <http://bluss.github.io/rust/2016/09/26/itertools-0.5.0/>`_
200 - combinations is now tuple_combinations
201 - combinations_n to combinations
202 - group_by_lazy, chunks_lazy to group_by, chunks
203 - Unfold::new to unfold()
204 - RepeatCall::new to repeat_call()
205 - Zip::new to multizip
206 - PutBack::new, PutBackN::new to put_back, put_back_n
207 - PutBack::with_value is now a builder setter, not a constructor
208 - MultiPeek::new, .multipeek() to multipeek()
209 - format to format_with and format_default to format
210 - .into_rc() to rciter
211 - ``Partition`` enum is now ``Either``
213 - Module reorganization:
215 - All iterator structs are under ``itertools::structs`` but also
216 reexported to the top level, for backwards compatibility
217 - All free functions are reexported at the root, ``itertools::free`` will
218 be removed in the next version
222 - ZipSlices, use .zip() instead
223 - .enumerate_from(), ZipTrusted, due to being unstable
224 - .mend_slices(), moved to crate odds
225 - Stride, StrideMut, moved to crate odds
226 - linspace(), moved to crate itertools-num
227 - .sort_by(), use .sorted_by()
228 - .is_empty_hint(), use .size_hint()
229 - .dropn(), use .dropping()
230 - .map_fn(), use .map()
231 - .slice(), use .take() / .skip()
232 - helper traits in misc
233 - ``new`` constructors on iterator structs, use Itertools trait or free
235 - ``itertools::size_hint`` is now private
239 - format and format_with helpers now panic if you try to format them more
241 - ``repeat_call`` is not double ended anymore
245 - tuple flattening iterator is constructible with ``cons_tuples``
246 - itertools reexports ``Either`` from the ``either`` crate. ``Either<L, R>``
247 is an iterator when ``L, R`` are.
248 - ``MinMaxResult`` now implements Copy and Clone
249 - tuple_combinations supports 1-4 tuples of combinations (previously just 2)
253 - Add ``.minmax_by()``
254 - Add ``itertools::free::cloned``
255 - Add ``itertools::free::rciter``
256 - Improve ``.step(n)`` slightly to take advantage of specialized Fuse better.
260 - Only changes related to the "unstable" crate feature. This feature is more
263 - Use deprecated warnings when unstable is enabled. .enumerate_from() will
264 be removed imminently since it's using a deprecated libstd trait.
268 - Fix bug in .kmerge() that caused it to often produce the wrong order (#134)
272 - Improve precision of the interleave_shortest adaptor's size hint (it is
273 now computed exactly when possible).
277 - Fixup on top of the workaround in 0.4.14. A function in itertools::free was
278 removed by mistake and now it is added back again.
282 - Workaround an upstream regression in a rust nightly build that broke
283 compilation of of itertools::free::{interleave, merge}
287 - Add .minmax() and .minmax_by_key(), iterator methods for finding both minimum
288 and maximum in one scan.
289 - Add .format_default(), a simpler version of .format() (lazy formatting
294 - Add .zip_eq(), an adaptor like .zip() except it ensures iterators
295 of inequal length don't pass silently (instead it panics).
296 - Add .fold_while(), an iterator method that is a fold that
298 - Add .partition_map(), an iterator method that can separate elements
299 into two collections.
303 - Add .get() for Stride{,Mut} and .get_mut() for StrideMut
307 - Improve performance of .kmerge()
311 - Add k-ary merge adaptor .kmerge()
312 - Fix a bug in .islice() with ranges a..b where a > b.
316 - Implement Clone, Debug for Linspace
320 - Add function diff_with() that compares two iterators
321 - Add .combinations_n(), an n-ary combinations iterator
322 - Add methods PutBack::with_value and PutBack::into_parts.
326 - Add method .sorted()
327 - Add module ``itertools::free`` with free function variants of common
328 iterator adaptors and methods.
329 For example ``enumerate(iterable)``, ``rev(iterable)``, and so on.
337 - Allow composing ZipSlices with itself
341 - Write iproduct!() as a single expression; this allows temporary values
346 - Add .fold_options()
347 - Require Rust 1.1 or later
351 - Update .dropping() to take advantage of .nth()
355 - .merge(), .unique() and .dedup() now perform better due to not using
357 - Add free functions enumerate() and rev()
360 - Return types of .merge() and .merge_by() renamed and changed
361 - Method Merge::new removed
362 - .merge_by() now takes a closure that returns bool.
363 - Return type of .dedup() changed
364 - Return type of .mend_slices() changed
365 - Return type of .unique() changed
366 - Removed function times(), struct Times: use a range instead
367 - Removed deprecated macro icompr!()
368 - Removed deprecated FnMap and method .fn_map(): use .map_fn()
369 - .interleave_shortest() is no longer guaranteed to act like fused
373 - Rename .sort_by() to .sorted_by(). Old name is deprecated.
374 - Fix well-formedness warnings from RFC 1214, no user visible impact
378 - Improve performance of .merge()'s ordering function slightly
382 - Added .chunks(), similar to (and based on) .group_by_lazy().
383 - Tweak linspace to match numpy.linspace and make it double ended.
387 - Added ZipSlices, a fast zip for slices
391 - Remove `Debug` impl for `Format`, it will have different use later
395 - Optimize .group_by_lazy()
399 - Added .group_by_lazy(), a possibly nonallocating group by
400 - Added .format(), a nonallocating formatting helper for iterators
401 - Remove uses of RandomAccessIterator since it has been deprecated in rust.
405 - Added (adopted) Unfold from rust
409 - Added adaptors .unique(), .unique_by()
413 - Added method .sort_by()
417 - Added adaptor .while_some()
421 - Added adaptor .interleave_shortest()
422 - Added adaptor .pad_using()
426 - Added assert_equal function
430 - Bugfix .combinations() size_hint.
434 - Added source RepeatCall
438 - Added adaptor PutBackN
439 - Added adaptor .combinations()
443 - Added itertools::partition, partition a sequence in place based on a predicate.
444 - Deprecate icompr!() with no replacement.
448 - .map_fn() replaces deprecated .fn_map().
452 - .take_while_ref() *by-ref adaptor*
453 - .coalesce() *adaptor*
454 - .mend_slices() *adaptor*
458 - .dropping_back() *method*
460 - .is_empty_hint() *method*
465 Dual-licensed to be compatible with the Rust project.
467 Licensed under the Apache License, Version 2.0
468 http://www.apache.org/licenses/LICENSE-2.0 or the MIT license
469 http://opensource.org/licenses/MIT, at your
470 option. This file may not be copied, modified, or distributed
471 except according to those terms.