vendor/itertools-0.8.2/README.rst

   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/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
  19 How to use with cargo:
  20
  21 .. code:: toml
  22
  23     [dependencies]
  24     itertools = "0.8"
  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
  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
  41 For new features, please first consider filing a PR to `rust-lang/rust <https://github.com/rust-lang/rust/>`_,
  42 adding your new feature to the `Iterator` trait of the standard library, if you believe it is reasonable.
  43 If it isn't accepted there, proposing it for inclusion in ``itertools`` is a good idea.
  44 The reason for doing is this is so that we avoid future breakage as with ``.flatten()``.
  45 However, if your feature involves heap allocation, such as storing elements in a ``Vec<T>``,
  46 then it can't be accepted into ``libcore``, and you should propose it for ``itertools`` directly instead.
  47
  48 Recent 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
 611 License
 612 -------
 613
 614 Dual-licensed to be compatible with the Rust project.
 615
 616 Licensed under the Apache License, Version 2.0
 617 http://www.apache.org/licenses/LICENSE-2.0 or the MIT license
 618 http://opensource.org/licenses/MIT, at your
 619 option. This file may not be copied, modified, or distributed
 620 except according to those terms.