1 //! Traits for writing parallel programs using an iterator-style interface
3 //! You will rarely need to interact with this module directly unless you have
4 //! need to name one of the iterator types.
6 //! Parallel iterators make it easy to write iterator-like chains that
7 //! execute in parallel: typically all you have to do is convert the
8 //! first `.iter()` (or `iter_mut()`, `into_iter()`, etc) method into
9 //! `par_iter()` (or `par_iter_mut()`, `into_par_iter()`, etc). For
10 //! example, to compute the sum of the squares of a sequence of
11 //! integers, one might write:
14 //! use rayon::prelude::*;
15 //! fn sum_of_squares(input: &[i32]) -> i32 {
22 //! Or, to increment all the integers in a slice, you could write:
25 //! use rayon::prelude::*;
26 //! fn increment_all(input: &mut [i32]) {
27 //! input.par_iter_mut()
28 //! .for_each(|p| *p += 1);
32 //! To use parallel iterators, first import the traits by adding
33 //! something like `use rayon::prelude::*` to your module. You can
34 //! then call `par_iter`, `par_iter_mut`, or `into_par_iter` to get a
35 //! parallel iterator. Like a [regular iterator][], parallel
36 //! iterators work by first constructing a computation and then
39 //! In addition to `par_iter()` and friends, some types offer other
40 //! ways to create (or consume) parallel iterators:
42 //! - Slices (`&[T]`, `&mut [T]`) offer methods like `par_split` and
43 //! `par_windows`, as well as various parallel sorting
44 //! operations. See [the `ParallelSlice` trait] for the full list.
45 //! - Strings (`&str`) offer methods like `par_split` and `par_lines`.
46 //! See [the `ParallelString` trait] for the full list.
47 //! - Various collections offer [`par_extend`], which grows a
48 //! collection given a parallel iterator. (If you don't have a
49 //! collection to extend, you can use [`collect()`] to create a new
50 //! one from scratch.)
52 //! [the `ParallelSlice` trait]: ../slice/trait.ParallelSlice.html
53 //! [the `ParallelString` trait]: ../str/trait.ParallelString.html
54 //! [`par_extend`]: trait.ParallelExtend.html
55 //! [`collect()`]: trait.ParallelIterator.html#method.collect
57 //! To see the full range of methods available on parallel iterators,
58 //! check out the [`ParallelIterator`] and [`IndexedParallelIterator`]
61 //! If you'd like to build a custom parallel iterator, or to write your own
62 //! combinator, then check out the [split] function and the [plumbing] module.
64 //! [regular iterator]: http://doc.rust-lang.org/std/iter/trait.Iterator.html
65 //! [`ParallelIterator`]: trait.ParallelIterator.html
66 //! [`IndexedParallelIterator`]: trait.IndexedParallelIterator.html
67 //! [split]: fn.split.html
68 //! [plumbing]: plumbing/index.html
70 //! Note: Several of the `ParallelIterator` methods rely on a `Try` trait which
71 //! has been deliberately obscured from the public API. This trait is intended
72 //! to mirror the unstable `std::ops::Try` with implementations for `Option` and
73 //! `Result`, where `Some`/`Ok` values will let those iterators continue, but
74 //! `None`/`Err` values will exit early.
76 use self::plumbing
::*;
77 use self::private
::Try
;
78 pub use either
::Either
;
79 use std
::cmp
::{self, Ordering}
;
80 use std
::iter
::{Product, Sum}
;
83 // There is a method to the madness here:
85 // - Most of these modules are private but expose certain types to the end-user
86 // (e.g., `enumerate::Enumerate`) -- specifically, the types that appear in the
87 // public API surface of the `ParallelIterator` traits.
88 // - In **this** module, those public types are always used unprefixed, which forces
89 // us to add a `pub use` and helps identify if we missed anything.
90 // - In contrast, items that appear **only** in the body of a method,
91 // e.g. `find::find()`, are always used **prefixed**, so that they
92 // can be readily distinguished.
95 pub use self::par_bridge
::{IterBridge, ParallelBridge}
;
100 pub use self::chain
::Chain
;
102 pub use self::chunks
::Chunks
;
105 pub use self::enumerate
::Enumerate
;
107 pub use self::filter
::Filter
;
109 pub use self::filter_map
::FilterMap
;
111 pub use self::flat_map
::FlatMap
;
113 pub use self::flatten
::Flatten
;
118 pub use self::fold
::{Fold, FoldWith}
;
120 pub use self::try_fold
::{TryFold, TryFoldWith}
;
125 pub use self::skip
::Skip
;
127 pub use self::splitter
::{split, Split}
;
129 pub use self::take
::Take
;
131 pub use self::map
::Map
;
133 pub use self::map_with
::{MapInit, MapWith}
;
135 pub use self::zip
::Zip
;
137 pub use self::zip_eq
::ZipEq
;
139 pub use self::interleave
::Interleave
;
140 mod interleave_shortest
;
141 pub use self::interleave_shortest
::InterleaveShortest
;
143 pub use self::intersperse
::Intersperse
;
145 pub use self::update
::Update
;
149 pub use self::rev
::Rev
;
151 pub use self::len
::{MaxLen, MinLen}
;
155 pub use self::cloned
::Cloned
;
157 pub use self::inspect
::Inspect
;
159 pub use self::while_some
::WhileSome
;
163 pub use self::repeat
::{repeat, Repeat}
;
164 pub use self::repeat
::{repeatn, RepeatN}
;
167 pub use self::empty
::{empty, Empty}
;
169 pub use self::once
::{once, Once}
;
174 /// `IntoParallelIterator` implements the conversion to a [`ParallelIterator`].
176 /// By implementing `IntoParallelIterator` for a type, you define how it will
177 /// transformed into an iterator. This is a parallel version of the standard
178 /// library's [`std::iter::IntoIterator`] trait.
180 /// [`ParallelIterator`]: trait.ParallelIterator.html
181 /// [`std::iter::IntoIterator`]: https://doc.rust-lang.org/std/iter/trait.IntoIterator.html
182 pub trait IntoParallelIterator
{
183 /// The parallel iterator type that will be created.
184 type Iter
: ParallelIterator
<Item
= Self::Item
>;
186 /// The type of item that the parallel iterator will produce.
189 /// Converts `self` into a parallel iterator.
194 /// use rayon::prelude::*;
196 /// println!("counting in parallel:");
197 /// (0..100).into_par_iter()
198 /// .for_each(|i| println!("{}", i));
201 /// This conversion is often implicit for arguments to methods like [`zip`].
204 /// use rayon::prelude::*;
206 /// let v: Vec<_> = (0..5).into_par_iter().zip(5..10).collect();
207 /// assert_eq!(v, [(0, 5), (1, 6), (2, 7), (3, 8), (4, 9)]);
210 /// [`zip`]: trait.IndexedParallelIterator.html#method.zip
211 fn into_par_iter(self) -> Self::Iter
;
214 /// `IntoParallelRefIterator` implements the conversion to a
215 /// [`ParallelIterator`], providing shared references to the data.
217 /// This is a parallel version of the `iter()` method
218 /// defined by various collections.
220 /// This trait is automatically implemented
221 /// `for I where &I: IntoParallelIterator`. In most cases, users
222 /// will want to implement [`IntoParallelIterator`] rather than implement
223 /// this trait directly.
225 /// [`ParallelIterator`]: trait.ParallelIterator.html
226 /// [`IntoParallelIterator`]: trait.IntoParallelIterator.html
227 pub trait IntoParallelRefIterator
<'data
> {
228 /// The type of the parallel iterator that will be returned.
229 type Iter
: ParallelIterator
<Item
= Self::Item
>;
231 /// The type of item that the parallel iterator will produce.
232 /// This will typically be an `&'data T` reference type.
233 type Item
: Send
+ 'data
;
235 /// Converts `self` into a parallel iterator.
240 /// use rayon::prelude::*;
242 /// let v: Vec<_> = (0..100).collect();
243 /// assert_eq!(v.par_iter().sum::<i32>(), 100 * 99 / 2);
245 /// // `v.par_iter()` is shorthand for `(&v).into_par_iter()`,
246 /// // producing the exact same references.
247 /// assert!(v.par_iter().zip(&v)
248 /// .all(|(a, b)| std::ptr::eq(a, b)));
250 fn par_iter(&'data
self) -> Self::Iter
;
253 impl<'data
, I
: 'data
+ ?Sized
> IntoParallelRefIterator
<'data
> for I
255 &'data I
: IntoParallelIterator
,
257 type Iter
= <&'data I
as IntoParallelIterator
>::Iter
;
258 type Item
= <&'data I
as IntoParallelIterator
>::Item
;
260 fn par_iter(&'data
self) -> Self::Iter
{
265 /// `IntoParallelRefMutIterator` implements the conversion to a
266 /// [`ParallelIterator`], providing mutable references to the data.
268 /// This is a parallel version of the `iter_mut()` method
269 /// defined by various collections.
271 /// This trait is automatically implemented
272 /// `for I where &mut I: IntoParallelIterator`. In most cases, users
273 /// will want to implement [`IntoParallelIterator`] rather than implement
274 /// this trait directly.
276 /// [`ParallelIterator`]: trait.ParallelIterator.html
277 /// [`IntoParallelIterator`]: trait.IntoParallelIterator.html
278 pub trait IntoParallelRefMutIterator
<'data
> {
279 /// The type of iterator that will be created.
280 type Iter
: ParallelIterator
<Item
= Self::Item
>;
282 /// The type of item that will be produced; this is typically an
283 /// `&'data mut T` reference.
284 type Item
: Send
+ 'data
;
286 /// Creates the parallel iterator from `self`.
291 /// use rayon::prelude::*;
293 /// let mut v = vec![0usize; 5];
294 /// v.par_iter_mut().enumerate().for_each(|(i, x)| *x = i);
295 /// assert_eq!(v, [0, 1, 2, 3, 4]);
297 fn par_iter_mut(&'data
mut self) -> Self::Iter
;
300 impl<'data
, I
: 'data
+ ?Sized
> IntoParallelRefMutIterator
<'data
> for I
302 &'data
mut I
: IntoParallelIterator
,
304 type Iter
= <&'data
mut I
as IntoParallelIterator
>::Iter
;
305 type Item
= <&'data
mut I
as IntoParallelIterator
>::Item
;
307 fn par_iter_mut(&'data
mut self) -> Self::Iter
{
312 /// Parallel version of the standard iterator trait.
314 /// The combinators on this trait are available on **all** parallel
315 /// iterators. Additional methods can be found on the
316 /// [`IndexedParallelIterator`] trait: those methods are only
317 /// available for parallel iterators where the number of items is
318 /// known in advance (so, e.g., after invoking `filter`, those methods
319 /// become unavailable).
321 /// For examples of using parallel iterators, see [the docs on the
322 /// `iter` module][iter].
324 /// [iter]: index.html
325 /// [`IndexedParallelIterator`]: trait.IndexedParallelIterator.html
326 pub trait ParallelIterator
: Sized
+ Send
{
327 /// The type of item that this parallel iterator produces.
328 /// For example, if you use the [`for_each`] method, this is the type of
329 /// item that your closure will be invoked with.
331 /// [`for_each`]: #method.for_each
334 /// Executes `OP` on each item produced by the iterator, in parallel.
339 /// use rayon::prelude::*;
341 /// (0..100).into_par_iter().for_each(|x| println!("{:?}", x));
343 fn for_each
<OP
>(self, op
: OP
)
345 OP
: Fn(Self::Item
) + Sync
+ Send
,
347 for_each
::for_each(self, &op
)
350 /// Executes `OP` on the given `init` value with each item produced by
351 /// the iterator, in parallel.
353 /// The `init` value will be cloned only as needed to be paired with
354 /// the group of items in each rayon job. It does not require the type
360 /// use std::sync::mpsc::channel;
361 /// use rayon::prelude::*;
363 /// let (sender, receiver) = channel();
365 /// (0..5).into_par_iter().for_each_with(sender, |s, x| s.send(x).unwrap());
367 /// let mut res: Vec<_> = receiver.iter().collect();
371 /// assert_eq!(&res[..], &[0, 1, 2, 3, 4])
373 fn for_each_with
<OP
, T
>(self, init
: T
, op
: OP
)
375 OP
: Fn(&mut T
, Self::Item
) + Sync
+ Send
,
378 self.map_with(init
, op
).for_each(|()| ())
381 /// Executes `OP` on a value returned by `init` with each item produced by
382 /// the iterator, in parallel.
384 /// The `init` function will be called only as needed for a value to be
385 /// paired with the group of items in each rayon job. There is no
386 /// constraint on that returned type at all!
391 /// extern crate rand;
392 /// extern crate rayon;
395 /// use rayon::prelude::*;
397 /// let mut v = vec![0u8; 1_000_000];
399 /// v.par_chunks_mut(1000)
401 /// || rand::thread_rng(),
402 /// |rng, chunk| rng.fill(chunk),
405 /// // There's a remote chance that this will fail...
406 /// for i in 0u8..=255 {
407 /// assert!(v.contains(&i));
410 fn for_each_init
<OP
, INIT
, T
>(self, init
: INIT
, op
: OP
)
412 OP
: Fn(&mut T
, Self::Item
) + Sync
+ Send
,
413 INIT
: Fn() -> T
+ Sync
+ Send
,
415 self.map_init(init
, op
).for_each(|()| ())
418 /// Executes a fallible `OP` on each item produced by the iterator, in parallel.
420 /// If the `OP` returns `Result::Err` or `Option::None`, we will attempt to
421 /// stop processing the rest of the items in the iterator as soon as
422 /// possible, and we will return that terminating value. Otherwise, we will
423 /// return an empty `Result::Ok(())` or `Option::Some(())`. If there are
424 /// multiple errors in parallel, it is not specified which will be returned.
429 /// use rayon::prelude::*;
430 /// use std::io::{self, Write};
432 /// // This will stop iteration early if there's any write error, like
433 /// // having piped output get closed on the other end.
434 /// (0..100).into_par_iter()
435 /// .try_for_each(|x| writeln!(io::stdout(), "{:?}", x))
436 /// .expect("expected no write errors");
438 fn try_for_each
<OP
, R
>(self, op
: OP
) -> R
440 OP
: Fn(Self::Item
) -> R
+ Sync
+ Send
,
441 R
: Try
<Ok
= ()> + Send
,
443 self.map(op
).try_reduce(|| (), |(), ()| R
::from_ok(()))
446 /// Executes a fallible `OP` on the given `init` value with each item
447 /// produced by the iterator, in parallel.
449 /// This combines the `init` semantics of [`for_each_with()`] and the
450 /// failure semantics of [`try_for_each()`].
452 /// [`for_each_with()`]: #method.for_each_with
453 /// [`try_for_each()`]: #method.try_for_each
458 /// use std::sync::mpsc::channel;
459 /// use rayon::prelude::*;
461 /// let (sender, receiver) = channel();
463 /// (0..5).into_par_iter()
464 /// .try_for_each_with(sender, |s, x| s.send(x))
465 /// .expect("expected no send errors");
467 /// let mut res: Vec<_> = receiver.iter().collect();
471 /// assert_eq!(&res[..], &[0, 1, 2, 3, 4])
473 fn try_for_each_with
<OP
, T
, R
>(self, init
: T
, op
: OP
) -> R
475 OP
: Fn(&mut T
, Self::Item
) -> R
+ Sync
+ Send
,
477 R
: Try
<Ok
= ()> + Send
,
479 self.map_with(init
, op
)
480 .try_reduce(|| (), |(), ()| R
::from_ok(()))
483 /// Executes a fallible `OP` on a value returned by `init` with each item
484 /// produced by the iterator, in parallel.
486 /// This combines the `init` semantics of [`for_each_init()`] and the
487 /// failure semantics of [`try_for_each()`].
489 /// [`for_each_init()`]: #method.for_each_init
490 /// [`try_for_each()`]: #method.try_for_each
495 /// extern crate rand;
496 /// extern crate rayon;
499 /// use rayon::prelude::*;
501 /// let mut v = vec![0u8; 1_000_000];
503 /// v.par_chunks_mut(1000)
504 /// .try_for_each_init(
505 /// || rand::thread_rng(),
506 /// |rng, chunk| rng.try_fill(chunk),
508 /// .expect("expected no rand errors");
510 /// // There's a remote chance that this will fail...
511 /// for i in 0u8..=255 {
512 /// assert!(v.contains(&i));
515 fn try_for_each_init
<OP
, INIT
, T
, R
>(self, init
: INIT
, op
: OP
) -> R
517 OP
: Fn(&mut T
, Self::Item
) -> R
+ Sync
+ Send
,
518 INIT
: Fn() -> T
+ Sync
+ Send
,
519 R
: Try
<Ok
= ()> + Send
,
521 self.map_init(init
, op
)
522 .try_reduce(|| (), |(), ()| R
::from_ok(()))
525 /// Counts the number of items in this parallel iterator.
530 /// use rayon::prelude::*;
532 /// let count = (0..100).into_par_iter().count();
534 /// assert_eq!(count, 100);
536 fn count(self) -> usize {
537 self.map(|_
| 1).sum()
540 /// Applies `map_op` to each item of this iterator, producing a new
541 /// iterator with the results.
546 /// use rayon::prelude::*;
548 /// let mut par_iter = (0..5).into_par_iter().map(|x| x * 2);
550 /// let doubles: Vec<_> = par_iter.collect();
552 /// assert_eq!(&doubles[..], &[0, 2, 4, 6, 8]);
554 fn map
<F
, R
>(self, map_op
: F
) -> Map
<Self, F
>
556 F
: Fn(Self::Item
) -> R
+ Sync
+ Send
,
559 map
::new(self, map_op
)
562 /// Applies `map_op` to the given `init` value with each item of this
563 /// iterator, producing a new iterator with the results.
565 /// The `init` value will be cloned only as needed to be paired with
566 /// the group of items in each rayon job. It does not require the type
572 /// use std::sync::mpsc::channel;
573 /// use rayon::prelude::*;
575 /// let (sender, receiver) = channel();
577 /// let a: Vec<_> = (0..5)
578 /// .into_par_iter() // iterating over i32
579 /// .map_with(sender, |s, x| {
580 /// s.send(x).unwrap(); // sending i32 values through the channel
581 /// x // returning i32
583 /// .collect(); // collecting the returned values into a vector
585 /// let mut b: Vec<_> = receiver.iter() // iterating over the values in the channel
586 /// .collect(); // and collecting them
589 /// assert_eq!(a, b);
591 fn map_with
<F
, T
, R
>(self, init
: T
, map_op
: F
) -> MapWith
<Self, T
, F
>
593 F
: Fn(&mut T
, Self::Item
) -> R
+ Sync
+ Send
,
597 map_with
::new(self, init
, map_op
)
600 /// Applies `map_op` to a value returned by `init` with each item of this
601 /// iterator, producing a new iterator with the results.
603 /// The `init` function will be called only as needed for a value to be
604 /// paired with the group of items in each rayon job. There is no
605 /// constraint on that returned type at all!
610 /// extern crate rand;
611 /// extern crate rayon;
614 /// use rayon::prelude::*;
616 /// let a: Vec<_> = (1i32..1_000_000)
619 /// || rand::thread_rng(), // get the thread-local RNG
620 /// |rng, x| if rng.gen() { // randomly negate items
627 /// // There's a remote chance that this will fail...
628 /// assert!(a.iter().any(|&x| x < 0));
629 /// assert!(a.iter().any(|&x| x > 0));
631 fn map_init
<F
, INIT
, T
, R
>(self, init
: INIT
, map_op
: F
) -> MapInit
<Self, INIT
, F
>
633 F
: Fn(&mut T
, Self::Item
) -> R
+ Sync
+ Send
,
634 INIT
: Fn() -> T
+ Sync
+ Send
,
637 map_with
::new_init(self, init
, map_op
)
640 /// Creates an iterator which clones all of its elements. This may be
641 /// useful when you have an iterator over `&T`, but you need `T`.
646 /// use rayon::prelude::*;
648 /// let a = [1, 2, 3];
650 /// let v_cloned: Vec<_> = a.par_iter().cloned().collect();
652 /// // cloned is the same as .map(|&x| x), for integers
653 /// let v_map: Vec<_> = a.par_iter().map(|&x| x).collect();
655 /// assert_eq!(v_cloned, vec![1, 2, 3]);
656 /// assert_eq!(v_map, vec![1, 2, 3]);
658 fn cloned
<'a
, T
>(self) -> Cloned
<Self>
660 T
: 'a
+ Clone
+ Send
,
661 Self: ParallelIterator
<Item
= &'a T
>,
666 /// Applies `inspect_op` to a reference to each item of this iterator,
667 /// producing a new iterator passing through the original items. This is
668 /// often useful for debugging to see what's happening in iterator stages.
673 /// use rayon::prelude::*;
675 /// let a = [1, 4, 2, 3];
677 /// // this iterator sequence is complex.
678 /// let sum = a.par_iter()
680 /// .filter(|&x| x % 2 == 0)
681 /// .reduce(|| 0, |sum, i| sum + i);
683 /// println!("{}", sum);
685 /// // let's add some inspect() calls to investigate what's happening
686 /// let sum = a.par_iter()
688 /// .inspect(|x| println!("about to filter: {}", x))
689 /// .filter(|&x| x % 2 == 0)
690 /// .inspect(|x| println!("made it through filter: {}", x))
691 /// .reduce(|| 0, |sum, i| sum + i);
693 /// println!("{}", sum);
695 fn inspect
<OP
>(self, inspect_op
: OP
) -> Inspect
<Self, OP
>
697 OP
: Fn(&Self::Item
) + Sync
+ Send
,
699 inspect
::new(self, inspect_op
)
702 /// Mutates each item of this iterator before yielding it.
707 /// use rayon::prelude::*;
709 /// let par_iter = (0..5).into_par_iter().update(|x| {*x *= 2;});
711 /// let doubles: Vec<_> = par_iter.collect();
713 /// assert_eq!(&doubles[..], &[0, 2, 4, 6, 8]);
715 fn update
<F
>(self, update_op
: F
) -> Update
<Self, F
>
717 F
: Fn(&mut Self::Item
) + Sync
+ Send
,
719 update
::new(self, update_op
)
722 /// Applies `filter_op` to each item of this iterator, producing a new
723 /// iterator with only the items that gave `true` results.
728 /// use rayon::prelude::*;
730 /// let mut par_iter = (0..10).into_par_iter().filter(|x| x % 2 == 0);
732 /// let even_numbers: Vec<_> = par_iter.collect();
734 /// assert_eq!(&even_numbers[..], &[0, 2, 4, 6, 8]);
736 fn filter
<P
>(self, filter_op
: P
) -> Filter
<Self, P
>
738 P
: Fn(&Self::Item
) -> bool
+ Sync
+ Send
,
740 filter
::new(self, filter_op
)
743 /// Applies `filter_op` to each item of this iterator to get an `Option`,
744 /// producing a new iterator with only the items from `Some` results.
749 /// use rayon::prelude::*;
751 /// let mut par_iter = (0..10).into_par_iter()
752 /// .filter_map(|x| {
753 /// if x % 2 == 0 { Some(x * 3) }
757 /// let even_numbers: Vec<_> = par_iter.collect();
759 /// assert_eq!(&even_numbers[..], &[0, 6, 12, 18, 24]);
761 fn filter_map
<P
, R
>(self, filter_op
: P
) -> FilterMap
<Self, P
>
763 P
: Fn(Self::Item
) -> Option
<R
> + Sync
+ Send
,
766 filter_map
::new(self, filter_op
)
769 /// Applies `map_op` to each item of this iterator to get nested iterators,
770 /// producing a new iterator that flattens these back into one.
775 /// use rayon::prelude::*;
777 /// let a = [[1, 2], [3, 4], [5, 6], [7, 8]];
779 /// let par_iter = a.par_iter().cloned().flat_map(|a| a.to_vec());
781 /// let vec: Vec<_> = par_iter.collect();
783 /// assert_eq!(&vec[..], &[1, 2, 3, 4, 5, 6, 7, 8]);
785 fn flat_map
<F
, PI
>(self, map_op
: F
) -> FlatMap
<Self, F
>
787 F
: Fn(Self::Item
) -> PI
+ Sync
+ Send
,
788 PI
: IntoParallelIterator
,
790 flat_map
::new(self, map_op
)
793 /// An adaptor that flattens iterable `Item`s into one large iterator
798 /// use rayon::prelude::*;
800 /// let x: Vec<Vec<_>> = vec![vec![1, 2], vec![3, 4]];
801 /// let y: Vec<_> = x.into_par_iter().flatten().collect();
803 /// assert_eq!(y, vec![1, 2, 3, 4]);
805 fn flatten(self) -> Flatten
<Self>
807 Self::Item
: IntoParallelIterator
,
812 /// Reduces the items in the iterator into one item using `op`.
813 /// The argument `identity` should be a closure that can produce
814 /// "identity" value which may be inserted into the sequence as
815 /// needed to create opportunities for parallel execution. So, for
816 /// example, if you are doing a summation, then `identity()` ought
817 /// to produce something that represents the zero for your type
818 /// (but consider just calling `sum()` in that case).
823 /// // Iterate over a sequence of pairs `(x0, y0), ..., (xN, yN)`
824 /// // and use reduce to compute one pair `(x0 + ... + xN, y0 + ... + yN)`
825 /// // where the first/second elements are summed separately.
826 /// use rayon::prelude::*;
827 /// let sums = [(0, 1), (5, 6), (16, 2), (8, 9)]
828 /// .par_iter() // iterating over &(i32, i32)
829 /// .cloned() // iterating over (i32, i32)
830 /// .reduce(|| (0, 0), // the "identity" is 0 in both columns
831 /// |a, b| (a.0 + b.0, a.1 + b.1));
832 /// assert_eq!(sums, (0 + 5 + 16 + 8, 1 + 6 + 2 + 9));
835 /// **Note:** unlike a sequential `fold` operation, the order in
836 /// which `op` will be applied to reduce the result is not fully
837 /// specified. So `op` should be [associative] or else the results
838 /// will be non-deterministic. And of course `identity()` should
839 /// produce a true identity.
841 /// [associative]: https://en.wikipedia.org/wiki/Associative_property
842 fn reduce
<OP
, ID
>(self, identity
: ID
, op
: OP
) -> Self::Item
844 OP
: Fn(Self::Item
, Self::Item
) -> Self::Item
+ Sync
+ Send
,
845 ID
: Fn() -> Self::Item
+ Sync
+ Send
,
847 reduce
::reduce(self, identity
, op
)
850 /// Reduces the items in the iterator into one item using `op`.
851 /// If the iterator is empty, `None` is returned; otherwise,
852 /// `Some` is returned.
854 /// This version of `reduce` is simple but somewhat less
855 /// efficient. If possible, it is better to call `reduce()`, which
856 /// requires an identity element.
861 /// use rayon::prelude::*;
862 /// let sums = [(0, 1), (5, 6), (16, 2), (8, 9)]
863 /// .par_iter() // iterating over &(i32, i32)
864 /// .cloned() // iterating over (i32, i32)
865 /// .reduce_with(|a, b| (a.0 + b.0, a.1 + b.1))
867 /// assert_eq!(sums, (0 + 5 + 16 + 8, 1 + 6 + 2 + 9));
870 /// **Note:** unlike a sequential `fold` operation, the order in
871 /// which `op` will be applied to reduce the result is not fully
872 /// specified. So `op` should be [associative] or else the results
873 /// will be non-deterministic.
875 /// [associative]: https://en.wikipedia.org/wiki/Associative_property
876 fn reduce_with
<OP
>(self, op
: OP
) -> Option
<Self::Item
>
878 OP
: Fn(Self::Item
, Self::Item
) -> Self::Item
+ Sync
+ Send
,
882 |opt_a
, b
| match opt_a
{
883 Some(a
) => Some(op(a
, b
)),
889 |opt_a
, opt_b
| match (opt_a
, opt_b
) {
890 (Some(a
), Some(b
)) => Some(op(a
, b
)),
891 (Some(v
), None
) | (None
, Some(v
)) => Some(v
),
892 (None
, None
) => None
,
897 /// Reduces the items in the iterator into one item using a fallible `op`.
898 /// The `identity` argument is used the same way as in [`reduce()`].
900 /// [`reduce()`]: #method.reduce
902 /// If a `Result::Err` or `Option::None` item is found, or if `op` reduces
903 /// to one, we will attempt to stop processing the rest of the items in the
904 /// iterator as soon as possible, and we will return that terminating value.
905 /// Otherwise, we will return the final reduced `Result::Ok(T)` or
906 /// `Option::Some(T)`. If there are multiple errors in parallel, it is not
907 /// specified which will be returned.
912 /// use rayon::prelude::*;
914 /// // Compute the sum of squares, being careful about overflow.
915 /// fn sum_squares<I: IntoParallelIterator<Item = i32>>(iter: I) -> Option<i32> {
916 /// iter.into_par_iter()
917 /// .map(|i| i.checked_mul(i)) // square each item,
918 /// .try_reduce(|| 0, i32::checked_add) // and add them up!
920 /// assert_eq!(sum_squares(0..5), Some(0 + 1 + 4 + 9 + 16));
922 /// // The sum might overflow
923 /// assert_eq!(sum_squares(0..10_000), None);
925 /// // Or the squares might overflow before it even reaches `try_reduce`
926 /// assert_eq!(sum_squares(1_000_000..1_000_001), None);
928 fn try_reduce
<T
, OP
, ID
>(self, identity
: ID
, op
: OP
) -> Self::Item
930 OP
: Fn(T
, T
) -> Self::Item
+ Sync
+ Send
,
931 ID
: Fn() -> T
+ Sync
+ Send
,
932 Self::Item
: Try
<Ok
= T
>,
934 try_reduce
::try_reduce(self, identity
, op
)
937 /// Reduces the items in the iterator into one item using a fallible `op`.
939 /// Like [`reduce_with()`], if the iterator is empty, `None` is returned;
940 /// otherwise, `Some` is returned. Beyond that, it behaves like
941 /// [`try_reduce()`] for handling `Err`/`None`.
943 /// [`reduce_with()`]: #method.reduce_with
944 /// [`try_reduce()`]: #method.try_reduce
946 /// For instance, with `Option` items, the return value may be:
947 /// - `None`, the iterator was empty
948 /// - `Some(None)`, we stopped after encountering `None`.
949 /// - `Some(Some(x))`, the entire iterator reduced to `x`.
951 /// With `Result` items, the nesting is more obvious:
952 /// - `None`, the iterator was empty
953 /// - `Some(Err(e))`, we stopped after encountering an error `e`.
954 /// - `Some(Ok(x))`, the entire iterator reduced to `x`.
959 /// use rayon::prelude::*;
961 /// let files = ["/dev/null", "/does/not/exist"];
963 /// // Find the biggest file
964 /// files.into_par_iter()
965 /// .map(|path| std::fs::metadata(path).map(|m| (path, m.len())))
966 /// .try_reduce_with(|a, b| {
967 /// Ok(if a.1 >= b.1 { a } else { b })
969 /// .expect("Some value, since the iterator is not empty")
970 /// .expect_err("not found");
972 fn try_reduce_with
<T
, OP
>(self, op
: OP
) -> Option
<Self::Item
>
974 OP
: Fn(T
, T
) -> Self::Item
+ Sync
+ Send
,
975 Self::Item
: Try
<Ok
= T
>,
977 try_reduce_with
::try_reduce_with(self, op
)
980 /// Parallel fold is similar to sequential fold except that the
981 /// sequence of items may be subdivided before it is
982 /// folded. Consider a list of numbers like `22 3 77 89 46`. If
983 /// you used sequential fold to add them (`fold(0, |a,b| a+b)`,
984 /// you would wind up first adding 0 + 22, then 22 + 3, then 25 +
985 /// 77, and so forth. The **parallel fold** works similarly except
986 /// that it first breaks up your list into sublists, and hence
987 /// instead of yielding up a single sum at the end, it yields up
988 /// multiple sums. The number of results is nondeterministic, as
989 /// is the point where the breaks occur.
991 /// So if did the same parallel fold (`fold(0, |a,b| a+b)`) on
992 /// our example list, we might wind up with a sequence of two numbers,
1001 /// Or perhaps these three numbers:
1009 /// In general, Rayon will attempt to find good breaking points
1010 /// that keep all of your cores busy.
1012 /// ### Fold versus reduce
1014 /// The `fold()` and `reduce()` methods each take an identity element
1015 /// and a combining function, but they operate rather differently.
1017 /// `reduce()` requires that the identity function has the same
1018 /// type as the things you are iterating over, and it fully
1019 /// reduces the list of items into a single item. So, for example,
1020 /// imagine we are iterating over a list of bytes `bytes: [128_u8,
1021 /// 64_u8, 64_u8]`. If we used `bytes.reduce(|| 0_u8, |a: u8, b:
1022 /// u8| a + b)`, we would get an overflow. This is because `0`,
1023 /// `a`, and `b` here are all bytes, just like the numbers in the
1024 /// list (I wrote the types explicitly above, but those are the
1025 /// only types you can use). To avoid the overflow, we would need
1026 /// to do something like `bytes.map(|b| b as u32).reduce(|| 0, |a,
1027 /// b| a + b)`, in which case our result would be `256`.
1029 /// In contrast, with `fold()`, the identity function does not
1030 /// have to have the same type as the things you are iterating
1031 /// over, and you potentially get back many results. So, if we
1032 /// continue with the `bytes` example from the previous paragraph,
1033 /// we could do `bytes.fold(|| 0_u32, |a, b| a + (b as u32))` to
1034 /// convert our bytes into `u32`. And of course we might not get
1035 /// back a single sum.
1037 /// There is a more subtle distinction as well, though it's
1038 /// actually implied by the above points. When you use `reduce()`,
1039 /// your reduction function is sometimes called with values that
1040 /// were never part of your original parallel iterator (for
1041 /// example, both the left and right might be a partial sum). With
1042 /// `fold()`, in contrast, the left value in the fold function is
1043 /// always the accumulator, and the right value is always from
1044 /// your original sequence.
1046 /// ### Fold vs Map/Reduce
1048 /// Fold makes sense if you have some operation where it is
1049 /// cheaper to create groups of elements at a time. For example,
1050 /// imagine collecting characters into a string. If you were going
1051 /// to use map/reduce, you might try this:
1054 /// use rayon::prelude::*;
1057 /// ['a', 'b', 'c', 'd', 'e']
1059 /// .map(|c: &char| format!("{}", c))
1060 /// .reduce(|| String::new(),
1061 /// |mut a: String, b: String| { a.push_str(&b); a });
1063 /// assert_eq!(s, "abcde");
1066 /// Because reduce produces the same type of element as its input,
1067 /// you have to first map each character into a string, and then
1068 /// you can reduce them. This means we create one string per
1069 /// element in our iterator -- not so great. Using `fold`, we can
1070 /// do this instead:
1073 /// use rayon::prelude::*;
1076 /// ['a', 'b', 'c', 'd', 'e']
1078 /// .fold(|| String::new(),
1079 /// |mut s: String, c: &char| { s.push(*c); s })
1080 /// .reduce(|| String::new(),
1081 /// |mut a: String, b: String| { a.push_str(&b); a });
1083 /// assert_eq!(s, "abcde");
1086 /// Now `fold` will process groups of our characters at a time,
1087 /// and we only make one string per group. We should wind up with
1088 /// some small-ish number of strings roughly proportional to the
1089 /// number of CPUs you have (it will ultimately depend on how busy
1090 /// your processors are). Note that we still need to do a reduce
1091 /// afterwards to combine those groups of strings into a single
1094 /// You could use a similar trick to save partial results (e.g., a
1095 /// cache) or something similar.
1097 /// ### Combining fold with other operations
1099 /// You can combine `fold` with `reduce` if you want to produce a
1100 /// single value. This is then roughly equivalent to a map/reduce
1101 /// combination in effect:
1104 /// use rayon::prelude::*;
1106 /// let bytes = 0..22_u8;
1107 /// let sum = bytes.into_par_iter()
1108 /// .fold(|| 0_u32, |a: u32, b: u8| a + (b as u32))
1111 /// assert_eq!(sum, (0..22).sum()); // compare to sequential
1113 fn fold
<T
, ID
, F
>(self, identity
: ID
, fold_op
: F
) -> Fold
<Self, ID
, F
>
1115 F
: Fn(T
, Self::Item
) -> T
+ Sync
+ Send
,
1116 ID
: Fn() -> T
+ Sync
+ Send
,
1119 fold
::fold(self, identity
, fold_op
)
1122 /// Applies `fold_op` to the given `init` value with each item of this
1123 /// iterator, finally producing the value for further use.
1125 /// This works essentially like `fold(|| init.clone(), fold_op)`, except
1126 /// it doesn't require the `init` type to be `Sync`, nor any other form
1127 /// of added synchronization.
1132 /// use rayon::prelude::*;
1134 /// let bytes = 0..22_u8;
1135 /// let sum = bytes.into_par_iter()
1136 /// .fold_with(0_u32, |a: u32, b: u8| a + (b as u32))
1139 /// assert_eq!(sum, (0..22).sum()); // compare to sequential
1141 fn fold_with
<F
, T
>(self, init
: T
, fold_op
: F
) -> FoldWith
<Self, T
, F
>
1143 F
: Fn(T
, Self::Item
) -> T
+ Sync
+ Send
,
1146 fold
::fold_with(self, init
, fold_op
)
1149 /// Perform a fallible parallel fold.
1151 /// This is a variation of [`fold()`] for operations which can fail with
1152 /// `Option::None` or `Result::Err`. The first such failure stops
1153 /// processing the local set of items, without affecting other folds in the
1154 /// iterator's subdivisions.
1156 /// Often, `try_fold()` will be followed by [`try_reduce()`]
1157 /// for a final reduction and global short-circuiting effect.
1159 /// [`fold()`]: #method.fold
1160 /// [`try_reduce()`]: #method.try_reduce
1165 /// use rayon::prelude::*;
1167 /// let bytes = 0..22_u8;
1168 /// let sum = bytes.into_par_iter()
1169 /// .try_fold(|| 0_u32, |a: u32, b: u8| a.checked_add(b as u32))
1170 /// .try_reduce(|| 0, u32::checked_add);
1172 /// assert_eq!(sum, Some((0..22).sum())); // compare to sequential
1174 fn try_fold
<T
, R
, ID
, F
>(self, identity
: ID
, fold_op
: F
) -> TryFold
<Self, R
, ID
, F
>
1176 F
: Fn(T
, Self::Item
) -> R
+ Sync
+ Send
,
1177 ID
: Fn() -> T
+ Sync
+ Send
,
1178 R
: Try
<Ok
= T
> + Send
,
1180 try_fold
::try_fold(self, identity
, fold_op
)
1183 /// Perform a fallible parallel fold with a cloneable `init` value.
1185 /// This combines the `init` semantics of [`fold_with()`] and the failure
1186 /// semantics of [`try_fold()`].
1188 /// [`fold_with()`]: #method.fold_with
1189 /// [`try_fold()`]: #method.try_fold
1192 /// use rayon::prelude::*;
1194 /// let bytes = 0..22_u8;
1195 /// let sum = bytes.into_par_iter()
1196 /// .try_fold_with(0_u32, |a: u32, b: u8| a.checked_add(b as u32))
1197 /// .try_reduce(|| 0, u32::checked_add);
1199 /// assert_eq!(sum, Some((0..22).sum())); // compare to sequential
1201 fn try_fold_with
<F
, T
, R
>(self, init
: T
, fold_op
: F
) -> TryFoldWith
<Self, R
, F
>
1203 F
: Fn(T
, Self::Item
) -> R
+ Sync
+ Send
,
1204 R
: Try
<Ok
= T
> + Send
,
1207 try_fold
::try_fold_with(self, init
, fold_op
)
1210 /// Sums up the items in the iterator.
1212 /// Note that the order in items will be reduced is not specified,
1213 /// so if the `+` operator is not truly [associative] \(as is the
1214 /// case for floating point numbers), then the results are not
1215 /// fully deterministic.
1217 /// [associative]: https://en.wikipedia.org/wiki/Associative_property
1219 /// Basically equivalent to `self.reduce(|| 0, |a, b| a + b)`,
1220 /// except that the type of `0` and the `+` operation may vary
1221 /// depending on the type of value being produced.
1226 /// use rayon::prelude::*;
1228 /// let a = [1, 5, 7];
1230 /// let sum: i32 = a.par_iter().sum();
1232 /// assert_eq!(sum, 13);
1234 fn sum
<S
>(self) -> S
1236 S
: Send
+ Sum
<Self::Item
> + Sum
<S
>,
1241 /// Multiplies all the items in the iterator.
1243 /// Note that the order in items will be reduced is not specified,
1244 /// so if the `*` operator is not truly [associative] \(as is the
1245 /// case for floating point numbers), then the results are not
1246 /// fully deterministic.
1248 /// [associative]: https://en.wikipedia.org/wiki/Associative_property
1250 /// Basically equivalent to `self.reduce(|| 1, |a, b| a * b)`,
1251 /// except that the type of `1` and the `*` operation may vary
1252 /// depending on the type of value being produced.
1257 /// use rayon::prelude::*;
1259 /// fn factorial(n: u32) -> u32 {
1260 /// (1..n+1).into_par_iter().product()
1263 /// assert_eq!(factorial(0), 1);
1264 /// assert_eq!(factorial(1), 1);
1265 /// assert_eq!(factorial(5), 120);
1267 fn product
<P
>(self) -> P
1269 P
: Send
+ Product
<Self::Item
> + Product
<P
>,
1271 product
::product(self)
1274 /// Computes the minimum of all the items in the iterator. If the
1275 /// iterator is empty, `None` is returned; otherwise, `Some(min)`
1278 /// Note that the order in which the items will be reduced is not
1279 /// specified, so if the `Ord` impl is not truly associative, then
1280 /// the results are not deterministic.
1282 /// Basically equivalent to `self.reduce_with(|a, b| cmp::min(a, b))`.
1287 /// use rayon::prelude::*;
1289 /// let a = [45, 74, 32];
1291 /// assert_eq!(a.par_iter().min(), Some(&32));
1293 /// let b: [i32; 0] = [];
1295 /// assert_eq!(b.par_iter().min(), None);
1297 fn min(self) -> Option
<Self::Item
>
1301 self.reduce_with(cmp
::min
)
1304 /// Computes the minimum of all the items in the iterator with respect to
1305 /// the given comparison function. If the iterator is empty, `None` is
1306 /// returned; otherwise, `Some(min)` is returned.
1308 /// Note that the order in which the items will be reduced is not
1309 /// specified, so if the comparison function is not associative, then
1310 /// the results are not deterministic.
1315 /// use rayon::prelude::*;
1317 /// let a = [-3_i32, 77, 53, 240, -1];
1319 /// assert_eq!(a.par_iter().min_by(|x, y| x.cmp(y)), Some(&-3));
1321 fn min_by
<F
>(self, f
: F
) -> Option
<Self::Item
>
1323 F
: Sync
+ Send
+ Fn(&Self::Item
, &Self::Item
) -> Ordering
,
1325 self.reduce_with(|a
, b
| match f(&a
, &b
) {
1326 Ordering
::Greater
=> b
,
1331 /// Computes the item that yields the minimum value for the given
1332 /// function. If the iterator is empty, `None` is returned;
1333 /// otherwise, `Some(item)` is returned.
1335 /// Note that the order in which the items will be reduced is not
1336 /// specified, so if the `Ord` impl is not truly associative, then
1337 /// the results are not deterministic.
1342 /// use rayon::prelude::*;
1344 /// let a = [-3_i32, 34, 2, 5, -10, -3, -23];
1346 /// assert_eq!(a.par_iter().min_by_key(|x| x.abs()), Some(&2));
1348 fn min_by_key
<K
, F
>(self, f
: F
) -> Option
<Self::Item
>
1351 F
: Sync
+ Send
+ Fn(&Self::Item
) -> K
,
1353 self.map(|x
| (f(&x
), x
))
1354 .min_by(|a
, b
| (a
.0).cmp(&b
.0))
1358 /// Computes the maximum of all the items in the iterator. If the
1359 /// iterator is empty, `None` is returned; otherwise, `Some(max)`
1362 /// Note that the order in which the items will be reduced is not
1363 /// specified, so if the `Ord` impl is not truly associative, then
1364 /// the results are not deterministic.
1366 /// Basically equivalent to `self.reduce_with(|a, b| cmp::max(a, b))`.
1371 /// use rayon::prelude::*;
1373 /// let a = [45, 74, 32];
1375 /// assert_eq!(a.par_iter().max(), Some(&74));
1377 /// let b: [i32; 0] = [];
1379 /// assert_eq!(b.par_iter().max(), None);
1381 fn max(self) -> Option
<Self::Item
>
1385 self.reduce_with(cmp
::max
)
1388 /// Computes the maximum of all the items in the iterator with respect to
1389 /// the given comparison function. If the iterator is empty, `None` is
1390 /// returned; otherwise, `Some(min)` is returned.
1392 /// Note that the order in which the items will be reduced is not
1393 /// specified, so if the comparison function is not associative, then
1394 /// the results are not deterministic.
1399 /// use rayon::prelude::*;
1401 /// let a = [-3_i32, 77, 53, 240, -1];
1403 /// assert_eq!(a.par_iter().max_by(|x, y| x.abs().cmp(&y.abs())), Some(&240));
1405 fn max_by
<F
>(self, f
: F
) -> Option
<Self::Item
>
1407 F
: Sync
+ Send
+ Fn(&Self::Item
, &Self::Item
) -> Ordering
,
1409 self.reduce_with(|a
, b
| match f(&a
, &b
) {
1410 Ordering
::Greater
=> a
,
1415 /// Computes the item that yields the maximum value for the given
1416 /// function. If the iterator is empty, `None` is returned;
1417 /// otherwise, `Some(item)` is returned.
1419 /// Note that the order in which the items will be reduced is not
1420 /// specified, so if the `Ord` impl is not truly associative, then
1421 /// the results are not deterministic.
1426 /// use rayon::prelude::*;
1428 /// let a = [-3_i32, 34, 2, 5, -10, -3, -23];
1430 /// assert_eq!(a.par_iter().max_by_key(|x| x.abs()), Some(&34));
1432 fn max_by_key
<K
, F
>(self, f
: F
) -> Option
<Self::Item
>
1435 F
: Sync
+ Send
+ Fn(&Self::Item
) -> K
,
1437 self.map(|x
| (f(&x
), x
))
1438 .max_by(|a
, b
| (a
.0).cmp(&b
.0))
1442 /// Takes two iterators and creates a new iterator over both.
1447 /// use rayon::prelude::*;
1449 /// let a = [0, 1, 2];
1450 /// let b = [9, 8, 7];
1452 /// let par_iter = a.par_iter().chain(b.par_iter());
1454 /// let chained: Vec<_> = par_iter.cloned().collect();
1456 /// assert_eq!(&chained[..], &[0, 1, 2, 9, 8, 7]);
1458 fn chain
<C
>(self, chain
: C
) -> Chain
<Self, C
::Iter
>
1460 C
: IntoParallelIterator
<Item
= Self::Item
>,
1462 chain
::new(self, chain
.into_par_iter())
1465 /// Searches for **some** item in the parallel iterator that
1466 /// matches the given predicate and returns it. This operation
1467 /// is similar to [`find` on sequential iterators][find] but
1468 /// the item returned may not be the **first** one in the parallel
1469 /// sequence which matches, since we search the entire sequence in parallel.
1471 /// Once a match is found, we will attempt to stop processing
1472 /// the rest of the items in the iterator as soon as possible
1473 /// (just as `find` stops iterating once a match is found).
1475 /// [find]: https://doc.rust-lang.org/std/iter/trait.Iterator.html#method.find
1480 /// use rayon::prelude::*;
1482 /// let a = [1, 2, 3, 3];
1484 /// assert_eq!(a.par_iter().find_any(|&&x| x == 3), Some(&3));
1486 /// assert_eq!(a.par_iter().find_any(|&&x| x == 100), None);
1488 fn find_any
<P
>(self, predicate
: P
) -> Option
<Self::Item
>
1490 P
: Fn(&Self::Item
) -> bool
+ Sync
+ Send
,
1492 find
::find(self, predicate
)
1495 /// Searches for the sequentially **first** item in the parallel iterator
1496 /// that matches the given predicate and returns it.
1498 /// Once a match is found, all attempts to the right of the match
1499 /// will be stopped, while attempts to the left must continue in case
1500 /// an earlier match is found.
1502 /// Note that not all parallel iterators have a useful order, much like
1503 /// sequential `HashMap` iteration, so "first" may be nebulous. If you
1504 /// just want the first match that discovered anywhere in the iterator,
1505 /// `find_any` is a better choice.
1510 /// use rayon::prelude::*;
1512 /// let a = [1, 2, 3, 3];
1514 /// assert_eq!(a.par_iter().find_first(|&&x| x == 3), Some(&3));
1516 /// assert_eq!(a.par_iter().find_first(|&&x| x == 100), None);
1518 fn find_first
<P
>(self, predicate
: P
) -> Option
<Self::Item
>
1520 P
: Fn(&Self::Item
) -> bool
+ Sync
+ Send
,
1522 find_first_last
::find_first(self, predicate
)
1525 /// Searches for the sequentially **last** item in the parallel iterator
1526 /// that matches the given predicate and returns it.
1528 /// Once a match is found, all attempts to the left of the match
1529 /// will be stopped, while attempts to the right must continue in case
1530 /// a later match is found.
1532 /// Note that not all parallel iterators have a useful order, much like
1533 /// sequential `HashMap` iteration, so "last" may be nebulous. When the
1534 /// order doesn't actually matter to you, `find_any` is a better choice.
1539 /// use rayon::prelude::*;
1541 /// let a = [1, 2, 3, 3];
1543 /// assert_eq!(a.par_iter().find_last(|&&x| x == 3), Some(&3));
1545 /// assert_eq!(a.par_iter().find_last(|&&x| x == 100), None);
1547 fn find_last
<P
>(self, predicate
: P
) -> Option
<Self::Item
>
1549 P
: Fn(&Self::Item
) -> bool
+ Sync
+ Send
,
1551 find_first_last
::find_last(self, predicate
)
1555 #[deprecated(note = "parallel `find` does not search in order -- use `find_any`, \\
1556 `find_first`, or `find_last`")]
1557 fn find
<P
>(self, predicate
: P
) -> Option
<Self::Item
>
1559 P
: Fn(&Self::Item
) -> bool
+ Sync
+ Send
,
1561 self.find_any(predicate
)
1564 /// Searches for **some** item in the parallel iterator that
1565 /// matches the given predicate, and if so returns true. Once
1566 /// a match is found, we'll attempt to stop process the rest
1567 /// of the items. Proving that there's no match, returning false,
1568 /// does require visiting every item.
1573 /// use rayon::prelude::*;
1575 /// let a = [0, 12, 3, 4, 0, 23, 0];
1577 /// let is_valid = a.par_iter().any(|&x| x > 10);
1579 /// assert!(is_valid);
1581 fn any
<P
>(self, predicate
: P
) -> bool
1583 P
: Fn(Self::Item
) -> bool
+ Sync
+ Send
,
1585 self.map(predicate
).find_any(|&p
| p
).is_some()
1588 /// Tests that every item in the parallel iterator matches the given
1589 /// predicate, and if so returns true. If a counter-example is found,
1590 /// we'll attempt to stop processing more items, then return false.
1595 /// use rayon::prelude::*;
1597 /// let a = [0, 12, 3, 4, 0, 23, 0];
1599 /// let is_valid = a.par_iter().all(|&x| x > 10);
1601 /// assert!(!is_valid);
1603 fn all
<P
>(self, predicate
: P
) -> bool
1605 P
: Fn(Self::Item
) -> bool
+ Sync
+ Send
,
1607 self.map(predicate
).find_any(|&p
| !p
).is_none()
1610 /// Creates an iterator over the `Some` items of this iterator, halting
1611 /// as soon as any `None` is found.
1616 /// use rayon::prelude::*;
1617 /// use std::sync::atomic::{AtomicUsize, Ordering};
1619 /// let counter = AtomicUsize::new(0);
1620 /// let value = (0_i32..2048)
1621 /// .into_par_iter()
1623 /// counter.fetch_add(1, Ordering::SeqCst);
1624 /// if x < 1024 { Some(x) } else { None }
1629 /// assert!(value < Some(1024));
1630 /// assert!(counter.load(Ordering::SeqCst) < 2048); // should not have visited every single one
1632 fn while_some
<T
>(self) -> WhileSome
<Self>
1634 Self: ParallelIterator
<Item
= Option
<T
>>,
1637 while_some
::new(self)
1640 /// Create a fresh collection containing all the element produced
1641 /// by this parallel iterator.
1643 /// You may prefer to use `collect_into_vec()`, which allocates more
1644 /// efficiently with precise knowledge of how many elements the
1645 /// iterator contains, and even allows you to reuse an existing
1646 /// vector's backing store rather than allocating a fresh vector.
1651 /// use rayon::prelude::*;
1653 /// let sync_vec: Vec<_> = (0..100).into_iter().collect();
1655 /// let async_vec: Vec<_> = (0..100).into_par_iter().collect();
1657 /// assert_eq!(sync_vec, async_vec);
1659 fn collect
<C
>(self) -> C
1661 C
: FromParallelIterator
<Self::Item
>,
1663 C
::from_par_iter(self)
1666 /// Unzips the items of a parallel iterator into a pair of arbitrary
1667 /// `ParallelExtend` containers.
1669 /// You may prefer to use `unzip_into_vecs()`, which allocates more
1670 /// efficiently with precise knowledge of how many elements the
1671 /// iterator contains, and even allows you to reuse existing
1672 /// vectors' backing stores rather than allocating fresh vectors.
1677 /// use rayon::prelude::*;
1679 /// let a = [(0, 1), (1, 2), (2, 3), (3, 4)];
1681 /// let (left, right): (Vec<_>, Vec<_>) = a.par_iter().cloned().unzip();
1683 /// assert_eq!(left, [0, 1, 2, 3]);
1684 /// assert_eq!(right, [1, 2, 3, 4]);
1687 /// Nested pairs can be unzipped too.
1690 /// use rayon::prelude::*;
1692 /// let (values, (squares, cubes)): (Vec<_>, (Vec<_>, Vec<_>)) = (0..4).into_par_iter()
1693 /// .map(|i| (i, (i * i, i * i * i)))
1696 /// assert_eq!(values, [0, 1, 2, 3]);
1697 /// assert_eq!(squares, [0, 1, 4, 9]);
1698 /// assert_eq!(cubes, [0, 1, 8, 27]);
1700 fn unzip
<A
, B
, FromA
, FromB
>(self) -> (FromA
, FromB
)
1702 Self: ParallelIterator
<Item
= (A
, B
)>,
1703 FromA
: Default
+ Send
+ ParallelExtend
<A
>,
1704 FromB
: Default
+ Send
+ ParallelExtend
<B
>,
1711 /// Partitions the items of a parallel iterator into a pair of arbitrary
1712 /// `ParallelExtend` containers. Items for which the `predicate` returns
1713 /// true go into the first container, and the rest go into the second.
1715 /// Note: unlike the standard `Iterator::partition`, this allows distinct
1716 /// collection types for the left and right items. This is more flexible,
1717 /// but may require new type annotations when converting sequential code
1718 /// that used type inferrence assuming the two were the same.
1723 /// use rayon::prelude::*;
1725 /// let (left, right): (Vec<_>, Vec<_>) = (0..8).into_par_iter().partition(|x| x % 2 == 0);
1727 /// assert_eq!(left, [0, 2, 4, 6]);
1728 /// assert_eq!(right, [1, 3, 5, 7]);
1730 fn partition
<A
, B
, P
>(self, predicate
: P
) -> (A
, B
)
1732 A
: Default
+ Send
+ ParallelExtend
<Self::Item
>,
1733 B
: Default
+ Send
+ ParallelExtend
<Self::Item
>,
1734 P
: Fn(&Self::Item
) -> bool
+ Sync
+ Send
,
1736 unzip
::partition(self, predicate
)
1739 /// Partitions and maps the items of a parallel iterator into a pair of
1740 /// arbitrary `ParallelExtend` containers. `Either::Left` items go into
1741 /// the first container, and `Either::Right` items go into the second.
1746 /// use rayon::prelude::*;
1747 /// use rayon::iter::Either;
1749 /// let (left, right): (Vec<_>, Vec<_>) = (0..8).into_par_iter()
1750 /// .partition_map(|x| {
1752 /// Either::Left(x * 4)
1754 /// Either::Right(x * 3)
1758 /// assert_eq!(left, [0, 8, 16, 24]);
1759 /// assert_eq!(right, [3, 9, 15, 21]);
1762 /// Nested `Either` enums can be split as well.
1765 /// use rayon::prelude::*;
1766 /// use rayon::iter::Either::*;
1768 /// let ((fizzbuzz, fizz), (buzz, other)): ((Vec<_>, Vec<_>), (Vec<_>, Vec<_>)) = (1..20)
1769 /// .into_par_iter()
1770 /// .partition_map(|x| match (x % 3, x % 5) {
1771 /// (0, 0) => Left(Left(x)),
1772 /// (0, _) => Left(Right(x)),
1773 /// (_, 0) => Right(Left(x)),
1774 /// (_, _) => Right(Right(x)),
1777 /// assert_eq!(fizzbuzz, [15]);
1778 /// assert_eq!(fizz, [3, 6, 9, 12, 18]);
1779 /// assert_eq!(buzz, [5, 10]);
1780 /// assert_eq!(other, [1, 2, 4, 7, 8, 11, 13, 14, 16, 17, 19]);
1782 fn partition_map
<A
, B
, P
, L
, R
>(self, predicate
: P
) -> (A
, B
)
1784 A
: Default
+ Send
+ ParallelExtend
<L
>,
1785 B
: Default
+ Send
+ ParallelExtend
<R
>,
1786 P
: Fn(Self::Item
) -> Either
<L
, R
> + Sync
+ Send
,
1790 unzip
::partition_map(self, predicate
)
1793 /// Intersperses clones of an element between items of this iterator.
1798 /// use rayon::prelude::*;
1800 /// let x = vec![1, 2, 3];
1801 /// let r: Vec<_> = x.into_par_iter().intersperse(-1).collect();
1803 /// assert_eq!(r, vec![1, -1, 2, -1, 3]);
1805 fn intersperse(self, element
: Self::Item
) -> Intersperse
<Self>
1809 intersperse
::new(self, element
)
1812 /// Internal method used to define the behavior of this parallel
1813 /// iterator. You should not need to call this directly.
1815 /// This method causes the iterator `self` to start producing
1816 /// items and to feed them to the consumer `consumer` one by one.
1817 /// It may split the consumer before doing so to create the
1818 /// opportunity to produce in parallel.
1820 /// See the [README] for more details on the internals of parallel
1823 /// [README]: README.md
1824 fn drive_unindexed
<C
>(self, consumer
: C
) -> C
::Result
1826 C
: UnindexedConsumer
<Self::Item
>;
1828 /// Internal method used to define the behavior of this parallel
1829 /// iterator. You should not need to call this directly.
1831 /// Returns the number of items produced by this iterator, if known
1832 /// statically. This can be used by consumers to trigger special fast
1833 /// paths. Therefore, if `Some(_)` is returned, this iterator must only
1834 /// use the (indexed) `Consumer` methods when driving a consumer, such
1835 /// as `split_at()`. Calling `UnindexedConsumer::split_off_left()` or
1836 /// other `UnindexedConsumer` methods -- or returning an inaccurate
1837 /// value -- may result in panics.
1839 /// This method is currently used to optimize `collect` for want
1840 /// of true Rust specialization; it may be removed when
1841 /// specialization is stable.
1842 fn opt_len(&self) -> Option
<usize> {
1847 impl<T
: ParallelIterator
> IntoParallelIterator
for T
{
1849 type Item
= T
::Item
;
1851 fn into_par_iter(self) -> T
{
1856 /// An iterator that supports "random access" to its data, meaning
1857 /// that you can split it at arbitrary indices and draw data from
1860 /// **Note:** Not implemented for `u64`, `i64`, `u128`, or `i128` ranges
1861 pub trait IndexedParallelIterator
: ParallelIterator
{
1862 /// Collects the results of the iterator into the specified
1863 /// vector. The vector is always truncated before execution
1864 /// begins. If possible, reusing the vector across calls can lead
1865 /// to better performance since it reuses the same backing buffer.
1870 /// use rayon::prelude::*;
1872 /// // any prior data will be truncated
1873 /// let mut vec = vec![-1, -2, -3];
1875 /// (0..5).into_par_iter()
1876 /// .collect_into_vec(&mut vec);
1878 /// assert_eq!(vec, [0, 1, 2, 3, 4]);
1880 fn collect_into_vec(self, target
: &mut Vec
<Self::Item
>) {
1881 collect
::collect_into_vec(self, target
);
1884 /// Unzips the results of the iterator into the specified
1885 /// vectors. The vectors are always truncated before execution
1886 /// begins. If possible, reusing the vectors across calls can lead
1887 /// to better performance since they reuse the same backing buffer.
1892 /// use rayon::prelude::*;
1894 /// // any prior data will be truncated
1895 /// let mut left = vec![42; 10];
1896 /// let mut right = vec![-1; 10];
1898 /// (10..15).into_par_iter()
1900 /// .unzip_into_vecs(&mut left, &mut right);
1902 /// assert_eq!(left, [0, 1, 2, 3, 4]);
1903 /// assert_eq!(right, [10, 11, 12, 13, 14]);
1905 fn unzip_into_vecs
<A
, B
>(self, left
: &mut Vec
<A
>, right
: &mut Vec
<B
>)
1907 Self: IndexedParallelIterator
<Item
= (A
, B
)>,
1911 collect
::unzip_into_vecs(self, left
, right
);
1914 /// Iterate over tuples `(A, B)`, where the items `A` are from
1915 /// this iterator and `B` are from the iterator given as argument.
1916 /// Like the `zip` method on ordinary iterators, if the two
1917 /// iterators are of unequal length, you only get the items they
1923 /// use rayon::prelude::*;
1925 /// let result: Vec<_> = (1..4)
1926 /// .into_par_iter()
1927 /// .zip(vec!['a', 'b', 'c'])
1930 /// assert_eq!(result, [(1, 'a'), (2, 'b'), (3, 'c')]);
1932 fn zip
<Z
>(self, zip_op
: Z
) -> Zip
<Self, Z
::Iter
>
1934 Z
: IntoParallelIterator
,
1935 Z
::Iter
: IndexedParallelIterator
,
1937 zip
::new(self, zip_op
.into_par_iter())
1940 /// The same as `Zip`, but requires that both iterators have the same length.
1943 /// Will panic if `self` and `zip_op` are not the same length.
1946 /// use rayon::prelude::*;
1948 /// let one = [1u8];
1949 /// let two = [2u8, 2];
1950 /// let one_iter = one.par_iter();
1951 /// let two_iter = two.par_iter();
1953 /// // this will panic
1954 /// let zipped: Vec<(&u8, &u8)> = one_iter.zip_eq(two_iter).collect();
1956 /// // we should never get here
1957 /// assert_eq!(1, zipped.len());
1959 fn zip_eq
<Z
>(self, zip_op
: Z
) -> ZipEq
<Self, Z
::Iter
>
1961 Z
: IntoParallelIterator
,
1962 Z
::Iter
: IndexedParallelIterator
,
1964 let zip_op_iter
= zip_op
.into_par_iter();
1965 assert_eq
!(self.len(), zip_op_iter
.len());
1966 zip_eq
::new(self, zip_op_iter
)
1969 /// Interleave elements of this iterator and the other given
1970 /// iterator. Alternately yields elements from this iterator and
1971 /// the given iterator, until both are exhausted. If one iterator
1972 /// is exhausted before the other, the last elements are provided
1978 /// use rayon::prelude::*;
1979 /// let (x, y) = (vec![1, 2], vec![3, 4, 5, 6]);
1980 /// let r: Vec<i32> = x.into_par_iter().interleave(y).collect();
1981 /// assert_eq!(r, vec![1, 3, 2, 4, 5, 6]);
1983 fn interleave
<I
>(self, other
: I
) -> Interleave
<Self, I
::Iter
>
1985 I
: IntoParallelIterator
<Item
= Self::Item
>,
1986 I
::Iter
: IndexedParallelIterator
<Item
= Self::Item
>,
1988 interleave
::new(self, other
.into_par_iter())
1991 /// Interleave elements of this iterator and the other given
1992 /// iterator, until one is exhausted.
1997 /// use rayon::prelude::*;
1998 /// let (x, y) = (vec![1, 2, 3, 4], vec![5, 6]);
1999 /// let r: Vec<i32> = x.into_par_iter().interleave_shortest(y).collect();
2000 /// assert_eq!(r, vec![1, 5, 2, 6, 3]);
2002 fn interleave_shortest
<I
>(self, other
: I
) -> InterleaveShortest
<Self, I
::Iter
>
2004 I
: IntoParallelIterator
<Item
= Self::Item
>,
2005 I
::Iter
: IndexedParallelIterator
<Item
= Self::Item
>,
2007 interleave_shortest
::new(self, other
.into_par_iter())
2010 /// Split an iterator up into fixed-size chunks.
2012 /// Returns an iterator that returns `Vec`s of the given number of elements.
2013 /// If the number of elements in the iterator is not divisible by `chunk_size`,
2014 /// the last chunk may be shorter than `chunk_size`.
2016 /// See also [`par_chunks()`] and [`par_chunks_mut()`] for similar behavior on
2017 /// slices, without having to allocate intermediate `Vec`s for the chunks.
2019 /// [`par_chunks()`]: ../slice/trait.ParallelSlice.html#method.par_chunks
2020 /// [`par_chunks_mut()`]: ../slice/trait.ParallelSliceMut.html#method.par_chunks_mut
2025 /// use rayon::prelude::*;
2026 /// let a = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
2027 /// let r: Vec<Vec<i32>> = a.into_par_iter().chunks(3).collect();
2028 /// assert_eq!(r, vec![vec![1,2,3], vec![4,5,6], vec![7,8,9], vec![10]]);
2030 fn chunks(self, chunk_size
: usize) -> Chunks
<Self> {
2031 assert
!(chunk_size
!= 0, "chunk_size must not be zero");
2032 chunks
::new(self, chunk_size
)
2035 /// Lexicographically compares the elements of this `ParallelIterator` with those of
2041 /// use rayon::prelude::*;
2042 /// use std::cmp::Ordering::*;
2044 /// let x = vec![1, 2, 3];
2045 /// assert_eq!(x.par_iter().cmp(&vec![1, 3, 0]), Less);
2046 /// assert_eq!(x.par_iter().cmp(&vec![1, 2, 3]), Equal);
2047 /// assert_eq!(x.par_iter().cmp(&vec![1, 2]), Greater);
2049 fn cmp
<I
>(self, other
: I
) -> Ordering
2051 I
: IntoParallelIterator
<Item
= Self::Item
>,
2052 I
::Iter
: IndexedParallelIterator
,
2055 let other
= other
.into_par_iter();
2056 let ord_len
= self.len().cmp(&other
.len());
2058 .map(|(x
, y
)| Ord
::cmp(&x
, &y
))
2059 .find_first(|&ord
| ord
!= Ordering
::Equal
)
2063 /// Lexicographically compares the elements of this `ParallelIterator` with those of
2069 /// use rayon::prelude::*;
2070 /// use std::cmp::Ordering::*;
2071 /// use std::f64::NAN;
2073 /// let x = vec![1.0, 2.0, 3.0];
2074 /// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, 3.0, 0.0]), Some(Less));
2075 /// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, 2.0, 3.0]), Some(Equal));
2076 /// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, 2.0]), Some(Greater));
2077 /// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, NAN]), None);
2079 fn partial_cmp
<I
>(self, other
: I
) -> Option
<Ordering
>
2081 I
: IntoParallelIterator
,
2082 I
::Iter
: IndexedParallelIterator
,
2083 Self::Item
: PartialOrd
<I
::Item
>,
2085 let other
= other
.into_par_iter();
2086 let ord_len
= self.len().cmp(&other
.len());
2088 .map(|(x
, y
)| PartialOrd
::partial_cmp(&x
, &y
))
2089 .find_first(|&ord
| ord
!= Some(Ordering
::Equal
))
2090 .unwrap_or(Some(ord_len
))
2093 /// Determines if the elements of this `ParallelIterator`
2094 /// are equal to those of another
2095 fn eq
<I
>(self, other
: I
) -> bool
2097 I
: IntoParallelIterator
,
2098 I
::Iter
: IndexedParallelIterator
,
2099 Self::Item
: PartialEq
<I
::Item
>,
2101 let other
= other
.into_par_iter();
2102 self.len() == other
.len() && self.zip(other
).all(|(x
, y
)| x
.eq(&y
))
2105 /// Determines if the elements of this `ParallelIterator`
2106 /// are unequal to those of another
2107 fn ne
<I
>(self, other
: I
) -> bool
2109 I
: IntoParallelIterator
,
2110 I
::Iter
: IndexedParallelIterator
,
2111 Self::Item
: PartialEq
<I
::Item
>,
2116 /// Determines if the elements of this `ParallelIterator`
2117 /// are lexicographically less than those of another.
2118 fn lt
<I
>(self, other
: I
) -> bool
2120 I
: IntoParallelIterator
,
2121 I
::Iter
: IndexedParallelIterator
,
2122 Self::Item
: PartialOrd
<I
::Item
>,
2124 self.partial_cmp(other
) == Some(Ordering
::Less
)
2127 /// Determines if the elements of this `ParallelIterator`
2128 /// are less or equal to those of another.
2129 fn le
<I
>(self, other
: I
) -> bool
2131 I
: IntoParallelIterator
,
2132 I
::Iter
: IndexedParallelIterator
,
2133 Self::Item
: PartialOrd
<I
::Item
>,
2135 let ord
= self.partial_cmp(other
);
2136 ord
== Some(Ordering
::Equal
) || ord
== Some(Ordering
::Less
)
2139 /// Determines if the elements of this `ParallelIterator`
2140 /// are lexicographically greater than those of another.
2141 fn gt
<I
>(self, other
: I
) -> bool
2143 I
: IntoParallelIterator
,
2144 I
::Iter
: IndexedParallelIterator
,
2145 Self::Item
: PartialOrd
<I
::Item
>,
2147 self.partial_cmp(other
) == Some(Ordering
::Greater
)
2150 /// Determines if the elements of this `ParallelIterator`
2151 /// are less or equal to those of another.
2152 fn ge
<I
>(self, other
: I
) -> bool
2154 I
: IntoParallelIterator
,
2155 I
::Iter
: IndexedParallelIterator
,
2156 Self::Item
: PartialOrd
<I
::Item
>,
2158 let ord
= self.partial_cmp(other
);
2159 ord
== Some(Ordering
::Equal
) || ord
== Some(Ordering
::Greater
)
2162 /// Yields an index along with each item.
2167 /// use rayon::prelude::*;
2169 /// let chars = vec!['a', 'b', 'c'];
2170 /// let result: Vec<_> = chars
2171 /// .into_par_iter()
2175 /// assert_eq!(result, [(0, 'a'), (1, 'b'), (2, 'c')]);
2177 fn enumerate(self) -> Enumerate
<Self> {
2178 enumerate
::new(self)
2181 /// Creates an iterator that skips the first `n` elements.
2186 /// use rayon::prelude::*;
2188 /// let result: Vec<_> = (0..100)
2189 /// .into_par_iter()
2193 /// assert_eq!(result, [95, 96, 97, 98, 99]);
2195 fn skip(self, n
: usize) -> Skip
<Self> {
2199 /// Creates an iterator that yields the first `n` elements.
2204 /// use rayon::prelude::*;
2206 /// let result: Vec<_> = (0..100)
2207 /// .into_par_iter()
2211 /// assert_eq!(result, [0, 1, 2, 3, 4]);
2213 fn take(self, n
: usize) -> Take
<Self> {
2217 /// Searches for **some** item in the parallel iterator that
2218 /// matches the given predicate, and returns its index. Like
2219 /// `ParallelIterator::find_any`, the parallel search will not
2220 /// necessarily find the **first** match, and once a match is
2221 /// found we'll attempt to stop processing any more.
2226 /// use rayon::prelude::*;
2228 /// let a = [1, 2, 3, 3];
2230 /// let i = a.par_iter().position_any(|&x| x == 3).expect("found");
2231 /// assert!(i == 2 || i == 3);
2233 /// assert_eq!(a.par_iter().position_any(|&x| x == 100), None);
2235 fn position_any
<P
>(self, predicate
: P
) -> Option
<usize>
2237 P
: Fn(Self::Item
) -> bool
+ Sync
+ Send
,
2241 .find_any(|&(_
, p
)| p
)
2245 /// Searches for the sequentially **first** item in the parallel iterator
2246 /// that matches the given predicate, and returns its index.
2248 /// Like `ParallelIterator::find_first`, once a match is found,
2249 /// all attempts to the right of the match will be stopped, while
2250 /// attempts to the left must continue in case an earlier match
2253 /// Note that not all parallel iterators have a useful order, much like
2254 /// sequential `HashMap` iteration, so "first" may be nebulous. If you
2255 /// just want the first match that discovered anywhere in the iterator,
2256 /// `position_any` is a better choice.
2261 /// use rayon::prelude::*;
2263 /// let a = [1, 2, 3, 3];
2265 /// assert_eq!(a.par_iter().position_first(|&x| x == 3), Some(2));
2267 /// assert_eq!(a.par_iter().position_first(|&x| x == 100), None);
2269 fn position_first
<P
>(self, predicate
: P
) -> Option
<usize>
2271 P
: Fn(Self::Item
) -> bool
+ Sync
+ Send
,
2275 .find_first(|&(_
, p
)| p
)
2279 /// Searches for the sequentially **last** item in the parallel iterator
2280 /// that matches the given predicate, and returns its index.
2282 /// Like `ParallelIterator::find_last`, once a match is found,
2283 /// all attempts to the left of the match will be stopped, while
2284 /// attempts to the right must continue in case a later match
2287 /// Note that not all parallel iterators have a useful order, much like
2288 /// sequential `HashMap` iteration, so "last" may be nebulous. When the
2289 /// order doesn't actually matter to you, `position_any` is a better
2295 /// use rayon::prelude::*;
2297 /// let a = [1, 2, 3, 3];
2299 /// assert_eq!(a.par_iter().position_last(|&x| x == 3), Some(3));
2301 /// assert_eq!(a.par_iter().position_last(|&x| x == 100), None);
2303 fn position_last
<P
>(self, predicate
: P
) -> Option
<usize>
2305 P
: Fn(Self::Item
) -> bool
+ Sync
+ Send
,
2309 .find_last(|&(_
, p
)| p
)
2315 note
= "parallel `position` does not search in order -- use `position_any`, \\
2316 `position_first`, or `position_last`"
2318 fn position
<P
>(self, predicate
: P
) -> Option
<usize>
2320 P
: Fn(Self::Item
) -> bool
+ Sync
+ Send
,
2322 self.position_any(predicate
)
2325 /// Produces a new iterator with the elements of this iterator in
2331 /// use rayon::prelude::*;
2333 /// let result: Vec<_> = (0..5)
2334 /// .into_par_iter()
2338 /// assert_eq!(result, [4, 3, 2, 1, 0]);
2340 fn rev(self) -> Rev
<Self> {
2344 /// Sets the minimum length of iterators desired to process in each
2345 /// thread. Rayon will not split any smaller than this length, but
2346 /// of course an iterator could already be smaller to begin with.
2348 /// Producers like `zip` and `interleave` will use greater of the two
2350 /// Chained iterators and iterators inside `flat_map` may each use
2351 /// their own minimum length.
2356 /// use rayon::prelude::*;
2358 /// let min = (0..1_000_000)
2359 /// .into_par_iter()
2360 /// .with_min_len(1234)
2361 /// .fold(|| 0, |acc, _| acc + 1) // count how many are in this segment
2362 /// .min().unwrap();
2364 /// assert!(min >= 1234);
2366 fn with_min_len(self, min
: usize) -> MinLen
<Self> {
2367 len
::new_min_len(self, min
)
2370 /// Sets the maximum length of iterators desired to process in each
2371 /// thread. Rayon will try to split at least below this length,
2372 /// unless that would put it below the length from `with_min_len()`.
2373 /// For example, given min=10 and max=15, a length of 16 will not be
2374 /// split any further.
2376 /// Producers like `zip` and `interleave` will use lesser of the two
2378 /// Chained iterators and iterators inside `flat_map` may each use
2379 /// their own maximum length.
2384 /// use rayon::prelude::*;
2386 /// let max = (0..1_000_000)
2387 /// .into_par_iter()
2388 /// .with_max_len(1234)
2389 /// .fold(|| 0, |acc, _| acc + 1) // count how many are in this segment
2390 /// .max().unwrap();
2392 /// assert!(max <= 1234);
2394 fn with_max_len(self, max
: usize) -> MaxLen
<Self> {
2395 len
::new_max_len(self, max
)
2398 /// Produces an exact count of how many items this iterator will
2399 /// produce, presuming no panic occurs.
2404 /// use rayon::prelude::*;
2406 /// let par_iter = (0..100).into_par_iter().zip(vec![0; 10]);
2407 /// assert_eq!(par_iter.len(), 10);
2409 /// let vec: Vec<_> = par_iter.collect();
2410 /// assert_eq!(vec.len(), 10);
2412 fn len(&self) -> usize;
2414 /// Internal method used to define the behavior of this parallel
2415 /// iterator. You should not need to call this directly.
2417 /// This method causes the iterator `self` to start producing
2418 /// items and to feed them to the consumer `consumer` one by one.
2419 /// It may split the consumer before doing so to create the
2420 /// opportunity to produce in parallel. If a split does happen, it
2421 /// will inform the consumer of the index where the split should
2422 /// occur (unlike `ParallelIterator::drive_unindexed()`).
2424 /// See the [README] for more details on the internals of parallel
2427 /// [README]: README.md
2428 fn drive
<C
: Consumer
<Self::Item
>>(self, consumer
: C
) -> C
::Result
;
2430 /// Internal method used to define the behavior of this parallel
2431 /// iterator. You should not need to call this directly.
2433 /// This method converts the iterator into a producer P and then
2434 /// invokes `callback.callback()` with P. Note that the type of
2435 /// this producer is not defined as part of the API, since
2436 /// `callback` must be defined generically for all producers. This
2437 /// allows the producer type to contain references; it also means
2438 /// that parallel iterators can adjust that type without causing a
2439 /// breaking change.
2441 /// See the [README] for more details on the internals of parallel
2444 /// [README]: README.md
2445 fn with_producer
<CB
: ProducerCallback
<Self::Item
>>(self, callback
: CB
) -> CB
::Output
;
2448 /// `FromParallelIterator` implements the creation of a collection
2449 /// from a [`ParallelIterator`]. By implementing
2450 /// `FromParallelIterator` for a given type, you define how it will be
2451 /// created from an iterator.
2453 /// `FromParallelIterator` is used through [`ParallelIterator`]'s [`collect()`] method.
2455 /// [`ParallelIterator`]: trait.ParallelIterator.html
2456 /// [`collect()`]: trait.ParallelIterator.html#method.collect
2460 /// Implementing `FromParallelIterator` for your type:
2463 /// use rayon::prelude::*;
2466 /// struct BlackHole {
2470 /// impl<T: Send> FromParallelIterator<T> for BlackHole {
2471 /// fn from_par_iter<I>(par_iter: I) -> Self
2472 /// where I: IntoParallelIterator<Item = T>
2474 /// let par_iter = par_iter.into_par_iter();
2476 /// mass: par_iter.count() * mem::size_of::<T>(),
2481 /// let bh: BlackHole = (0i32..1000).into_par_iter().collect();
2482 /// assert_eq!(bh.mass, 4000);
2484 pub trait FromParallelIterator
<T
>
2488 /// Creates an instance of the collection from the parallel iterator `par_iter`.
2490 /// If your collection is not naturally parallel, the easiest (and
2491 /// fastest) way to do this is often to collect `par_iter` into a
2492 /// [`LinkedList`] or other intermediate data structure and then
2493 /// sequentially extend your collection. However, a more 'native'
2494 /// technique is to use the [`par_iter.fold`] or
2495 /// [`par_iter.fold_with`] methods to create the collection.
2496 /// Alternatively, if your collection is 'natively' parallel, you
2497 /// can use `par_iter.for_each` to process each element in turn.
2499 /// [`LinkedList`]: https://doc.rust-lang.org/std/collections/struct.LinkedList.html
2500 /// [`par_iter.fold`]: trait.ParallelIterator.html#method.fold
2501 /// [`par_iter.fold_with`]: trait.ParallelIterator.html#method.fold_with
2502 /// [`par_iter.for_each`]: trait.ParallelIterator.html#method.for_each
2503 fn from_par_iter
<I
>(par_iter
: I
) -> Self
2505 I
: IntoParallelIterator
<Item
= T
>;
2508 /// `ParallelExtend` extends an existing collection with items from a [`ParallelIterator`].
2510 /// [`ParallelIterator`]: trait.ParallelIterator.html
2514 /// Implementing `ParallelExtend` for your type:
2517 /// use rayon::prelude::*;
2520 /// struct BlackHole {
2524 /// impl<T: Send> ParallelExtend<T> for BlackHole {
2525 /// fn par_extend<I>(&mut self, par_iter: I)
2526 /// where I: IntoParallelIterator<Item = T>
2528 /// let par_iter = par_iter.into_par_iter();
2529 /// self.mass += par_iter.count() * mem::size_of::<T>();
2533 /// let mut bh = BlackHole { mass: 0 };
2534 /// bh.par_extend(0i32..1000);
2535 /// assert_eq!(bh.mass, 4000);
2536 /// bh.par_extend(0i64..10);
2537 /// assert_eq!(bh.mass, 4080);
2539 pub trait ParallelExtend
<T
>
2543 /// Extends an instance of the collection with the elements drawn
2544 /// from the parallel iterator `par_iter`.
2549 /// use rayon::prelude::*;
2551 /// let mut vec = vec![];
2552 /// vec.par_extend(0..5);
2553 /// vec.par_extend((0..5).into_par_iter().map(|i| i * i));
2554 /// assert_eq!(vec, [0, 1, 2, 3, 4, 0, 1, 4, 9, 16]);
2556 fn par_extend
<I
>(&mut self, par_iter
: I
)
2558 I
: IntoParallelIterator
<Item
= T
>;
2561 /// We hide the `Try` trait in a private module, as it's only meant to be a
2562 /// stable clone of the standard library's `Try` trait, as yet unstable.
2564 /// Clone of `std::ops::Try`.
2566 /// Implementing this trait is not permitted outside of `rayon`.
2572 fn into_result(self) -> Result
<Self::Ok
, Self::Error
>;
2573 fn from_ok(v
: Self::Ok
) -> Self;
2574 fn from_error(v
: Self::Error
) -> Self;
2577 impl<T
> Try
for Option
<T
> {
2583 fn into_result(self) -> Result
<T
, ()> {
2586 fn from_ok(v
: T
) -> Self {
2589 fn from_error(_
: ()) -> Self {
2594 impl<T
, E
> Try
for Result
<T
, E
> {
2600 fn into_result(self) -> Result
<T
, E
> {
2603 fn from_ok(v
: T
) -> Self {
2606 fn from_error(v
: E
) -> Self {