1
2Itertools
3=========
4
5Extra iterator adaptors, functions and macros.
6
7Please read the `API documentation here`__
8
9__ https://docs.rs/itertools/
10
11|build_status|_ |crates|_
12
13.. |build_status| image:: https://travis-ci.org/rust-itertools/itertools.svg?branch=master
14.. _build_status: https://travis-ci.org/rust-itertools/itertools
15
16.. |crates| image:: http://meritbadge.herokuapp.com/itertools
17.. _crates: https://crates.io/crates/itertools
18
19How to use with cargo:
20
21.. code:: toml
22
23 [dependencies]
24 itertools = "0.8"
25
26How to use in your crate:
27
28.. code:: rust
29
30 #[macro_use] extern crate itertools;
31
32 use itertools::Itertools;
33
34How to contribute
35-----------------
36
37- Fix a bug or implement a new thing
38- Include tests for your new feature, preferably a quickcheck test
39- Make a Pull Request
40
41For new features, please first consider filing a PR to `rust-lang/rust <https://github.com/rust-lang/rust/>`_,
42adding your new feature to the `Iterator` trait of the standard library, if you believe it is reasonable.
43If it isn't accepted there, proposing it for inclusion in ``itertools`` is a good idea.
44The reason for doing is this is so that we avoid future breakage as with ``.flatten()``.
45However, if your feature involves heap allocation, such as storing elements in a ``Vec<T>``,
46then it can't be accepted into ``libcore``, and you should propose it for ``itertools`` directly instead.
47
48Recent Changes
49--------------
50- 0.8.2
51
52 - 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>`_)
53
54- 0.8.1
55
56 - Added a `.exactly_one() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.exactly_one>`_
57 iterator method that, on success, extracts the single value of an
58 iterator
59 ; by `@Xaeroxe <https://github.com/Xaeroxe>`_
60
61 - Added combinatory iterator adaptors:
62
63 - `.permutations(k) <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.permutations>`_:
64
65 ``[0, 1, 2].iter().permutations(2)`` yields
66
67 .. code:: rust
68
69 [
70 vec![0, 1],
71 vec![0, 2],
72 vec![1, 0],
73 vec![1, 2],
74 vec![2, 0],
75 vec![2, 1],
76 ]
77
78 ; by `@tobz1000 <https://github.com/tobz1000>`_
79
80 - `.combinations_with_replacement(k) <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.combinations_with_replacement>`_:
81
82 ``[0, 1, 2].iter().combinations_with_replacement(2)`` yields
83
84 .. code:: rust
85
86 [
87 vec![0, 0],
88 vec![0, 1],
89 vec![0, 2],
90 vec![1, 1],
91 vec![1, 2],
92 vec![2, 2],
93 ]
94
95 ; by `@tommilligan <https://github.com/tommilligan>`_
96
97 - For reference, these methods join the already existing
98 `.combinations(k) <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.combinations>`_:
99
100 ``[0, 1, 2].iter().combinations(2)`` yields
101
102 .. code:: rust
103
104 [
105 vec![0, 1],
106 vec![0, 2],
107 vec![1, 2],
108 ]
109
110 - Improved the performance of `.fold() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.fold>`_-based internal iteration for the
111 `.intersperse() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.intersperse>`_ iterator
112 ; by `@jswrenn <https://github.com/jswrenn>`_
113
114 - Added
115 `.dedup_by() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.dedup_by>`_,
116 `.merge_by() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.merge_by>`_
117 and `.kmerge_by() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.kmerge_by>`_
118 adaptors that work like
119 `.dedup() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.dedup>`_,
120 `.merge() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.merge>`_ and
121 `.kmerge() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.kmerge>`_,
122 but taking an additional custom comparison closure parameter.
123 ; by `@phimuemue <https://github.com/phimuemue>`_
124
125 - Improved the performance of `.all_equal() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.all_equal>`_
126 ; by `@fyrchik <https://github.com/fyrchik>`_
127
128 - Loosened the bounds on `.partition_map() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.partition_map>`_
129 to take just a ``FnMut`` closure rather than a ``Fn`` closure, and made its
130 implementation use internal iteration for better performance
131 ; by `@danielhenrymantilla <https://github.com/danielhenrymantilla>`_
132
133 - Added convenience methods to
134 `EitherOrBoth <https://docs.rs/itertools/0.8.1/itertools/enum.EitherOrBoth.html>`_ elements yielded from the
135 `.zip_longest() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.zip_longest>`_ iterator adaptor
136 ; by `@Avi-D-coder <https://github.com/Avi-D-coder>`_
137
138 - Added `.sum1() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.sum1>`_
139 and `.product1() <https://docs.rs/itertools/0.8.1/itertools/trait.Itertools.html#method.product1>`_
140 iterator methods that respectively try to return the sum and the product of
141 the elements of an iterator **when it is not empty**, otherwise they return
142 ``None``
143 ; by `@Emerentius <https://github.com/Emerentius>`_
144
145- 0.8.0
146
147 - Added new adaptor ``.map_into()`` for conversions using ``Into`` by @vorner
148 - Improved ``Itertools`` docs by @JohnHeitmann
149 - The return type of ``.sorted/_by/_by_key()`` is now an iterator, not a Vec.
150 - The return type of the ``izip!(x, y)`` macro with exactly two arguments
151 is now the usual ``Iterator::zip``.
152 - Remove ``.flatten()`` in favour of std's ``.flatten()``
153 - Deprecate ``.foreach()`` in favour of std's ``.for_each()``
154 - Deprecate ``.step()`` in favour of std's ``.step_by()``
155 - Deprecate ``repeat_call`` in favour of std's ``repeat_with``
156 - Deprecate ``.fold_while()`` in favour of std's ``.try_fold()``
157 - Require Rust 1.24 as minimal version.
158
159- 0.7.11
160
161 - Add convenience methods to ``EitherOrBoth``, making it more similar to ``Option``
162 and ``Either`` by @jethrogb
163
164- 0.7.10
165
166 - No changes.
167
168- 0.7.9
169
170 - New inclusion policy: See the readme about suggesting features for std before
171 accepting them in itertools.
172 - The ``FoldWhile`` type now implements ``Eq`` and ``PartialEq`` by @jturner314
173
174- 0.7.8
175
176 - Add new iterator method ``.tree_fold1()`` which is like ``.fold1()``
177 except items are combined in a tree structure (see its docs).
178 By @scottmcm
179 - Add more ``Debug`` impls by @phimuemue: KMerge, KMergeBy, MergeJoinBy,
180 ConsTuples, Intersperse, ProcessResults, RcIter, Tee, TupleWindows, Tee,
181 ZipLongest, ZipEq, Zip.
182
183- 0.7.7
184
185 - Add new iterator method ``.into_group_map() -> HashMap<K, Vec<V>>``
186 which turns an iterator of ``(K, V)`` elements into such a hash table,
187 where values are grouped by key. By @tobz1000
188 - Add new free function ``flatten`` for the ``.flatten()`` adaptor.
189 **NOTE:** recent Rust nightlies have ``Iterator::flatten`` and thus a clash
190 with our flatten adaptor. One workaround is to use the itertools ``flatten``
191 free function.
192
193- 0.7.6
194
195 - Add new adaptor ``.multi_cartesian_product()`` which is an n-ary product
196 iterator by @tobz1000
197 - Add new method ``.sorted_by_key()`` by @Xion
198 - Provide simpler and faster ``.count()`` for ``.unique()`` and ``.unique_by()``
199
200- 0.7.5
201
202 - ``.multipeek()`` now implements ``PeekingNext``, by @nicopap.
203
204- 0.7.4
205
206 - Add new adaptor ``.update()`` by @lucasem; this adaptor is used
207 to modify an element before passing it on in an iterator chain.
208
209- 0.7.3
210
211 - Add new method ``.collect_tuple()`` by @matklad; it makes a tuple out of
212 the iterator's elements if the number of them matches **exactly**.
213 - Implement ``fold`` and ``collect`` for ``.map_results()`` which means
214 it reuses the code of the standard ``.map()`` for these methods.
215
216- 0.7.2
217
218 - Add new adaptor ``.merge_join_by`` by @srijs; a heterogeneous merge join
219 for two ordered sequences.
220
221- 0.7.1
222
223 - Iterator adaptors and iterators in itertools now use the same ``must_use``
224 reminder that the standard library adaptors do, by @matematikaedit and @bluss
225 *“iterator adaptors are lazy and do nothing unless consumed”*.
226
227- 0.7.0
228
229 - Faster ``izip!()`` by @krdln
230
231 - ``izip!()`` is now a wrapper for repeated regular ``.zip()`` and
232 a single ``.map()``. This means it optimizes as well as the standard
233 library ``.zip()`` it uses.
234 **Note:** ``multizip`` and ``izip!()`` are now different! The former
235 has a named type but the latter optimizes better.
236
237 - Faster ``.unique()``
238
239 - ``no_std`` support, which is opt-in!
240
241 - Many lovable features are still there without std, like ``izip!()``
242 or ``.format()`` or ``.merge()``, but not those that use collections.
243
244 - Trait bounds were required up front instead of just on the type:
245 ``group_by``'s ``PartialEq`` by @Phlosioneer and ``repeat_call``'s
246 ``FnMut``.
247 - Removed deprecated constructor ``Zip::new`` — use ``izip!()`` or ``multizip()``
248
249- 0.6.5
250
251 - Fix bug in ``.cartesian_product()``'s fold (which only was visible for
252 unfused iterators).
253
254- 0.6.4
255
256 - Add specific ``fold`` implementations for ``.cartesian_product()`` and
257 ``cons_tuples()``, which improves their performance in fold, foreach, and
258 iterator consumers derived from them.
259
260- 0.6.3
261
262 - Add iterator adaptor ``.positions(predicate)`` by @tmccombs
263
264- 0.6.2
265
266 - Add function ``process_results`` which can “lift” a function of the regular
267 values of an iterator so that it can process the ``Ok`` values from an
268 iterator of ``Results`` instead, by @shepmaster
269 - Add iterator method ``.concat()`` which combines all iterator elements
270 into a single collection using the ``Extend`` trait, by @srijs
271
272- 0.6.1
273
274 - Better size hint testing and subsequent size hint bugfixes by @rkarp.
275 Fixes bugs in product, interleave_shortest size hints.
276 - New iterator method ``.all_equal()`` by @phimuemue
277
278- 0.6.0
279
280 - Deprecated names were removed in favour of their replacements
281 - ``.flatten()`` does not implement double ended iteration anymore
282 - ``.fold_while()`` uses ``&mut self`` and returns ``FoldWhile<T>``, for
283 composability (#168)
284 - ``.foreach()`` and ``.fold1()`` use ``self``, like ``.fold()`` does.
285 - ``.combinations(0)`` now produces a single empty vector. (#174)
286
287- 0.5.10
288
289 - Add itertools method ``.kmerge_by()`` (and corresponding free function)
290 - Relaxed trait requirement of ``.kmerge()`` and ``.minmax()`` to PartialOrd.
291
292- 0.5.9
293
294 - Add multipeek method ``.reset_peek()``
295 - Add categories
296
297- 0.5.8
298
299 - Add iterator adaptor ``.peeking_take_while()`` and its trait ``PeekingNext``.
300
301- 0.5.7
302
303 - Add iterator adaptor ``.with_position()``
304 - Fix multipeek's performance for long peeks by using ``VecDeque``.
305
306- 0.5.6
307
308 - Add ``.map_results()``
309
310- 0.5.5
311
312 - Many more adaptors now implement ``Debug``
313 - Add free function constructor ``repeat_n``. ``RepeatN::new`` is now
314 deprecated.
315
316- 0.5.4
317
318 - Add infinite generator function ``iterate``, that takes a seed and a
319 closure.
320
321- 0.5.3
322
323 - Special-cased ``.fold()`` for flatten and put back. ``.foreach()``
324 now uses fold on the iterator, to pick up any iterator specific loop
325 implementation.
326 - ``.combinations(n)`` asserts up front that ``n != 0``, instead of
327 running into an error on the second iterator element.
328
329- 0.5.2
330
331 - Add ``.tuples::<T>()`` that iterates by two, three or four elements at
332 a time (where ``T`` is a tuple type).
333 - Add ``.tuple_windows::<T>()`` that iterates using a window of the
334 two, three or four most recent elements.
335 - Add ``.next_tuple::<T>()`` method, that picks the next two, three or four
336 elements in one go.
337 - ``.interleave()`` now has an accurate size hint.
338
339- 0.5.1
340
341 - Workaround module/function name clash that made racer crash on completing
342 itertools. Only internal changes needed.
343
344- 0.5.0
345
346 - `Release announcement <http://bluss.github.io/rust/2016/09/26/itertools-0.5.0/>`_
347 - Renamed:
348
349 - combinations is now tuple_combinations
350 - combinations_n to combinations
351 - group_by_lazy, chunks_lazy to group_by, chunks
352 - Unfold::new to unfold()
353 - RepeatCall::new to repeat_call()
354 - Zip::new to multizip
355 - PutBack::new, PutBackN::new to put_back, put_back_n
356 - PutBack::with_value is now a builder setter, not a constructor
357 - MultiPeek::new, .multipeek() to multipeek()
358 - format to format_with and format_default to format
359 - .into_rc() to rciter
360 - ``Partition`` enum is now ``Either``
361
362 - Module reorganization:
363
364 - All iterator structs are under ``itertools::structs`` but also
365 reexported to the top level, for backwards compatibility
366 - All free functions are reexported at the root, ``itertools::free`` will
367 be removed in the next version
368
369 - Removed:
370
371 - ZipSlices, use .zip() instead
372 - .enumerate_from(), ZipTrusted, due to being unstable
373 - .mend_slices(), moved to crate odds
374 - Stride, StrideMut, moved to crate odds
375 - linspace(), moved to crate itertools-num
376 - .sort_by(), use .sorted_by()
377 - .is_empty_hint(), use .size_hint()
378 - .dropn(), use .dropping()
379 - .map_fn(), use .map()
380 - .slice(), use .take() / .skip()
381 - helper traits in misc
382 - ``new`` constructors on iterator structs, use Itertools trait or free
383 functions instead
384 - ``itertools::size_hint`` is now private
385
386 - Behaviour changes:
387
388 - format and format_with helpers now panic if you try to format them more
389 than once.
390 - ``repeat_call`` is not double ended anymore
391
392 - New features:
393
394 - tuple flattening iterator is constructible with ``cons_tuples``
395 - itertools reexports ``Either`` from the ``either`` crate. ``Either<L, R>``
396 is an iterator when ``L, R`` are.
397 - ``MinMaxResult`` now implements Copy and Clone
398 - tuple_combinations supports 1-4 tuples of combinations (previously just 2)
399
400- 0.4.19
401
402 - Add ``.minmax_by()``
403 - Add ``itertools::free::cloned``
404 - Add ``itertools::free::rciter``
405 - Improve ``.step(n)`` slightly to take advantage of specialized Fuse better.
406
407- 0.4.18
408
409 - Only changes related to the "unstable" crate feature. This feature is more
410 or less deprecated.
411
412 - Use deprecated warnings when unstable is enabled. .enumerate_from() will
413 be removed imminently since it's using a deprecated libstd trait.
414
415- 0.4.17
416
417 - Fix bug in .kmerge() that caused it to often produce the wrong order (#134)
418
419- 0.4.16
420
421 - Improve precision of the interleave_shortest adaptor's size hint (it is
422 now computed exactly when possible).
423
424- 0.4.15
425
426 - Fixup on top of the workaround in 0.4.14. A function in itertools::free was
427 removed by mistake and now it is added back again.
428
429- 0.4.14
430
431 - Workaround an upstream regression in a rust nightly build that broke
432 compilation of of itertools::free::{interleave, merge}
433
434- 0.4.13
435
436 - Add .minmax() and .minmax_by_key(), iterator methods for finding both minimum
437 and maximum in one scan.
438 - Add .format_default(), a simpler version of .format() (lazy formatting
439 for iterators).
440
441- 0.4.12
442
443 - Add .zip_eq(), an adaptor like .zip() except it ensures iterators
444 of inequal length don't pass silently (instead it panics).
445 - Add .fold_while(), an iterator method that is a fold that
446 can short-circuit.
447 - Add .partition_map(), an iterator method that can separate elements
448 into two collections.
449
450- 0.4.11
451
452 - Add .get() for Stride{,Mut} and .get_mut() for StrideMut
453
454- 0.4.10
455
456 - Improve performance of .kmerge()
457
458- 0.4.9
459
460 - Add k-ary merge adaptor .kmerge()
461 - Fix a bug in .islice() with ranges a..b where a > b.
462
463- 0.4.8
464
465 - Implement Clone, Debug for Linspace
466
467- 0.4.7
468
469 - Add function diff_with() that compares two iterators
470 - Add .combinations_n(), an n-ary combinations iterator
471 - Add methods PutBack::with_value and PutBack::into_parts.
472
473- 0.4.6
474
475 - Add method .sorted()
476 - Add module ``itertools::free`` with free function variants of common
477 iterator adaptors and methods.
478 For example ``enumerate(iterable)``, ``rev(iterable)``, and so on.
479
480- 0.4.5
481
482 - Add .flatten()
483
484- 0.4.4
485
486 - Allow composing ZipSlices with itself
487
488- 0.4.3
489
490 - Write iproduct!() as a single expression; this allows temporary values
491 in its arguments.
492
493- 0.4.2
494
495 - Add .fold_options()
496 - Require Rust 1.1 or later
497
498- 0.4.1
499
500 - Update .dropping() to take advantage of .nth()
501
502- 0.4.0
503
504 - .merge(), .unique() and .dedup() now perform better due to not using
505 function pointers
506 - Add free functions enumerate() and rev()
507 - Breaking changes:
508
509 - Return types of .merge() and .merge_by() renamed and changed
510 - Method Merge::new removed
511 - .merge_by() now takes a closure that returns bool.
512 - Return type of .dedup() changed
513 - Return type of .mend_slices() changed
514 - Return type of .unique() changed
515 - Removed function times(), struct Times: use a range instead
516 - Removed deprecated macro icompr!()
517 - Removed deprecated FnMap and method .fn_map(): use .map_fn()
518 - .interleave_shortest() is no longer guaranteed to act like fused
519
520- 0.3.25
521
522 - Rename .sort_by() to .sorted_by(). Old name is deprecated.
523 - Fix well-formedness warnings from RFC 1214, no user visible impact
524
525- 0.3.24
526
527 - Improve performance of .merge()'s ordering function slightly
528
529- 0.3.23
530
531 - Added .chunks(), similar to (and based on) .group_by_lazy().
532 - Tweak linspace to match numpy.linspace and make it double ended.
533
534- 0.3.22
535
536 - Added ZipSlices, a fast zip for slices
537
538- 0.3.21
539
540 - Remove `Debug` impl for `Format`, it will have different use later
541
542- 0.3.20
543
544 - Optimize .group_by_lazy()
545
546- 0.3.19
547
548 - Added .group_by_lazy(), a possibly nonallocating group by
549 - Added .format(), a nonallocating formatting helper for iterators
550 - Remove uses of RandomAccessIterator since it has been deprecated in rust.
551
552- 0.3.17
553
554 - Added (adopted) Unfold from rust
555
556- 0.3.16
557
558 - Added adaptors .unique(), .unique_by()
559
560- 0.3.15
561
562 - Added method .sort_by()
563
564- 0.3.14
565
566 - Added adaptor .while_some()
567
568- 0.3.13
569
570 - Added adaptor .interleave_shortest()
571 - Added adaptor .pad_using()
572
573- 0.3.11
574
575 - Added assert_equal function
576
577- 0.3.10
578
579 - Bugfix .combinations() size_hint.
580
581- 0.3.8
582
583 - Added source RepeatCall
584
585- 0.3.7
586
587 - Added adaptor PutBackN
588 - Added adaptor .combinations()
589
590- 0.3.6
591
592 - Added itertools::partition, partition a sequence in place based on a predicate.
593 - Deprecate icompr!() with no replacement.
594
595- 0.3.5
596
597 - .map_fn() replaces deprecated .fn_map().
598
599- 0.3.4
600
601 - .take_while_ref() *by-ref adaptor*
602 - .coalesce() *adaptor*
603 - .mend_slices() *adaptor*
604
605- 0.3.3
606
607 - .dropping_back() *method*
608 - .fold1() *method*
609 - .is_empty_hint() *method*
610
611License
612-------
613
614Dual-licensed to be compatible with the Rust project.
615
616Licensed under the Apache License, Version 2.0
617http://www.apache.org/licenses/LICENSE-2.0 or the MIT license
618http://opensource.org/licenses/MIT, at your
619option. This file may not be copied, modified, or distributed
620except according to those terms.
621
