vendor/itertools-0.7.8/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/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.