//! If you'd like to build a custom parallel iterator, or to write your own
//! combinator, then check out the [split] function and the [plumbing] module.
//!
-//! [regular iterator]: http://doc.rust-lang.org/std/iter/trait.Iterator.html
+//! [regular iterator]: https://doc.rust-lang.org/std/iter/trait.Iterator.html
//! [`ParallelIterator`]: trait.ParallelIterator.html
//! [`IndexedParallelIterator`]: trait.IndexedParallelIterator.html
//! [split]: fn.split.html
-//! [plumbing]: plumbing
+//! [plumbing]: plumbing/index.html
+//!
+//! Note: Several of the `ParallelIterator` methods rely on a `Try` trait which
+//! has been deliberately obscured from the public API. This trait is intended
+//! to mirror the unstable `std::ops::Try` with implementations for `Option` and
+//! `Result`, where `Some`/`Ok` values will let those iterators continue, but
+//! `None`/`Err` values will exit early.
+//!
+//! A note about object safety: It is currently _not_ possible to wrap
+//! a `ParallelIterator` (or any trait that depends on it) using a
+//! `Box<dyn ParallelIterator>` or other kind of dynamic allocation,
+//! because `ParallelIterator` is **not object-safe**.
+//! (This keeps the implementation simpler and allows extra optimizations.)
+use self::plumbing::*;
+use self::private::Try;
pub use either::Either;
use std::cmp::{self, Ordering};
-use std::iter::{Sum, Product};
-use std::ops::Fn;
-use self::plumbing::*;
+use std::iter::{Product, Sum};
+use std::ops::{Fn, RangeBounds};
+
+pub mod plumbing;
+
+#[cfg(test)]
+mod test;
// There is a method to the madness here:
//
-// - Most of these modules are private but expose certain types to the end-user
+// - These modules are private but expose certain types to the end-user
// (e.g., `enumerate::Enumerate`) -- specifically, the types that appear in the
// public API surface of the `ParallelIterator` traits.
// - In **this** module, those public types are always used unprefixed, which forces
// e.g. `find::find()`, are always used **prefixed**, so that they
// can be readily distinguished.
-mod find;
-mod find_first_last;
mod chain;
-pub use self::chain::Chain;
mod chunks;
-pub use self::chunks::Chunks;
+mod cloned;
mod collect;
+mod copied;
+mod empty;
mod enumerate;
-pub use self::enumerate::Enumerate;
+mod extend;
mod filter;
-pub use self::filter::Filter;
mod filter_map;
-pub use self::filter_map::FilterMap;
+mod find;
+mod find_first_last;
mod flat_map;
-pub use self::flat_map::FlatMap;
+mod flat_map_iter;
mod flatten;
-pub use self::flatten::Flatten;
-mod from_par_iter;
-pub mod plumbing;
-mod for_each;
+mod flatten_iter;
mod fold;
-pub use self::fold::{Fold, FoldWith};
-mod reduce;
-mod skip;
-pub use self::skip::Skip;
-mod splitter;
-pub use self::splitter::{split, Split};
-mod take;
-pub use self::take::Take;
-mod map;
-pub use self::map::Map;
-mod map_with;
-pub use self::map_with::MapWith;
-mod zip;
-pub use self::zip::Zip;
-mod zip_eq;
-pub use self::zip_eq::ZipEq;
+mod for_each;
+mod from_par_iter;
+mod inspect;
mod interleave;
-pub use self::interleave::Interleave;
mod interleave_shortest;
-pub use self::interleave_shortest::InterleaveShortest;
mod intersperse;
-pub use self::intersperse::Intersperse;
-mod update;
-pub use self::update::Update;
-
+mod len;
+mod map;
+mod map_with;
+mod multizip;
mod noop;
+mod once;
+mod panic_fuse;
+mod par_bridge;
+mod positions;
+mod product;
+mod reduce;
+mod repeat;
mod rev;
-pub use self::rev::Rev;
-mod len;
-pub use self::len::{MinLen, MaxLen};
+mod skip;
+mod splitter;
mod sum;
-mod product;
-mod cloned;
-pub use self::cloned::Cloned;
-mod inspect;
-pub use self::inspect::Inspect;
-mod while_some;
-pub use self::while_some::WhileSome;
-mod extend;
+mod take;
+mod try_fold;
+mod try_reduce;
+mod try_reduce_with;
mod unzip;
-mod repeat;
-pub use self::repeat::{Repeat, repeat};
-pub use self::repeat::{RepeatN, repeatn};
-
-mod empty;
-pub use self::empty::{Empty, empty};
-mod once;
-pub use self::once::{Once, once};
+mod update;
+mod while_some;
+mod zip;
+mod zip_eq;
-#[cfg(test)]
-mod test;
+pub use self::{
+ chain::Chain,
+ chunks::Chunks,
+ cloned::Cloned,
+ copied::Copied,
+ empty::{empty, Empty},
+ enumerate::Enumerate,
+ filter::Filter,
+ filter_map::FilterMap,
+ flat_map::FlatMap,
+ flat_map_iter::FlatMapIter,
+ flatten::Flatten,
+ flatten_iter::FlattenIter,
+ fold::{Fold, FoldWith},
+ inspect::Inspect,
+ interleave::Interleave,
+ interleave_shortest::InterleaveShortest,
+ intersperse::Intersperse,
+ len::{MaxLen, MinLen},
+ map::Map,
+ map_with::{MapInit, MapWith},
+ multizip::MultiZip,
+ once::{once, Once},
+ panic_fuse::PanicFuse,
+ par_bridge::{IterBridge, ParallelBridge},
+ positions::Positions,
+ repeat::{repeat, repeatn, Repeat, RepeatN},
+ rev::Rev,
+ skip::Skip,
+ splitter::{split, Split},
+ take::Take,
+ try_fold::{TryFold, TryFoldWith},
+ update::Update,
+ while_some::WhileSome,
+ zip::Zip,
+ zip_eq::ZipEq,
+};
+
+mod step_by;
+#[cfg(has_step_by_rev)]
+pub use self::step_by::StepBy;
/// `IntoParallelIterator` implements the conversion to a [`ParallelIterator`].
///
}
impl<'data, I: 'data + ?Sized> IntoParallelRefIterator<'data> for I
- where &'data I: IntoParallelIterator
+where
+ &'data I: IntoParallelIterator,
{
type Iter = <&'data I as IntoParallelIterator>::Iter;
type Item = <&'data I as IntoParallelIterator>::Item;
}
}
-
/// `IntoParallelRefMutIterator` implements the conversion to a
/// [`ParallelIterator`], providing mutable references to the data.
///
}
impl<'data, I: 'data + ?Sized> IntoParallelRefMutIterator<'data> for I
- where &'data mut I: IntoParallelIterator
+where
+ &'data mut I: IntoParallelIterator,
{
type Iter = <&'data mut I as IntoParallelIterator>::Iter;
type Item = <&'data mut I as IntoParallelIterator>::Item;
/// (0..100).into_par_iter().for_each(|x| println!("{:?}", x));
/// ```
fn for_each<OP>(self, op: OP)
- where OP: Fn(Self::Item) + Sync + Send
+ where
+ OP: Fn(Self::Item) + Sync + Send,
{
for_each::for_each(self, &op)
}
/// assert_eq!(&res[..], &[0, 1, 2, 3, 4])
/// ```
fn for_each_with<OP, T>(self, init: T, op: OP)
- where OP: Fn(&mut T, Self::Item) + Sync + Send,
- T: Send + Clone
+ where
+ OP: Fn(&mut T, Self::Item) + Sync + Send,
+ T: Send + Clone,
{
- self.map_with(init, op).for_each(|()| ())
+ self.map_with(init, op).collect()
+ }
+
+ /// Executes `OP` on a value returned by `init` with each item produced by
+ /// the iterator, in parallel.
+ ///
+ /// The `init` function will be called only as needed for a value to be
+ /// paired with the group of items in each rayon job. There is no
+ /// constraint on that returned type at all!
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rand::Rng;
+ /// use rayon::prelude::*;
+ ///
+ /// let mut v = vec![0u8; 1_000_000];
+ ///
+ /// v.par_chunks_mut(1000)
+ /// .for_each_init(
+ /// || rand::thread_rng(),
+ /// |rng, chunk| rng.fill(chunk),
+ /// );
+ ///
+ /// // There's a remote chance that this will fail...
+ /// for i in 0u8..=255 {
+ /// assert!(v.contains(&i));
+ /// }
+ /// ```
+ fn for_each_init<OP, INIT, T>(self, init: INIT, op: OP)
+ where
+ OP: Fn(&mut T, Self::Item) + Sync + Send,
+ INIT: Fn() -> T + Sync + Send,
+ {
+ self.map_init(init, op).collect()
+ }
+
+ /// Executes a fallible `OP` on each item produced by the iterator, in parallel.
+ ///
+ /// If the `OP` returns `Result::Err` or `Option::None`, we will attempt to
+ /// stop processing the rest of the items in the iterator as soon as
+ /// possible, and we will return that terminating value. Otherwise, we will
+ /// return an empty `Result::Ok(())` or `Option::Some(())`. If there are
+ /// multiple errors in parallel, it is not specified which will be returned.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ /// use std::io::{self, Write};
+ ///
+ /// // This will stop iteration early if there's any write error, like
+ /// // having piped output get closed on the other end.
+ /// (0..100).into_par_iter()
+ /// .try_for_each(|x| writeln!(io::stdout(), "{:?}", x))
+ /// .expect("expected no write errors");
+ /// ```
+ fn try_for_each<OP, R>(self, op: OP) -> R
+ where
+ OP: Fn(Self::Item) -> R + Sync + Send,
+ R: Try<Output = ()> + Send,
+ {
+ fn ok<R: Try<Output = ()>>(_: (), _: ()) -> R {
+ R::from_output(())
+ }
+
+ self.map(op).try_reduce(<()>::default, ok)
+ }
+
+ /// Executes a fallible `OP` on the given `init` value with each item
+ /// produced by the iterator, in parallel.
+ ///
+ /// This combines the `init` semantics of [`for_each_with()`] and the
+ /// failure semantics of [`try_for_each()`].
+ ///
+ /// [`for_each_with()`]: #method.for_each_with
+ /// [`try_for_each()`]: #method.try_for_each
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use std::sync::mpsc::channel;
+ /// use rayon::prelude::*;
+ ///
+ /// let (sender, receiver) = channel();
+ ///
+ /// (0..5).into_par_iter()
+ /// .try_for_each_with(sender, |s, x| s.send(x))
+ /// .expect("expected no send errors");
+ ///
+ /// let mut res: Vec<_> = receiver.iter().collect();
+ ///
+ /// res.sort();
+ ///
+ /// assert_eq!(&res[..], &[0, 1, 2, 3, 4])
+ /// ```
+ fn try_for_each_with<OP, T, R>(self, init: T, op: OP) -> R
+ where
+ OP: Fn(&mut T, Self::Item) -> R + Sync + Send,
+ T: Send + Clone,
+ R: Try<Output = ()> + Send,
+ {
+ fn ok<R: Try<Output = ()>>(_: (), _: ()) -> R {
+ R::from_output(())
+ }
+
+ self.map_with(init, op).try_reduce(<()>::default, ok)
+ }
+
+ /// Executes a fallible `OP` on a value returned by `init` with each item
+ /// produced by the iterator, in parallel.
+ ///
+ /// This combines the `init` semantics of [`for_each_init()`] and the
+ /// failure semantics of [`try_for_each()`].
+ ///
+ /// [`for_each_init()`]: #method.for_each_init
+ /// [`try_for_each()`]: #method.try_for_each
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rand::Rng;
+ /// use rayon::prelude::*;
+ ///
+ /// let mut v = vec![0u8; 1_000_000];
+ ///
+ /// v.par_chunks_mut(1000)
+ /// .try_for_each_init(
+ /// || rand::thread_rng(),
+ /// |rng, chunk| rng.try_fill(chunk),
+ /// )
+ /// .expect("expected no rand errors");
+ ///
+ /// // There's a remote chance that this will fail...
+ /// for i in 0u8..=255 {
+ /// assert!(v.contains(&i));
+ /// }
+ /// ```
+ fn try_for_each_init<OP, INIT, T, R>(self, init: INIT, op: OP) -> R
+ where
+ OP: Fn(&mut T, Self::Item) -> R + Sync + Send,
+ INIT: Fn() -> T + Sync + Send,
+ R: Try<Output = ()> + Send,
+ {
+ fn ok<R: Try<Output = ()>>(_: (), _: ()) -> R {
+ R::from_output(())
+ }
+
+ self.map_init(init, op).try_reduce(<()>::default, ok)
}
/// Counts the number of items in this parallel iterator.
/// assert_eq!(count, 100);
/// ```
fn count(self) -> usize {
- self.map(|_| 1).sum()
+ fn one<T>(_: T) -> usize {
+ 1
+ }
+
+ self.map(one).sum()
}
/// Applies `map_op` to each item of this iterator, producing a new
/// assert_eq!(&doubles[..], &[0, 2, 4, 6, 8]);
/// ```
fn map<F, R>(self, map_op: F) -> Map<Self, F>
- where F: Fn(Self::Item) -> R + Sync + Send,
- R: Send
+ where
+ F: Fn(Self::Item) -> R + Sync + Send,
+ R: Send,
{
- map::new(self, map_op)
+ Map::new(self, map_op)
}
/// Applies `map_op` to the given `init` value with each item of this
/// assert_eq!(a, b);
/// ```
fn map_with<F, T, R>(self, init: T, map_op: F) -> MapWith<Self, T, F>
- where F: Fn(&mut T, Self::Item) -> R + Sync + Send,
- T: Send + Clone,
- R: Send
+ where
+ F: Fn(&mut T, Self::Item) -> R + Sync + Send,
+ T: Send + Clone,
+ R: Send,
+ {
+ MapWith::new(self, init, map_op)
+ }
+
+ /// Applies `map_op` to a value returned by `init` with each item of this
+ /// iterator, producing a new iterator with the results.
+ ///
+ /// The `init` function will be called only as needed for a value to be
+ /// paired with the group of items in each rayon job. There is no
+ /// constraint on that returned type at all!
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rand::Rng;
+ /// use rayon::prelude::*;
+ ///
+ /// let a: Vec<_> = (1i32..1_000_000)
+ /// .into_par_iter()
+ /// .map_init(
+ /// || rand::thread_rng(), // get the thread-local RNG
+ /// |rng, x| if rng.gen() { // randomly negate items
+ /// -x
+ /// } else {
+ /// x
+ /// },
+ /// ).collect();
+ ///
+ /// // There's a remote chance that this will fail...
+ /// assert!(a.iter().any(|&x| x < 0));
+ /// assert!(a.iter().any(|&x| x > 0));
+ /// ```
+ fn map_init<F, INIT, T, R>(self, init: INIT, map_op: F) -> MapInit<Self, INIT, F>
+ where
+ F: Fn(&mut T, Self::Item) -> R + Sync + Send,
+ INIT: Fn() -> T + Sync + Send,
+ R: Send,
{
- map_with::new(self, init, map_op)
+ MapInit::new(self, init, map_op)
}
/// Creates an iterator which clones all of its elements. This may be
- /// useful when you have an iterator over `&T`, but you need `T`.
+ /// useful when you have an iterator over `&T`, but you need `T`, and
+ /// that type implements `Clone`. See also [`copied()`].
+ ///
+ /// [`copied()`]: #method.copied
///
/// # Examples
///
/// assert_eq!(v_map, vec![1, 2, 3]);
/// ```
fn cloned<'a, T>(self) -> Cloned<Self>
- where T: 'a + Clone + Send,
- Self: ParallelIterator<Item = &'a T>
+ where
+ T: 'a + Clone + Send,
+ Self: ParallelIterator<Item = &'a T>,
{
- cloned::new(self)
+ Cloned::new(self)
+ }
+
+ /// Creates an iterator which copies all of its elements. This may be
+ /// useful when you have an iterator over `&T`, but you need `T`, and
+ /// that type implements `Copy`. See also [`cloned()`].
+ ///
+ /// [`cloned()`]: #method.cloned
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let a = [1, 2, 3];
+ ///
+ /// let v_copied: Vec<_> = a.par_iter().copied().collect();
+ ///
+ /// // copied is the same as .map(|&x| x), for integers
+ /// let v_map: Vec<_> = a.par_iter().map(|&x| x).collect();
+ ///
+ /// assert_eq!(v_copied, vec![1, 2, 3]);
+ /// assert_eq!(v_map, vec![1, 2, 3]);
+ /// ```
+ fn copied<'a, T>(self) -> Copied<Self>
+ where
+ T: 'a + Copy + Send,
+ Self: ParallelIterator<Item = &'a T>,
+ {
+ Copied::new(self)
}
/// Applies `inspect_op` to a reference to each item of this iterator,
/// println!("{}", sum);
/// ```
fn inspect<OP>(self, inspect_op: OP) -> Inspect<Self, OP>
- where OP: Fn(&Self::Item) + Sync + Send
+ where
+ OP: Fn(&Self::Item) + Sync + Send,
{
- inspect::new(self, inspect_op)
+ Inspect::new(self, inspect_op)
}
/// Mutates each item of this iterator before yielding it.
/// assert_eq!(&doubles[..], &[0, 2, 4, 6, 8]);
/// ```
fn update<F>(self, update_op: F) -> Update<Self, F>
- where F: Fn(&mut Self::Item) + Sync + Send
+ where
+ F: Fn(&mut Self::Item) + Sync + Send,
{
- update::new(self, update_op)
+ Update::new(self, update_op)
}
/// Applies `filter_op` to each item of this iterator, producing a new
/// assert_eq!(&even_numbers[..], &[0, 2, 4, 6, 8]);
/// ```
fn filter<P>(self, filter_op: P) -> Filter<Self, P>
- where P: Fn(&Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(&Self::Item) -> bool + Sync + Send,
{
- filter::new(self, filter_op)
+ Filter::new(self, filter_op)
}
/// Applies `filter_op` to each item of this iterator to get an `Option`,
/// assert_eq!(&even_numbers[..], &[0, 6, 12, 18, 24]);
/// ```
fn filter_map<P, R>(self, filter_op: P) -> FilterMap<Self, P>
- where P: Fn(Self::Item) -> Option<R> + Sync + Send,
- R: Send
+ where
+ P: Fn(Self::Item) -> Option<R> + Sync + Send,
+ R: Send,
{
- filter_map::new(self, filter_op)
+ FilterMap::new(self, filter_op)
}
- /// Applies `map_op` to each item of this iterator to get nested iterators,
- /// producing a new iterator that flattens these back into one.
+ /// Applies `map_op` to each item of this iterator to get nested parallel iterators,
+ /// producing a new parallel iterator that flattens these back into one.
+ ///
+ /// See also [`flat_map_iter`](#method.flat_map_iter).
///
/// # Examples
///
/// assert_eq!(&vec[..], &[1, 2, 3, 4, 5, 6, 7, 8]);
/// ```
fn flat_map<F, PI>(self, map_op: F) -> FlatMap<Self, F>
- where F: Fn(Self::Item) -> PI + Sync + Send,
- PI: IntoParallelIterator
+ where
+ F: Fn(Self::Item) -> PI + Sync + Send,
+ PI: IntoParallelIterator,
{
- flat_map::new(self, map_op)
+ FlatMap::new(self, map_op)
}
- /// An adaptor that flattens iterable `Item`s into one large iterator
+ /// Applies `map_op` to each item of this iterator to get nested serial iterators,
+ /// producing a new parallel iterator that flattens these back into one.
+ ///
+ /// # `flat_map_iter` versus `flat_map`
+ ///
+ /// These two methods are similar but behave slightly differently. With [`flat_map`],
+ /// each of the nested iterators must be a parallel iterator, and they will be further
+ /// split up with nested parallelism. With `flat_map_iter`, each nested iterator is a
+ /// sequential `Iterator`, and we only parallelize _between_ them, while the items
+ /// produced by each nested iterator are processed sequentially.
+ ///
+ /// When choosing between these methods, consider whether nested parallelism suits the
+ /// potential iterators at hand. If there's little computation involved, or its length
+ /// is much less than the outer parallel iterator, then it may perform better to avoid
+ /// the overhead of parallelism, just flattening sequentially with `flat_map_iter`.
+ /// If there is a lot of computation, potentially outweighing the outer parallel
+ /// iterator, then the nested parallelism of `flat_map` may be worthwhile.
+ ///
+ /// [`flat_map`]: #method.flat_map
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ /// use std::cell::RefCell;
+ ///
+ /// let a = [[1, 2], [3, 4], [5, 6], [7, 8]];
+ ///
+ /// let par_iter = a.par_iter().flat_map_iter(|a| {
+ /// // The serial iterator doesn't have to be thread-safe, just its items.
+ /// let cell_iter = RefCell::new(a.iter().cloned());
+ /// std::iter::from_fn(move || cell_iter.borrow_mut().next())
+ /// });
+ ///
+ /// let vec: Vec<_> = par_iter.collect();
+ ///
+ /// assert_eq!(&vec[..], &[1, 2, 3, 4, 5, 6, 7, 8]);
+ /// ```
+ fn flat_map_iter<F, SI>(self, map_op: F) -> FlatMapIter<Self, F>
+ where
+ F: Fn(Self::Item) -> SI + Sync + Send,
+ SI: IntoIterator,
+ SI::Item: Send,
+ {
+ FlatMapIter::new(self, map_op)
+ }
+
+ /// An adaptor that flattens parallel-iterable `Item`s into one large iterator.
+ ///
+ /// See also [`flatten_iter`](#method.flatten_iter).
///
/// # Examples
///
/// assert_eq!(y, vec![1, 2, 3, 4]);
/// ```
fn flatten(self) -> Flatten<Self>
- where Self::Item: IntoParallelIterator
+ where
+ Self::Item: IntoParallelIterator,
{
- flatten::new(self)
+ Flatten::new(self)
+ }
+
+ /// An adaptor that flattens serial-iterable `Item`s into one large iterator.
+ ///
+ /// See also [`flatten`](#method.flatten) and the analogous comparison of
+ /// [`flat_map_iter` versus `flat_map`](#flat_map_iter-versus-flat_map).
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let x: Vec<Vec<_>> = vec![vec![1, 2], vec![3, 4]];
+ /// let iters: Vec<_> = x.into_iter().map(Vec::into_iter).collect();
+ /// let y: Vec<_> = iters.into_par_iter().flatten_iter().collect();
+ ///
+ /// assert_eq!(y, vec![1, 2, 3, 4]);
+ /// ```
+ fn flatten_iter(self) -> FlattenIter<Self>
+ where
+ Self::Item: IntoIterator,
+ <Self::Item as IntoIterator>::Item: Send,
+ {
+ FlattenIter::new(self)
}
/// Reduces the items in the iterator into one item using `op`.
///
/// [associative]: https://en.wikipedia.org/wiki/Associative_property
fn reduce<OP, ID>(self, identity: ID, op: OP) -> Self::Item
- where OP: Fn(Self::Item, Self::Item) -> Self::Item + Sync + Send,
- ID: Fn() -> Self::Item + Sync + Send
+ where
+ OP: Fn(Self::Item, Self::Item) -> Self::Item + Sync + Send,
+ ID: Fn() -> Self::Item + Sync + Send,
{
reduce::reduce(self, identity, op)
}
///
/// [associative]: https://en.wikipedia.org/wiki/Associative_property
fn reduce_with<OP>(self, op: OP) -> Option<Self::Item>
- where OP: Fn(Self::Item, Self::Item) -> Self::Item + Sync + Send
+ where
+ OP: Fn(Self::Item, Self::Item) -> Self::Item + Sync + Send,
{
- self.fold(|| None, |opt_a, b| match opt_a {
+ fn opt_fold<T>(op: impl Fn(T, T) -> T) -> impl Fn(Option<T>, T) -> Option<T> {
+ move |opt_a, b| match opt_a {
Some(a) => Some(op(a, b)),
None => Some(b),
- })
- .reduce(|| None, |opt_a, opt_b| match (opt_a, opt_b) {
+ }
+ }
+
+ fn opt_reduce<T>(op: impl Fn(T, T) -> T) -> impl Fn(Option<T>, Option<T>) -> Option<T> {
+ move |opt_a, opt_b| match (opt_a, opt_b) {
(Some(a), Some(b)) => Some(op(a, b)),
(Some(v), None) | (None, Some(v)) => Some(v),
(None, None) => None,
- })
+ }
+ }
+
+ self.fold(<_>::default, opt_fold(&op))
+ .reduce(<_>::default, opt_reduce(&op))
+ }
+
+ /// Reduces the items in the iterator into one item using a fallible `op`.
+ /// The `identity` argument is used the same way as in [`reduce()`].
+ ///
+ /// [`reduce()`]: #method.reduce
+ ///
+ /// If a `Result::Err` or `Option::None` item is found, or if `op` reduces
+ /// to one, we will attempt to stop processing the rest of the items in the
+ /// iterator as soon as possible, and we will return that terminating value.
+ /// Otherwise, we will return the final reduced `Result::Ok(T)` or
+ /// `Option::Some(T)`. If there are multiple errors in parallel, it is not
+ /// specified which will be returned.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// // Compute the sum of squares, being careful about overflow.
+ /// fn sum_squares<I: IntoParallelIterator<Item = i32>>(iter: I) -> Option<i32> {
+ /// iter.into_par_iter()
+ /// .map(|i| i.checked_mul(i)) // square each item,
+ /// .try_reduce(|| 0, i32::checked_add) // and add them up!
+ /// }
+ /// assert_eq!(sum_squares(0..5), Some(0 + 1 + 4 + 9 + 16));
+ ///
+ /// // The sum might overflow
+ /// assert_eq!(sum_squares(0..10_000), None);
+ ///
+ /// // Or the squares might overflow before it even reaches `try_reduce`
+ /// assert_eq!(sum_squares(1_000_000..1_000_001), None);
+ /// ```
+ fn try_reduce<T, OP, ID>(self, identity: ID, op: OP) -> Self::Item
+ where
+ OP: Fn(T, T) -> Self::Item + Sync + Send,
+ ID: Fn() -> T + Sync + Send,
+ Self::Item: Try<Output = T>,
+ {
+ try_reduce::try_reduce(self, identity, op)
+ }
+
+ /// Reduces the items in the iterator into one item using a fallible `op`.
+ ///
+ /// Like [`reduce_with()`], if the iterator is empty, `None` is returned;
+ /// otherwise, `Some` is returned. Beyond that, it behaves like
+ /// [`try_reduce()`] for handling `Err`/`None`.
+ ///
+ /// [`reduce_with()`]: #method.reduce_with
+ /// [`try_reduce()`]: #method.try_reduce
+ ///
+ /// For instance, with `Option` items, the return value may be:
+ /// - `None`, the iterator was empty
+ /// - `Some(None)`, we stopped after encountering `None`.
+ /// - `Some(Some(x))`, the entire iterator reduced to `x`.
+ ///
+ /// With `Result` items, the nesting is more obvious:
+ /// - `None`, the iterator was empty
+ /// - `Some(Err(e))`, we stopped after encountering an error `e`.
+ /// - `Some(Ok(x))`, the entire iterator reduced to `x`.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let files = ["/dev/null", "/does/not/exist"];
+ ///
+ /// // Find the biggest file
+ /// files.into_par_iter()
+ /// .map(|path| std::fs::metadata(path).map(|m| (path, m.len())))
+ /// .try_reduce_with(|a, b| {
+ /// Ok(if a.1 >= b.1 { a } else { b })
+ /// })
+ /// .expect("Some value, since the iterator is not empty")
+ /// .expect_err("not found");
+ /// ```
+ fn try_reduce_with<T, OP>(self, op: OP) -> Option<Self::Item>
+ where
+ OP: Fn(T, T) -> Self::Item + Sync + Send,
+ Self::Item: Try<Output = T>,
+ {
+ try_reduce_with::try_reduce_with(self, op)
}
/// Parallel fold is similar to sequential fold except that the
/// assert_eq!(sum, (0..22).sum()); // compare to sequential
/// ```
fn fold<T, ID, F>(self, identity: ID, fold_op: F) -> Fold<Self, ID, F>
- where F: Fn(T, Self::Item) -> T + Sync + Send,
- ID: Fn() -> T + Sync + Send,
- T: Send
+ where
+ F: Fn(T, Self::Item) -> T + Sync + Send,
+ ID: Fn() -> T + Sync + Send,
+ T: Send,
{
- fold::fold(self, identity, fold_op)
+ Fold::new(self, identity, fold_op)
}
/// Applies `fold_op` to the given `init` value with each item of this
/// assert_eq!(sum, (0..22).sum()); // compare to sequential
/// ```
fn fold_with<F, T>(self, init: T, fold_op: F) -> FoldWith<Self, T, F>
- where F: Fn(T, Self::Item) -> T + Sync + Send,
- T: Send + Clone
+ where
+ F: Fn(T, Self::Item) -> T + Sync + Send,
+ T: Send + Clone,
{
- fold::fold_with(self, init, fold_op)
+ FoldWith::new(self, init, fold_op)
+ }
+
+ /// Performs a fallible parallel fold.
+ ///
+ /// This is a variation of [`fold()`] for operations which can fail with
+ /// `Option::None` or `Result::Err`. The first such failure stops
+ /// processing the local set of items, without affecting other folds in the
+ /// iterator's subdivisions.
+ ///
+ /// Often, `try_fold()` will be followed by [`try_reduce()`]
+ /// for a final reduction and global short-circuiting effect.
+ ///
+ /// [`fold()`]: #method.fold
+ /// [`try_reduce()`]: #method.try_reduce
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let bytes = 0..22_u8;
+ /// let sum = bytes.into_par_iter()
+ /// .try_fold(|| 0_u32, |a: u32, b: u8| a.checked_add(b as u32))
+ /// .try_reduce(|| 0, u32::checked_add);
+ ///
+ /// assert_eq!(sum, Some((0..22).sum())); // compare to sequential
+ /// ```
+ fn try_fold<T, R, ID, F>(self, identity: ID, fold_op: F) -> TryFold<Self, R, ID, F>
+ where
+ F: Fn(T, Self::Item) -> R + Sync + Send,
+ ID: Fn() -> T + Sync + Send,
+ R: Try<Output = T> + Send,
+ {
+ TryFold::new(self, identity, fold_op)
+ }
+
+ /// Performs a fallible parallel fold with a cloneable `init` value.
+ ///
+ /// This combines the `init` semantics of [`fold_with()`] and the failure
+ /// semantics of [`try_fold()`].
+ ///
+ /// [`fold_with()`]: #method.fold_with
+ /// [`try_fold()`]: #method.try_fold
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let bytes = 0..22_u8;
+ /// let sum = bytes.into_par_iter()
+ /// .try_fold_with(0_u32, |a: u32, b: u8| a.checked_add(b as u32))
+ /// .try_reduce(|| 0, u32::checked_add);
+ ///
+ /// assert_eq!(sum, Some((0..22).sum())); // compare to sequential
+ /// ```
+ fn try_fold_with<F, T, R>(self, init: T, fold_op: F) -> TryFoldWith<Self, R, F>
+ where
+ F: Fn(T, Self::Item) -> R + Sync + Send,
+ R: Try<Output = T> + Send,
+ T: Clone + Send,
+ {
+ TryFoldWith::new(self, init, fold_op)
}
/// Sums up the items in the iterator.
/// assert_eq!(sum, 13);
/// ```
fn sum<S>(self) -> S
- where S: Send + Sum<Self::Item> + Sum<S>
+ where
+ S: Send + Sum<Self::Item> + Sum<S>,
{
sum::sum(self)
}
/// assert_eq!(factorial(5), 120);
/// ```
fn product<P>(self) -> P
- where P: Send + Product<Self::Item> + Product<P>
+ where
+ P: Send + Product<Self::Item> + Product<P>,
{
product::product(self)
}
/// assert_eq!(b.par_iter().min(), None);
/// ```
fn min(self) -> Option<Self::Item>
- where Self::Item: Ord
+ where
+ Self::Item: Ord,
{
self.reduce_with(cmp::min)
}
/// assert_eq!(a.par_iter().min_by(|x, y| x.cmp(y)), Some(&-3));
/// ```
fn min_by<F>(self, f: F) -> Option<Self::Item>
- where F: Sync + Send + Fn(&Self::Item, &Self::Item) -> Ordering
+ where
+ F: Sync + Send + Fn(&Self::Item, &Self::Item) -> Ordering,
{
- self.reduce_with(|a, b| match f(&a, &b) {
- Ordering::Greater => b,
- _ => a,
- })
+ fn min<T>(f: impl Fn(&T, &T) -> Ordering) -> impl Fn(T, T) -> T {
+ move |a, b| match f(&a, &b) {
+ Ordering::Greater => b,
+ _ => a,
+ }
+ }
+
+ self.reduce_with(min(f))
}
/// Computes the item that yields the minimum value for the given
/// assert_eq!(a.par_iter().min_by_key(|x| x.abs()), Some(&2));
/// ```
fn min_by_key<K, F>(self, f: F) -> Option<Self::Item>
- where K: Ord + Send,
- F: Sync + Send + Fn(&Self::Item) -> K
+ where
+ K: Ord + Send,
+ F: Sync + Send + Fn(&Self::Item) -> K,
{
- self.map(|x| (f(&x), x))
- .min_by(|a, b| (a.0).cmp(&b.0))
- .map(|(_, x)| x)
+ fn key<T, K>(f: impl Fn(&T) -> K) -> impl Fn(T) -> (K, T) {
+ move |x| (f(&x), x)
+ }
+
+ fn min_key<T, K: Ord>(a: (K, T), b: (K, T)) -> (K, T) {
+ match (a.0).cmp(&b.0) {
+ Ordering::Greater => b,
+ _ => a,
+ }
+ }
+
+ let (_, x) = self.map(key(f)).reduce_with(min_key)?;
+ Some(x)
}
/// Computes the maximum of all the items in the iterator. If the
/// assert_eq!(b.par_iter().max(), None);
/// ```
fn max(self) -> Option<Self::Item>
- where Self::Item: Ord
+ where
+ Self::Item: Ord,
{
self.reduce_with(cmp::max)
}
/// assert_eq!(a.par_iter().max_by(|x, y| x.abs().cmp(&y.abs())), Some(&240));
/// ```
fn max_by<F>(self, f: F) -> Option<Self::Item>
- where F: Sync + Send + Fn(&Self::Item, &Self::Item) -> Ordering
+ where
+ F: Sync + Send + Fn(&Self::Item, &Self::Item) -> Ordering,
{
- self.reduce_with(|a, b| match f(&a, &b) {
- Ordering::Greater => a,
- _ => b,
- })
+ fn max<T>(f: impl Fn(&T, &T) -> Ordering) -> impl Fn(T, T) -> T {
+ move |a, b| match f(&a, &b) {
+ Ordering::Greater => a,
+ _ => b,
+ }
+ }
+
+ self.reduce_with(max(f))
}
/// Computes the item that yields the maximum value for the given
/// assert_eq!(a.par_iter().max_by_key(|x| x.abs()), Some(&34));
/// ```
fn max_by_key<K, F>(self, f: F) -> Option<Self::Item>
- where K: Ord + Send,
- F: Sync + Send + Fn(&Self::Item) -> K
+ where
+ K: Ord + Send,
+ F: Sync + Send + Fn(&Self::Item) -> K,
{
- self.map(|x| (f(&x), x))
- .max_by(|a, b| (a.0).cmp(&b.0))
- .map(|(_, x)| x)
+ fn key<T, K>(f: impl Fn(&T) -> K) -> impl Fn(T) -> (K, T) {
+ move |x| (f(&x), x)
+ }
+
+ fn max_key<T, K: Ord>(a: (K, T), b: (K, T)) -> (K, T) {
+ match (a.0).cmp(&b.0) {
+ Ordering::Greater => a,
+ _ => b,
+ }
+ }
+
+ let (_, x) = self.map(key(f)).reduce_with(max_key)?;
+ Some(x)
}
/// Takes two iterators and creates a new iterator over both.
/// assert_eq!(&chained[..], &[0, 1, 2, 9, 8, 7]);
/// ```
fn chain<C>(self, chain: C) -> Chain<Self, C::Iter>
- where C: IntoParallelIterator<Item = Self::Item>
+ where
+ C: IntoParallelIterator<Item = Self::Item>,
{
- chain::new(self, chain.into_par_iter())
+ Chain::new(self, chain.into_par_iter())
}
/// Searches for **some** item in the parallel iterator that
/// assert_eq!(a.par_iter().find_any(|&&x| x == 100), None);
/// ```
fn find_any<P>(self, predicate: P) -> Option<Self::Item>
- where P: Fn(&Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(&Self::Item) -> bool + Sync + Send,
{
find::find(self, predicate)
}
/// just want the first match that discovered anywhere in the iterator,
/// `find_any` is a better choice.
///
- /// # Exmaples
+ /// # Examples
///
/// ```
/// use rayon::prelude::*;
/// assert_eq!(a.par_iter().find_first(|&&x| x == 100), None);
/// ```
fn find_first<P>(self, predicate: P) -> Option<Self::Item>
- where P: Fn(&Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(&Self::Item) -> bool + Sync + Send,
{
find_first_last::find_first(self, predicate)
}
/// assert_eq!(a.par_iter().find_last(|&&x| x == 100), None);
/// ```
fn find_last<P>(self, predicate: P) -> Option<Self::Item>
- where P: Fn(&Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(&Self::Item) -> bool + Sync + Send,
{
find_first_last::find_last(self, predicate)
}
+ /// Applies the given predicate to the items in the parallel iterator
+ /// and returns **any** non-None result of the map operation.
+ ///
+ /// Once a non-None value is produced from the map operation, we will
+ /// attempt to stop processing the rest of the items in the iterator
+ /// as soon as possible.
+ ///
+ /// Note that this method only returns **some** item in the parallel
+ /// iterator that is not None from the map predicate. The item returned
+ /// may not be the **first** non-None value produced in the parallel
+ /// sequence, since the entire sequence is mapped over in parallel.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let c = ["lol", "NaN", "5", "5"];
+ ///
+ /// let found_number = c.par_iter().find_map_any(|s| s.parse().ok());
+ ///
+ /// assert_eq!(found_number, Some(5));
+ /// ```
+ fn find_map_any<P, R>(self, predicate: P) -> Option<R>
+ where
+ P: Fn(Self::Item) -> Option<R> + Sync + Send,
+ R: Send,
+ {
+ fn yes<T>(_: &T) -> bool {
+ true
+ }
+ self.filter_map(predicate).find_any(yes)
+ }
+
+ /// Applies the given predicate to the items in the parallel iterator and
+ /// returns the sequentially **first** non-None result of the map operation.
+ ///
+ /// Once a non-None value is produced from the map operation, all attempts
+ /// to the right of the match will be stopped, while attempts to the left
+ /// must continue in case an earlier match is found.
+ ///
+ /// Note that not all parallel iterators have a useful order, much like
+ /// sequential `HashMap` iteration, so "first" may be nebulous. If you
+ /// just want the first non-None value discovered anywhere in the iterator,
+ /// `find_map_any` is a better choice.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let c = ["lol", "NaN", "2", "5"];
+ ///
+ /// let first_number = c.par_iter().find_map_first(|s| s.parse().ok());
+ ///
+ /// assert_eq!(first_number, Some(2));
+ /// ```
+ fn find_map_first<P, R>(self, predicate: P) -> Option<R>
+ where
+ P: Fn(Self::Item) -> Option<R> + Sync + Send,
+ R: Send,
+ {
+ fn yes<T>(_: &T) -> bool {
+ true
+ }
+ self.filter_map(predicate).find_first(yes)
+ }
+
+ /// Applies the given predicate to the items in the parallel iterator and
+ /// returns the sequentially **last** non-None result of the map operation.
+ ///
+ /// Once a non-None value is produced from the map operation, all attempts
+ /// to the left of the match will be stopped, while attempts to the right
+ /// must continue in case a later match is found.
+ ///
+ /// Note that not all parallel iterators have a useful order, much like
+ /// sequential `HashMap` iteration, so "first" may be nebulous. If you
+ /// just want the first non-None value discovered anywhere in the iterator,
+ /// `find_map_any` is a better choice.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let c = ["lol", "NaN", "2", "5"];
+ ///
+ /// let last_number = c.par_iter().find_map_last(|s| s.parse().ok());
+ ///
+ /// assert_eq!(last_number, Some(5));
+ /// ```
+ fn find_map_last<P, R>(self, predicate: P) -> Option<R>
+ where
+ P: Fn(Self::Item) -> Option<R> + Sync + Send,
+ R: Send,
+ {
+ fn yes<T>(_: &T) -> bool {
+ true
+ }
+ self.filter_map(predicate).find_last(yes)
+ }
+
#[doc(hidden)]
#[deprecated(note = "parallel `find` does not search in order -- use `find_any`, \\
- `find_first`, or `find_last`")]
+ `find_first`, or `find_last`")]
fn find<P>(self, predicate: P) -> Option<Self::Item>
- where P: Fn(&Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(&Self::Item) -> bool + Sync + Send,
{
self.find_any(predicate)
}
/// assert!(is_valid);
/// ```
fn any<P>(self, predicate: P) -> bool
- where P: Fn(Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(Self::Item) -> bool + Sync + Send,
{
- self.map(predicate).find_any(|&p| p).is_some()
+ self.map(predicate).find_any(bool::clone).is_some()
}
/// Tests that every item in the parallel iterator matches the given
/// assert!(!is_valid);
/// ```
fn all<P>(self, predicate: P) -> bool
- where P: Fn(Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(Self::Item) -> bool + Sync + Send,
{
- self.map(predicate).find_any(|&p| !p).is_none()
+ #[inline]
+ fn is_false(x: &bool) -> bool {
+ !x
+ }
+
+ self.map(predicate).find_any(is_false).is_none()
}
/// Creates an iterator over the `Some` items of this iterator, halting
/// assert!(counter.load(Ordering::SeqCst) < 2048); // should not have visited every single one
/// ```
fn while_some<T>(self) -> WhileSome<Self>
- where Self: ParallelIterator<Item = Option<T>>,
- T: Send
+ where
+ Self: ParallelIterator<Item = Option<T>>,
+ T: Send,
{
- while_some::new(self)
+ WhileSome::new(self)
}
- /// Create a fresh collection containing all the element produced
+ /// Wraps an iterator with a fuse in case of panics, to halt all threads
+ /// as soon as possible.
+ ///
+ /// Panics within parallel iterators are always propagated to the caller,
+ /// but they don't always halt the rest of the iterator right away, due to
+ /// the internal semantics of [`join`]. This adaptor makes a greater effort
+ /// to stop processing other items sooner, with the cost of additional
+ /// synchronization overhead, which may also inhibit some optimizations.
+ ///
+ /// [`join`]: ../fn.join.html#panics
+ ///
+ /// # Examples
+ ///
+ /// If this code didn't use `panic_fuse()`, it would continue processing
+ /// many more items in other threads (with long sleep delays) before the
+ /// panic is finally propagated.
+ ///
+ /// ```should_panic
+ /// use rayon::prelude::*;
+ /// use std::{thread, time};
+ ///
+ /// (0..1_000_000)
+ /// .into_par_iter()
+ /// .panic_fuse()
+ /// .for_each(|i| {
+ /// // simulate some work
+ /// thread::sleep(time::Duration::from_secs(1));
+ /// assert!(i > 0); // oops!
+ /// });
+ /// ```
+ fn panic_fuse(self) -> PanicFuse<Self> {
+ PanicFuse::new(self)
+ }
+
+ /// Creates a fresh collection containing all the elements produced
/// by this parallel iterator.
///
- /// You may prefer to use `collect_into_vec()`, which allocates more
- /// efficiently with precise knowledge of how many elements the
- /// iterator contains, and even allows you to reuse an existing
- /// vector's backing store rather than allocating a fresh vector.
+ /// You may prefer [`collect_into_vec()`] implemented on
+ /// [`IndexedParallelIterator`], if your underlying iterator also implements
+ /// it. [`collect_into_vec()`] allocates efficiently with precise knowledge
+ /// of how many elements the iterator contains, and even allows you to reuse
+ /// an existing vector's backing store rather than allocating a fresh vector.
+ ///
+ /// [`IndexedParallelIterator`]: trait.IndexedParallelIterator.html
+ /// [`collect_into_vec()`]:
+ /// trait.IndexedParallelIterator.html#method.collect_into_vec
///
/// # Examples
///
///
/// assert_eq!(sync_vec, async_vec);
/// ```
+ ///
+ /// You can collect a pair of collections like [`unzip`](#method.unzip)
+ /// for paired items:
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let a = [(0, 1), (1, 2), (2, 3), (3, 4)];
+ /// let (first, second): (Vec<_>, Vec<_>) = a.into_par_iter().collect();
+ ///
+ /// assert_eq!(first, [0, 1, 2, 3]);
+ /// assert_eq!(second, [1, 2, 3, 4]);
+ /// ```
+ ///
+ /// Or like [`partition_map`](#method.partition_map) for `Either` items:
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ /// use rayon::iter::Either;
+ ///
+ /// let (left, right): (Vec<_>, Vec<_>) = (0..8).into_par_iter().map(|x| {
+ /// if x % 2 == 0 {
+ /// Either::Left(x * 4)
+ /// } else {
+ /// Either::Right(x * 3)
+ /// }
+ /// }).collect();
+ ///
+ /// assert_eq!(left, [0, 8, 16, 24]);
+ /// assert_eq!(right, [3, 9, 15, 21]);
+ /// ```
+ ///
+ /// You can even collect an arbitrarily-nested combination of pairs and `Either`:
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ /// use rayon::iter::Either;
+ ///
+ /// let (first, (left, right)): (Vec<_>, (Vec<_>, Vec<_>))
+ /// = (0..8).into_par_iter().map(|x| {
+ /// if x % 2 == 0 {
+ /// (x, Either::Left(x * 4))
+ /// } else {
+ /// (-x, Either::Right(x * 3))
+ /// }
+ /// }).collect();
+ ///
+ /// assert_eq!(first, [0, -1, 2, -3, 4, -5, 6, -7]);
+ /// assert_eq!(left, [0, 8, 16, 24]);
+ /// assert_eq!(right, [3, 9, 15, 21]);
+ /// ```
+ ///
+ /// All of that can _also_ be combined with short-circuiting collection of
+ /// `Result` or `Option` types:
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ /// use rayon::iter::Either;
+ ///
+ /// let result: Result<(Vec<_>, (Vec<_>, Vec<_>)), _>
+ /// = (0..8).into_par_iter().map(|x| {
+ /// if x > 5 {
+ /// Err(x)
+ /// } else if x % 2 == 0 {
+ /// Ok((x, Either::Left(x * 4)))
+ /// } else {
+ /// Ok((-x, Either::Right(x * 3)))
+ /// }
+ /// }).collect();
+ ///
+ /// let error = result.unwrap_err();
+ /// assert!(error == 6 || error == 7);
+ /// ```
fn collect<C>(self) -> C
- where C: FromParallelIterator<Self::Item>
+ where
+ C: FromParallelIterator<Self::Item>,
{
C::from_par_iter(self)
}
/// assert_eq!(left, [0, 1, 2, 3]);
/// assert_eq!(right, [1, 2, 3, 4]);
/// ```
+ ///
+ /// Nested pairs can be unzipped too.
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let (values, (squares, cubes)): (Vec<_>, (Vec<_>, Vec<_>)) = (0..4).into_par_iter()
+ /// .map(|i| (i, (i * i, i * i * i)))
+ /// .unzip();
+ ///
+ /// assert_eq!(values, [0, 1, 2, 3]);
+ /// assert_eq!(squares, [0, 1, 4, 9]);
+ /// assert_eq!(cubes, [0, 1, 8, 27]);
+ /// ```
fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)
- where Self: ParallelIterator<Item = (A, B)>,
- FromA: Default + Send + ParallelExtend<A>,
- FromB: Default + Send + ParallelExtend<B>,
- A: Send,
- B: Send
+ where
+ Self: ParallelIterator<Item = (A, B)>,
+ FromA: Default + Send + ParallelExtend<A>,
+ FromB: Default + Send + ParallelExtend<B>,
+ A: Send,
+ B: Send,
{
unzip::unzip(self)
}
/// Note: unlike the standard `Iterator::partition`, this allows distinct
/// collection types for the left and right items. This is more flexible,
/// but may require new type annotations when converting sequential code
- /// that used type inferrence assuming the two were the same.
+ /// that used type inference assuming the two were the same.
///
/// # Examples
///
/// assert_eq!(right, [1, 3, 5, 7]);
/// ```
fn partition<A, B, P>(self, predicate: P) -> (A, B)
- where A: Default + Send + ParallelExtend<Self::Item>,
- B: Default + Send + ParallelExtend<Self::Item>,
- P: Fn(&Self::Item) -> bool + Sync + Send
+ where
+ A: Default + Send + ParallelExtend<Self::Item>,
+ B: Default + Send + ParallelExtend<Self::Item>,
+ P: Fn(&Self::Item) -> bool + Sync + Send,
{
unzip::partition(self, predicate)
}
/// use rayon::iter::Either;
///
/// let (left, right): (Vec<_>, Vec<_>) = (0..8).into_par_iter()
- /// .partition_map(|x| {
- /// if x % 2 == 0 {
- /// Either::Left(x * 4)
- /// } else {
- /// Either::Right(x * 3)
- /// }
- /// });
+ /// .partition_map(|x| {
+ /// if x % 2 == 0 {
+ /// Either::Left(x * 4)
+ /// } else {
+ /// Either::Right(x * 3)
+ /// }
+ /// });
///
/// assert_eq!(left, [0, 8, 16, 24]);
/// assert_eq!(right, [3, 9, 15, 21]);
/// ```
+ ///
+ /// Nested `Either` enums can be split as well.
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ /// use rayon::iter::Either::*;
+ ///
+ /// let ((fizzbuzz, fizz), (buzz, other)): ((Vec<_>, Vec<_>), (Vec<_>, Vec<_>)) = (1..20)
+ /// .into_par_iter()
+ /// .partition_map(|x| match (x % 3, x % 5) {
+ /// (0, 0) => Left(Left(x)),
+ /// (0, _) => Left(Right(x)),
+ /// (_, 0) => Right(Left(x)),
+ /// (_, _) => Right(Right(x)),
+ /// });
+ ///
+ /// assert_eq!(fizzbuzz, [15]);
+ /// assert_eq!(fizz, [3, 6, 9, 12, 18]);
+ /// assert_eq!(buzz, [5, 10]);
+ /// assert_eq!(other, [1, 2, 4, 7, 8, 11, 13, 14, 16, 17, 19]);
+ /// ```
fn partition_map<A, B, P, L, R>(self, predicate: P) -> (A, B)
- where A: Default + Send + ParallelExtend<L>,
- B: Default + Send + ParallelExtend<R>,
- P: Fn(Self::Item) -> Either<L, R> + Sync + Send,
- L: Send,
- R: Send
+ where
+ A: Default + Send + ParallelExtend<L>,
+ B: Default + Send + ParallelExtend<R>,
+ P: Fn(Self::Item) -> Either<L, R> + Sync + Send,
+ L: Send,
+ R: Send,
{
unzip::partition_map(self, predicate)
}
/// assert_eq!(r, vec![1, -1, 2, -1, 3]);
/// ```
fn intersperse(self, element: Self::Item) -> Intersperse<Self>
- where Self::Item: Clone
+ where
+ Self::Item: Clone,
{
- intersperse::new(self, element)
+ Intersperse::new(self, element)
}
/// Internal method used to define the behavior of this parallel
/// See the [README] for more details on the internals of parallel
/// iterators.
///
- /// [README]: README.md
- fn drive_unindexed<C>(self, consumer: C) -> C::Result where C: UnindexedConsumer<Self::Item>;
-
+ /// [README]: https://github.com/rayon-rs/rayon/blob/master/src/iter/plumbing/README.md
+ fn drive_unindexed<C>(self, consumer: C) -> C::Result
+ where
+ C: UnindexedConsumer<Self::Item>;
/// Internal method used to define the behavior of this parallel
/// iterator. You should not need to call this directly.
/// that you can split it at arbitrary indices and draw data from
/// those points.
///
-/// **Note:** Not implemented for `u64` and `i64` ranges
+/// **Note:** Not implemented for `u64`, `i64`, `u128`, or `i128` ranges
pub trait IndexedParallelIterator: ParallelIterator {
/// Collects the results of the iterator into the specified
/// vector. The vector is always truncated before execution
/// assert_eq!(right, [10, 11, 12, 13, 14]);
/// ```
fn unzip_into_vecs<A, B>(self, left: &mut Vec<A>, right: &mut Vec<B>)
- where Self: IndexedParallelIterator<Item = (A, B)>,
- A: Send,
- B: Send
+ where
+ Self: IndexedParallelIterator<Item = (A, B)>,
+ A: Send,
+ B: Send,
{
collect::unzip_into_vecs(self, left, right);
}
- /// Iterate over tuples `(A, B)`, where the items `A` are from
+ /// Iterates over tuples `(A, B)`, where the items `A` are from
/// this iterator and `B` are from the iterator given as argument.
/// Like the `zip` method on ordinary iterators, if the two
/// iterators are of unequal length, you only get the items they
/// assert_eq!(result, [(1, 'a'), (2, 'b'), (3, 'c')]);
/// ```
fn zip<Z>(self, zip_op: Z) -> Zip<Self, Z::Iter>
- where Z: IntoParallelIterator,
- Z::Iter: IndexedParallelIterator
+ where
+ Z: IntoParallelIterator,
+ Z::Iter: IndexedParallelIterator,
{
- zip::new(self, zip_op.into_par_iter())
+ Zip::new(self, zip_op.into_par_iter())
}
/// The same as `Zip`, but requires that both iterators have the same length.
/// assert_eq!(1, zipped.len());
/// ```
fn zip_eq<Z>(self, zip_op: Z) -> ZipEq<Self, Z::Iter>
- where Z: IntoParallelIterator,
- Z::Iter: IndexedParallelIterator
+ where
+ Z: IntoParallelIterator,
+ Z::Iter: IndexedParallelIterator,
{
let zip_op_iter = zip_op.into_par_iter();
assert_eq!(self.len(), zip_op_iter.len());
- zip_eq::new(self, zip_op_iter)
+ ZipEq::new(self, zip_op_iter)
}
- /// Interleave elements of this iterator and the other given
+ /// Interleaves elements of this iterator and the other given
/// iterator. Alternately yields elements from this iterator and
/// the given iterator, until both are exhausted. If one iterator
/// is exhausted before the other, the last elements are provided
/// assert_eq!(r, vec![1, 3, 2, 4, 5, 6]);
/// ```
fn interleave<I>(self, other: I) -> Interleave<Self, I::Iter>
- where I: IntoParallelIterator<Item = Self::Item>,
- I::Iter: IndexedParallelIterator<Item = Self::Item>
+ where
+ I: IntoParallelIterator<Item = Self::Item>,
+ I::Iter: IndexedParallelIterator<Item = Self::Item>,
{
- interleave::new(self, other.into_par_iter())
+ Interleave::new(self, other.into_par_iter())
}
- /// Interleave elements of this iterator and the other given
+ /// Interleaves elements of this iterator and the other given
/// iterator, until one is exhausted.
///
/// # Examples
/// assert_eq!(r, vec![1, 5, 2, 6, 3]);
/// ```
fn interleave_shortest<I>(self, other: I) -> InterleaveShortest<Self, I::Iter>
- where I: IntoParallelIterator<Item = Self::Item>,
- I::Iter: IndexedParallelIterator<Item = Self::Item>
+ where
+ I: IntoParallelIterator<Item = Self::Item>,
+ I::Iter: IndexedParallelIterator<Item = Self::Item>,
{
- interleave_shortest::new(self, other.into_par_iter())
+ InterleaveShortest::new(self, other.into_par_iter())
}
- /// Split an iterator up into fixed-size chunks.
+ /// Splits an iterator up into fixed-size chunks.
///
/// Returns an iterator that returns `Vec`s of the given number of elements.
/// If the number of elements in the iterator is not divisible by `chunk_size`,
/// ```
fn chunks(self, chunk_size: usize) -> Chunks<Self> {
assert!(chunk_size != 0, "chunk_size must not be zero");
- chunks::new(self, chunk_size)
+ Chunks::new(self, chunk_size)
}
/// Lexicographically compares the elements of this `ParallelIterator` with those of
/// assert_eq!(x.par_iter().cmp(&vec![1, 2]), Greater);
/// ```
fn cmp<I>(self, other: I) -> Ordering
- where I: IntoParallelIterator<Item = Self::Item>,
- I::Iter: IndexedParallelIterator,
- Self::Item: Ord
+ where
+ I: IntoParallelIterator<Item = Self::Item>,
+ I::Iter: IndexedParallelIterator,
+ Self::Item: Ord,
{
+ #[inline]
+ fn ordering<T: Ord>((x, y): (T, T)) -> Ordering {
+ Ord::cmp(&x, &y)
+ }
+
+ #[inline]
+ fn inequal(&ord: &Ordering) -> bool {
+ ord != Ordering::Equal
+ }
+
let other = other.into_par_iter();
let ord_len = self.len().cmp(&other.len());
self.zip(other)
- .map(|(x, y)| Ord::cmp(&x, &y))
- .find_first(|&ord| ord != Ordering::Equal)
+ .map(ordering)
+ .find_first(inequal)
.unwrap_or(ord_len)
}
/// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, NAN]), None);
/// ```
fn partial_cmp<I>(self, other: I) -> Option<Ordering>
- where I: IntoParallelIterator,
- I::Iter: IndexedParallelIterator,
- Self::Item: PartialOrd<I::Item>
+ where
+ I: IntoParallelIterator,
+ I::Iter: IndexedParallelIterator,
+ Self::Item: PartialOrd<I::Item>,
{
+ #[inline]
+ fn ordering<T: PartialOrd<U>, U>((x, y): (T, U)) -> Option<Ordering> {
+ PartialOrd::partial_cmp(&x, &y)
+ }
+
+ #[inline]
+ fn inequal(&ord: &Option<Ordering>) -> bool {
+ ord != Some(Ordering::Equal)
+ }
+
let other = other.into_par_iter();
let ord_len = self.len().cmp(&other.len());
self.zip(other)
- .map(|(x, y)| PartialOrd::partial_cmp(&x, &y))
- .find_first(|&ord| ord != Some(Ordering::Equal))
+ .map(ordering)
+ .find_first(inequal)
.unwrap_or(Some(ord_len))
}
/// Determines if the elements of this `ParallelIterator`
/// are equal to those of another
fn eq<I>(self, other: I) -> bool
- where I: IntoParallelIterator,
- I::Iter: IndexedParallelIterator,
- Self::Item: PartialEq<I::Item>
+ where
+ I: IntoParallelIterator,
+ I::Iter: IndexedParallelIterator,
+ Self::Item: PartialEq<I::Item>,
{
+ #[inline]
+ fn eq<T: PartialEq<U>, U>((x, y): (T, U)) -> bool {
+ PartialEq::eq(&x, &y)
+ }
+
let other = other.into_par_iter();
- self.len() == other.len() && self.zip(other).all(|(x, y)| x.eq(&y))
+ self.len() == other.len() && self.zip(other).all(eq)
}
/// Determines if the elements of this `ParallelIterator`
/// are unequal to those of another
fn ne<I>(self, other: I) -> bool
- where I: IntoParallelIterator,
- I::Iter: IndexedParallelIterator,
- Self::Item: PartialEq<I::Item>
+ where
+ I: IntoParallelIterator,
+ I::Iter: IndexedParallelIterator,
+ Self::Item: PartialEq<I::Item>,
{
!self.eq(other)
}
/// Determines if the elements of this `ParallelIterator`
/// are lexicographically less than those of another.
fn lt<I>(self, other: I) -> bool
- where I: IntoParallelIterator,
- I::Iter: IndexedParallelIterator,
- Self::Item: PartialOrd<I::Item>
+ where
+ I: IntoParallelIterator,
+ I::Iter: IndexedParallelIterator,
+ Self::Item: PartialOrd<I::Item>,
{
self.partial_cmp(other) == Some(Ordering::Less)
}
/// Determines if the elements of this `ParallelIterator`
/// are less or equal to those of another.
fn le<I>(self, other: I) -> bool
- where I: IntoParallelIterator,
- I::Iter: IndexedParallelIterator,
- Self::Item: PartialOrd<I::Item>
+ where
+ I: IntoParallelIterator,
+ I::Iter: IndexedParallelIterator,
+ Self::Item: PartialOrd<I::Item>,
{
let ord = self.partial_cmp(other);
ord == Some(Ordering::Equal) || ord == Some(Ordering::Less)
/// Determines if the elements of this `ParallelIterator`
/// are lexicographically greater than those of another.
fn gt<I>(self, other: I) -> bool
- where I: IntoParallelIterator,
- I::Iter: IndexedParallelIterator,
- Self::Item: PartialOrd<I::Item>
+ where
+ I: IntoParallelIterator,
+ I::Iter: IndexedParallelIterator,
+ Self::Item: PartialOrd<I::Item>,
{
self.partial_cmp(other) == Some(Ordering::Greater)
}
/// Determines if the elements of this `ParallelIterator`
/// are less or equal to those of another.
fn ge<I>(self, other: I) -> bool
- where I: IntoParallelIterator,
- I::Iter: IndexedParallelIterator,
- Self::Item: PartialOrd<I::Item>
+ where
+ I: IntoParallelIterator,
+ I::Iter: IndexedParallelIterator,
+ Self::Item: PartialOrd<I::Item>,
{
let ord = self.partial_cmp(other);
ord == Some(Ordering::Equal) || ord == Some(Ordering::Greater)
/// assert_eq!(result, [(0, 'a'), (1, 'b'), (2, 'c')]);
/// ```
fn enumerate(self) -> Enumerate<Self> {
- enumerate::new(self)
+ Enumerate::new(self)
+ }
+
+ /// Creates an iterator that steps by the given amount
+ ///
+ /// # Examples
+ ///
+ /// ```
+ ///use rayon::prelude::*;
+ ///
+ /// let range = (3..10);
+ /// let result: Vec<i32> = range
+ /// .into_par_iter()
+ /// .step_by(3)
+ /// .collect();
+ ///
+ /// assert_eq!(result, [3, 6, 9])
+ /// ```
+ ///
+ /// # Compatibility
+ ///
+ /// This method is only available on Rust 1.38 or greater.
+ #[cfg(has_step_by_rev)]
+ fn step_by(self, step: usize) -> StepBy<Self> {
+ StepBy::new(self, step)
}
/// Creates an iterator that skips the first `n` elements.
/// assert_eq!(result, [95, 96, 97, 98, 99]);
/// ```
fn skip(self, n: usize) -> Skip<Self> {
- skip::new(self, n)
+ Skip::new(self, n)
}
/// Creates an iterator that yields the first `n` elements.
/// assert_eq!(result, [0, 1, 2, 3, 4]);
/// ```
fn take(self, n: usize) -> Take<Self> {
- take::new(self, n)
+ Take::new(self, n)
}
/// Searches for **some** item in the parallel iterator that
/// assert_eq!(a.par_iter().position_any(|&x| x == 100), None);
/// ```
fn position_any<P>(self, predicate: P) -> Option<usize>
- where P: Fn(Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(Self::Item) -> bool + Sync + Send,
{
- self.map(predicate)
- .enumerate()
- .find_any(|&(_, p)| p)
- .map(|(i, _)| i)
+ #[inline]
+ fn check(&(_, p): &(usize, bool)) -> bool {
+ p
+ }
+
+ let (i, _) = self.map(predicate).enumerate().find_any(check)?;
+ Some(i)
}
/// Searches for the sequentially **first** item in the parallel iterator
/// assert_eq!(a.par_iter().position_first(|&x| x == 100), None);
/// ```
fn position_first<P>(self, predicate: P) -> Option<usize>
- where P: Fn(Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(Self::Item) -> bool + Sync + Send,
{
- self.map(predicate)
- .enumerate()
- .find_first(|&(_, p)| p)
- .map(|(i, _)| i)
+ #[inline]
+ fn check(&(_, p): &(usize, bool)) -> bool {
+ p
+ }
+
+ let (i, _) = self.map(predicate).enumerate().find_first(check)?;
+ Some(i)
}
/// Searches for the sequentially **last** item in the parallel iterator
/// assert_eq!(a.par_iter().position_last(|&x| x == 100), None);
/// ```
fn position_last<P>(self, predicate: P) -> Option<usize>
- where P: Fn(Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(Self::Item) -> bool + Sync + Send,
{
- self.map(predicate)
- .enumerate()
- .find_last(|&(_, p)| p)
- .map(|(i, _)| i)
+ #[inline]
+ fn check(&(_, p): &(usize, bool)) -> bool {
+ p
+ }
+
+ let (i, _) = self.map(predicate).enumerate().find_last(check)?;
+ Some(i)
}
#[doc(hidden)]
- #[deprecated(note = "parallel `position` does not search in order -- use `position_any`, \\
- `position_first`, or `position_last`")]
+ #[deprecated(
+ note = "parallel `position` does not search in order -- use `position_any`, \\
+ `position_first`, or `position_last`"
+ )]
fn position<P>(self, predicate: P) -> Option<usize>
- where P: Fn(Self::Item) -> bool + Sync + Send
+ where
+ P: Fn(Self::Item) -> bool + Sync + Send,
{
self.position_any(predicate)
}
+ /// Searches for items in the parallel iterator that match the given
+ /// predicate, and returns their indices.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let primes = vec![2, 3, 5, 7, 11, 13, 17, 19, 23, 29];
+ ///
+ /// // Find the positions of primes congruent to 1 modulo 6
+ /// let p1mod6: Vec<_> = primes.par_iter().positions(|&p| p % 6 == 1).collect();
+ /// assert_eq!(p1mod6, [3, 5, 7]); // primes 7, 13, and 19
+ ///
+ /// // Find the positions of primes congruent to 5 modulo 6
+ /// let p5mod6: Vec<_> = primes.par_iter().positions(|&p| p % 6 == 5).collect();
+ /// assert_eq!(p5mod6, [2, 4, 6, 8, 9]); // primes 5, 11, 17, 23, and 29
+ /// ```
+ fn positions<P>(self, predicate: P) -> Positions<Self, P>
+ where
+ P: Fn(Self::Item) -> bool + Sync + Send,
+ {
+ Positions::new(self, predicate)
+ }
+
/// Produces a new iterator with the elements of this iterator in
/// reverse order.
///
/// assert_eq!(result, [4, 3, 2, 1, 0]);
/// ```
fn rev(self) -> Rev<Self> {
- rev::new(self)
+ Rev::new(self)
}
/// Sets the minimum length of iterators desired to process in each
- /// thread. Rayon will not split any smaller than this length, but
+ /// rayon job. Rayon will not split any smaller than this length, but
/// of course an iterator could already be smaller to begin with.
///
/// Producers like `zip` and `interleave` will use greater of the two
/// assert!(min >= 1234);
/// ```
fn with_min_len(self, min: usize) -> MinLen<Self> {
- len::new_min_len(self, min)
+ MinLen::new(self, min)
}
/// Sets the maximum length of iterators desired to process in each
- /// thread. Rayon will try to split at least below this length,
+ /// rayon job. Rayon will try to split at least below this length,
/// unless that would put it below the length from `with_min_len()`.
/// For example, given min=10 and max=15, a length of 16 will not be
/// split any further.
/// assert!(max <= 1234);
/// ```
fn with_max_len(self, max: usize) -> MaxLen<Self> {
- len::new_max_len(self, max)
+ MaxLen::new(self, max)
}
/// Produces an exact count of how many items this iterator will
/// See the [README] for more details on the internals of parallel
/// iterators.
///
- /// [README]: README.md
+ /// [README]: https://github.com/rayon-rs/rayon/blob/master/src/iter/plumbing/README.md
fn drive<C: Consumer<Self::Item>>(self, consumer: C) -> C::Result;
/// Internal method used to define the behavior of this parallel
/// See the [README] for more details on the internals of parallel
/// iterators.
///
- /// [README]: README.md
+ /// [README]: https://github.com/rayon-rs/rayon/blob/master/src/iter/plumbing/README.md
fn with_producer<CB: ProducerCallback<Self::Item>>(self, callback: CB) -> CB::Output;
}
/// assert_eq!(bh.mass, 4000);
/// ```
pub trait FromParallelIterator<T>
- where T: Send
+where
+ T: Send,
{
/// Creates an instance of the collection from the parallel iterator `par_iter`.
///
/// [`par_iter.fold`]: trait.ParallelIterator.html#method.fold
/// [`par_iter.fold_with`]: trait.ParallelIterator.html#method.fold_with
/// [`par_iter.for_each`]: trait.ParallelIterator.html#method.for_each
- fn from_par_iter<I>(par_iter: I) -> Self where I: IntoParallelIterator<Item = T>;
+ fn from_par_iter<I>(par_iter: I) -> Self
+ where
+ I: IntoParallelIterator<Item = T>;
}
/// `ParallelExtend` extends an existing collection with items from a [`ParallelIterator`].
/// assert_eq!(bh.mass, 4080);
/// ```
pub trait ParallelExtend<T>
- where T: Send
+where
+ T: Send,
{
/// Extends an instance of the collection with the elements drawn
/// from the parallel iterator `par_iter`.
/// vec.par_extend((0..5).into_par_iter().map(|i| i * i));
/// assert_eq!(vec, [0, 1, 2, 3, 4, 0, 1, 4, 9, 16]);
/// ```
- fn par_extend<I>(&mut self, par_iter: I) where I: IntoParallelIterator<Item = T>;
+ fn par_extend<I>(&mut self, par_iter: I)
+ where
+ I: IntoParallelIterator<Item = T>;
+}
+
+/// `ParallelDrainFull` creates a parallel iterator that moves all items
+/// from a collection while retaining the original capacity.
+///
+/// Types which are indexable typically implement [`ParallelDrainRange`]
+/// instead, where you can drain fully with `par_drain(..)`.
+///
+/// [`ParallelDrainRange`]: trait.ParallelDrainRange.html
+pub trait ParallelDrainFull {
+ /// The draining parallel iterator type that will be created.
+ type Iter: ParallelIterator<Item = Self::Item>;
+
+ /// The type of item that the parallel iterator will produce.
+ /// This is usually the same as `IntoParallelIterator::Item`.
+ type Item: Send;
+
+ /// Returns a draining parallel iterator over an entire collection.
+ ///
+ /// When the iterator is dropped, all items are removed, even if the
+ /// iterator was not fully consumed. If the iterator is leaked, for example
+ /// using `std::mem::forget`, it is unspecified how many items are removed.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ /// use std::collections::{BinaryHeap, HashSet};
+ ///
+ /// let squares: HashSet<i32> = (0..10).map(|x| x * x).collect();
+ ///
+ /// let mut heap: BinaryHeap<_> = squares.iter().copied().collect();
+ /// assert_eq!(
+ /// // heaps are drained in arbitrary order
+ /// heap.par_drain()
+ /// .inspect(|x| assert!(squares.contains(x)))
+ /// .count(),
+ /// squares.len(),
+ /// );
+ /// assert!(heap.is_empty());
+ /// assert!(heap.capacity() >= squares.len());
+ /// ```
+ fn par_drain(self) -> Self::Iter;
+}
+
+/// `ParallelDrainRange` creates a parallel iterator that moves a range of items
+/// from a collection while retaining the original capacity.
+///
+/// Types which are not indexable may implement [`ParallelDrainFull`] instead.
+///
+/// [`ParallelDrainFull`]: trait.ParallelDrainFull.html
+pub trait ParallelDrainRange<Idx = usize> {
+ /// The draining parallel iterator type that will be created.
+ type Iter: ParallelIterator<Item = Self::Item>;
+
+ /// The type of item that the parallel iterator will produce.
+ /// This is usually the same as `IntoParallelIterator::Item`.
+ type Item: Send;
+
+ /// Returns a draining parallel iterator over a range of the collection.
+ ///
+ /// When the iterator is dropped, all items in the range are removed, even
+ /// if the iterator was not fully consumed. If the iterator is leaked, for
+ /// example using `std::mem::forget`, it is unspecified how many items are
+ /// removed.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use rayon::prelude::*;
+ ///
+ /// let squares: Vec<i32> = (0..10).map(|x| x * x).collect();
+ ///
+ /// println!("RangeFull");
+ /// let mut vec = squares.clone();
+ /// assert!(vec.par_drain(..)
+ /// .eq(squares.par_iter().copied()));
+ /// assert!(vec.is_empty());
+ /// assert!(vec.capacity() >= squares.len());
+ ///
+ /// println!("RangeFrom");
+ /// let mut vec = squares.clone();
+ /// assert!(vec.par_drain(5..)
+ /// .eq(squares[5..].par_iter().copied()));
+ /// assert_eq!(&vec[..], &squares[..5]);
+ /// assert!(vec.capacity() >= squares.len());
+ ///
+ /// println!("RangeTo");
+ /// let mut vec = squares.clone();
+ /// assert!(vec.par_drain(..5)
+ /// .eq(squares[..5].par_iter().copied()));
+ /// assert_eq!(&vec[..], &squares[5..]);
+ /// assert!(vec.capacity() >= squares.len());
+ ///
+ /// println!("RangeToInclusive");
+ /// let mut vec = squares.clone();
+ /// assert!(vec.par_drain(..=5)
+ /// .eq(squares[..=5].par_iter().copied()));
+ /// assert_eq!(&vec[..], &squares[6..]);
+ /// assert!(vec.capacity() >= squares.len());
+ ///
+ /// println!("Range");
+ /// let mut vec = squares.clone();
+ /// assert!(vec.par_drain(3..7)
+ /// .eq(squares[3..7].par_iter().copied()));
+ /// assert_eq!(&vec[..3], &squares[..3]);
+ /// assert_eq!(&vec[3..], &squares[7..]);
+ /// assert!(vec.capacity() >= squares.len());
+ ///
+ /// println!("RangeInclusive");
+ /// let mut vec = squares.clone();
+ /// assert!(vec.par_drain(3..=7)
+ /// .eq(squares[3..=7].par_iter().copied()));
+ /// assert_eq!(&vec[..3], &squares[..3]);
+ /// assert_eq!(&vec[3..], &squares[8..]);
+ /// assert!(vec.capacity() >= squares.len());
+ /// ```
+ fn par_drain<R: RangeBounds<Idx>>(self, range: R) -> Self::Iter;
+}
+
+/// We hide the `Try` trait in a private module, as it's only meant to be a
+/// stable clone of the standard library's `Try` trait, as yet unstable.
+mod private {
+ use std::convert::Infallible;
+ use std::task::Poll;
+
+ #[cfg(has_control_flow)]
+ pub(crate) use std::ops::ControlFlow;
+
+ #[cfg(not(has_control_flow))]
+ #[allow(missing_debug_implementations)]
+ pub enum ControlFlow<B, C = ()> {
+ Continue(C),
+ Break(B),
+ }
+
+ use self::ControlFlow::{Break, Continue};
+
+ /// Clone of `std::ops::Try`.
+ ///
+ /// Implementing this trait is not permitted outside of `rayon`.
+ pub trait Try {
+ private_decl! {}
+
+ type Output;
+ type Residual;
+
+ fn from_output(output: Self::Output) -> Self;
+
+ fn from_residual(residual: Self::Residual) -> Self;
+
+ fn branch(self) -> ControlFlow<Self::Residual, Self::Output>;
+ }
+
+ #[cfg(has_control_flow)]
+ impl<B, C> Try for ControlFlow<B, C> {
+ private_impl! {}
+
+ type Output = C;
+ type Residual = ControlFlow<B, Infallible>;
+
+ fn from_output(output: Self::Output) -> Self {
+ Continue(output)
+ }
+
+ fn from_residual(residual: Self::Residual) -> Self {
+ match residual {
+ Break(b) => Break(b),
+ Continue(_) => unreachable!(),
+ }
+ }
+
+ fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
+ match self {
+ Continue(c) => Continue(c),
+ Break(b) => Break(Break(b)),
+ }
+ }
+ }
+
+ impl<T> Try for Option<T> {
+ private_impl! {}
+
+ type Output = T;
+ type Residual = Option<Infallible>;
+
+ fn from_output(output: Self::Output) -> Self {
+ Some(output)
+ }
+
+ fn from_residual(residual: Self::Residual) -> Self {
+ match residual {
+ None => None,
+ Some(_) => unreachable!(),
+ }
+ }
+
+ fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
+ match self {
+ Some(c) => Continue(c),
+ None => Break(None),
+ }
+ }
+ }
+
+ impl<T, E> Try for Result<T, E> {
+ private_impl! {}
+
+ type Output = T;
+ type Residual = Result<Infallible, E>;
+
+ fn from_output(output: Self::Output) -> Self {
+ Ok(output)
+ }
+
+ fn from_residual(residual: Self::Residual) -> Self {
+ match residual {
+ Err(e) => Err(e),
+ Ok(_) => unreachable!(),
+ }
+ }
+
+ fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
+ match self {
+ Ok(c) => Continue(c),
+ Err(e) => Break(Err(e)),
+ }
+ }
+ }
+
+ impl<T, E> Try for Poll<Result<T, E>> {
+ private_impl! {}
+
+ type Output = Poll<T>;
+ type Residual = Result<Infallible, E>;
+
+ fn from_output(output: Self::Output) -> Self {
+ output.map(Ok)
+ }
+
+ fn from_residual(residual: Self::Residual) -> Self {
+ match residual {
+ Err(e) => Poll::Ready(Err(e)),
+ Ok(_) => unreachable!(),
+ }
+ }
+
+ fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
+ match self {
+ Poll::Pending => Continue(Poll::Pending),
+ Poll::Ready(Ok(c)) => Continue(Poll::Ready(c)),
+ Poll::Ready(Err(e)) => Break(Err(e)),
+ }
+ }
+ }
+
+ impl<T, E> Try for Poll<Option<Result<T, E>>> {
+ private_impl! {}
+
+ type Output = Poll<Option<T>>;
+ type Residual = Result<Infallible, E>;
+
+ fn from_output(output: Self::Output) -> Self {
+ match output {
+ Poll::Ready(o) => Poll::Ready(o.map(Ok)),
+ Poll::Pending => Poll::Pending,
+ }
+ }
+
+ fn from_residual(residual: Self::Residual) -> Self {
+ match residual {
+ Err(e) => Poll::Ready(Some(Err(e))),
+ Ok(_) => unreachable!(),
+ }
+ }
+
+ fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
+ match self {
+ Poll::Pending => Continue(Poll::Pending),
+ Poll::Ready(None) => Continue(Poll::Ready(None)),
+ Poll::Ready(Some(Ok(c))) => Continue(Poll::Ready(Some(c))),
+ Poll::Ready(Some(Err(e))) => Break(Err(e)),
+ }
+ }
+ }
}
projects / rustc.git / blobdiff