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