Merge #788

788: Add a parallel iterator of matching positions r=nikomatsakis a=cuviper

This is the plural of the `position` methods, where `positions` finds
_all_ matching items and returns their indices in a new iterator. This
matches the API of `Itertools::positions`, but in parallel.

Co-authored-by: Josh Stone <[email protected]>

src/compile_fail/must_use.rs

@@ -54,6 +54,7 @@ must_use! {
     map_with            /** v.par_iter().map_with(0, |_, x| x); */
     map_init            /** v.par_iter().map_init(|| 0, |_, x| x); */
     panic_fuse          /** v.par_iter().panic_fuse(); */
+    positions           /** v.par_iter().positions(|_| true); */
     rev                 /** v.par_iter().rev(); */
     skip                /** v.par_iter().skip(1); */
     take                /** v.par_iter().take(1); */

src/iter/mod.rs

@@ -133,6 +133,7 @@ mod noop;
 mod once;
 mod panic_fuse;
 mod par_bridge;
+mod positions;
 mod product;
 mod reduce;
 mod repeat;
@@ -175,6 +176,7 @@ pub use self::{
     once::{once, Once},
     panic_fuse::PanicFuse,
     par_bridge::{IterBridge, ParallelBridge},
+    positions::Positions,
     repeat::{repeat, repeatn, Repeat, RepeatN},
     rev::Rev,
     skip::Skip,
@@ -2688,6 +2690,31 @@ pub trait IndexedParallelIterator: ParallelIterator {
         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.
     ///

src/iter/positions.rs

@@ -0,0 +1,137 @@
+use super::plumbing::*;
+use super::*;
+
+use std::fmt::{self, Debug};
+
+/// `Positions` takes a predicate `predicate` and filters out elements that match,
+/// yielding their indices.
+///
+/// This struct is created by the [`positions()`] method on [`IndexedParallelIterator`]
+///
+/// [`positions()`]: trait.IndexedParallelIterator.html#method.positions
+/// [`IndexedParallelIterator`]: trait.IndexedParallelIterator.html
+#[must_use = "iterator adaptors are lazy and do nothing unless consumed"]
+#[derive(Clone)]
+pub struct Positions<I: IndexedParallelIterator, P> {
+    base: I,
+    predicate: P,
+}
+
+impl<I: IndexedParallelIterator + Debug, P> Debug for Positions<I, P> {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.debug_struct("Positions")
+            .field("base", &self.base)
+            .finish()
+    }
+}
+
+impl<I, P> Positions<I, P>
+where
+    I: IndexedParallelIterator,
+{
+    /// Create a new `Positions` iterator.
+    pub(super) fn new(base: I, predicate: P) -> Self {
+        Positions { base, predicate }
+    }
+}
+
+impl<I, P> ParallelIterator for Positions<I, P>
+where
+    I: IndexedParallelIterator,
+    P: Fn(I::Item) -> bool + Sync + Send,
+{
+    type Item = usize;
+
+    fn drive_unindexed<C>(self, consumer: C) -> C::Result
+    where
+        C: UnindexedConsumer<Self::Item>,
+    {
+        let consumer1 = PositionsConsumer::new(consumer, &self.predicate, 0);
+        self.base.drive(consumer1)
+    }
+}
+
+/// ////////////////////////////////////////////////////////////////////////
+/// Consumer implementation
+
+struct PositionsConsumer<'p, C, P> {
+    base: C,
+    predicate: &'p P,
+    offset: usize,
+}
+
+impl<'p, C, P> PositionsConsumer<'p, C, P> {
+    fn new(base: C, predicate: &'p P, offset: usize) -> Self {
+        PositionsConsumer {
+            base,
+            predicate,
+            offset,
+        }
+    }
+}
+
+impl<'p, T, C, P> Consumer<T> for PositionsConsumer<'p, C, P>
+where
+    C: Consumer<usize>,
+    P: Fn(T) -> bool + Sync,
+{
+    type Folder = PositionsFolder<'p, C::Folder, P>;
+    type Reducer = C::Reducer;
+    type Result = C::Result;
+
+    fn split_at(self, index: usize) -> (Self, Self, C::Reducer) {
+        let (left, right, reducer) = self.base.split_at(index);
+        (
+            PositionsConsumer::new(left, self.predicate, self.offset),
+            PositionsConsumer::new(right, self.predicate, self.offset + index),
+            reducer,
+        )
+    }
+
+    fn into_folder(self) -> Self::Folder {
+        PositionsFolder {
+            base: self.base.into_folder(),
+            predicate: self.predicate,
+            offset: self.offset,
+        }
+    }
+
+    fn full(&self) -> bool {
+        self.base.full()
+    }
+}
+
+struct PositionsFolder<'p, F, P> {
+    base: F,
+    predicate: &'p P,
+    offset: usize,
+}
+
+impl<F, P, T> Folder<T> for PositionsFolder<'_, F, P>
+where
+    F: Folder<usize>,
+    P: Fn(T) -> bool,
+{
+    type Result = F::Result;
+
+    fn consume(mut self, item: T) -> Self {
+        let index = self.offset;
+        self.offset += 1;
+        if (self.predicate)(item) {
+            self.base = self.base.consume(index);
+        }
+        self
+    }
+
+    // This cannot easily specialize `consume_iter` to be better than
+    // the default, because that requires checking `self.base.full()`
+    // during a call to `self.base.consume_iter()`. (#632)
+
+    fn complete(self) -> Self::Result {
+        self.base.complete()
+    }
+
+    fn full(&self) -> bool {
+        self.base.full()
+    }
+}

tests/clones.rs

@@ -134,6 +134,7 @@ fn clone_adaptors() {
     check(v.par_iter().map_with(0, |_, x| x));
     check(v.par_iter().map_init(|| 0, |_, x| x));
     check(v.par_iter().panic_fuse());
+    check(v.par_iter().positions(|_| true));
     check(v.par_iter().rev());
     check(v.par_iter().skip(1));
     check(v.par_iter().take(1));

tests/debug.rs

@@ -157,6 +157,7 @@ fn debug_adaptors() {
     check(v.par_iter().map_with(0, |_, x| x));
     check(v.par_iter().map_init(|| 0, |_, x| x));
     check(v.par_iter().panic_fuse());
+    check(v.par_iter().positions(|_| true));
     check(v.par_iter().rev());
     check(v.par_iter().skip(1));
     check(v.par_iter().take(1));