Iterator Trait Parity

Here is a copy of the current Iterator trait along with some annotations on each of its methods.

• fn size_hint(&self) -> (usize, Option<usize>) { ... }
  • N/A, although in issue #146, I mentioned that it would be useful to be able to dynamically test if this is an exact vs bounded iterator; and in general it'd be great to be able to dynamically test even more than that --nmatsakis
• fn count(self) -> usize { ... }
• fn last(self) -> Option<Self::Item> { ... }
• fn nth(&mut self, n: usize) -> Option<Self::Item> { ... }
• fn step_by(self, step: usize) -> StepBy<Self> { ... }
  • https://github.com/rayon-rs/rayon/issues/494
• fn chain<U>(self, other: U) -> Chain<Self, U::IntoIter> where U: IntoIterator<Item=Self::Item> { ... }
• fn zip<U>(self, other: U) -> Zip<Self, U::IntoIter> where U: IntoIterator { ... }
• fn map<B, F>(self, f: F) -> Map<Self, F> where F: FnMut(Self::Item) -> B { ... }
• fn for_each<F>(self, f: F) where F: FnMut(Self::Item) -> () { ... }
• fn filter<P>(self, predicate: P) -> Filter<Self, P> where P: FnMut(&Self::Item) -> bool { ... }
• fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> where F: FnMut(Self::Item) -> Option<B> { ... }
• fn enumerate(self) -> Enumerate<Self> { ... }
• fn peekable(self) -> Peekable<Self> { ... }
  • Inherently sequential --nmatsakis
• fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P> where P: FnMut(&Self::Item) -> bool { ... }
  • Inherently sequential --nmatsakis
• fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> where P: FnMut(&Self::Item) -> bool { ... }
  • Inherently sequential --nmatsakis
• fn skip(self, n: usize) -> Skip<Self> { ... }
  • https://github.com/nikomatsakis/rayon/issues/147
• fn take(self, n: usize) -> Take<Self> { ... }
  • https://github.com/nikomatsakis/rayon/issues/147
• fn scan<St, B, F>(self, initial_state: St, f: F) -> Scan<Self, St, F> where F: FnMut(&mut St, Self::Item) -> Option<B> { ... }
  • https://github.com/rayon-rs/rayon/issues/329
  • this is generally possible (it will be a bit different; more like reduce), but it is non-trivial
  • it requires >1 pass and hence produces an intermediate collection
  • basically you would do a parallel fold operation, performing a sequential scan for each segment
    • the result of your scan is a VecTree<Vec<T>> of same total length as your input iterator
    • this gives you partial sums (to consider one concrete application) at each point
  • you can then traverse the tree (sequentially) to compute, for each vector, the total sum of preceding vectors
  • you can then re-traverse the tree (in parallel) and add this total sum to each element of the vector (in place)
  • that last step can itself drive another consumer, so this can still be a parallel adapter
    • if we are clever, it can even be an exact one, though it will require a nice VecTree implementation
• fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F> where F: FnMut(Self::Item) -> U, U: IntoIterator { ... }
• fn fuse(self) -> Fuse<Self> { ... }
  • Meh. I'm not sure how relevant this this. -- nmatsakis
• fn inspect<F>(self, f: F) -> Inspect<Self, F> where F: FnMut(&Self::Item) -> () { ... }
• fn by_ref(&mut self) -> &mut Self { ... }
  • Meh. Harder for us to support since we rely on taking ownership a lot to make ownership and safety work out, iirc.
• fn collect<B>(self) -> B where B: FromIterator<Self::Item> { ... }
• fn partition<B, F>(self, f: F) -> (B, B) where B: Default + Extend<Self::Item>, F: FnMut(&Self::Item) -> bool { ... }
  • I've always thought this signature was wrong. Trying to remember why. =)
  • At minimum, it should permit two distinct kinds of collections.
  • Still, it's interesting that the current FromParallelIterator can't support this.
  • https://github.com/nikomatsakis/rayon/pull/326
• fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R where F: FnMut(B, Self::Item) -> R, R: Try<Ok = B> { ... }
  • https://github.com/rayon-rs/rayon/issues/495
• fn fold<B, F>(self, init: B, f: F) -> B where F: FnMut(B, Self::Item) -> B { ... }
• fn all<F>(&mut self, f: F) -> bool where F: FnMut(Self::Item) -> bool { ... }
• fn any<F>(&mut self, f: F) -> bool where F: FnMut(Self::Item) -> bool { ... }
• fn find<P>(&mut self, predicate: P) -> Option<Self::Item> where P: FnMut(&Self::Item) -> bool { ... }
  • https://github.com/nikomatsakis/rayon/issues/151
• fn position<P>(&mut self, predicate: P) -> Option<usize> where P: FnMut(Self::Item) -> bool { ... }
  • https://github.com/nikomatsakis/rayon/issues/151
• fn rposition<P>(&mut self, predicate: P) -> Option<usize> where P: FnMut(Self::Item) -> bool, Self: ExactSizeIterator + DoubleEndedIterator { ... }
  • https://github.com/nikomatsakis/rayon/issues/151
• fn max(self) -> Option<Self::Item> where Self::Item: Ord { ... }
  • https://github.com/nikomatsakis/rayon/issues/148
• fn min(self) -> Option<Self::Item> where Self::Item: Ord { ... }
  • https://github.com/nikomatsakis/rayon/issues/148
• fn max_by_key<B, F>(self, f: F) -> Option<Self::Item> where B: Ord, F: FnMut(&Self::Item) -> B { ... }
  • https://github.com/nikomatsakis/rayon/issues/148
• fn max_by<F>(self, compare: F) -> Option<Self::Item> where F: FnMut(&Self::Item, &Self::Item) -> Ordering { ... }
  • https://github.com/rayon-rs/rayon/pull/306
• fn min_by_key<B, F>(self, f: F) -> Option<Self::Item> where B: Ord, F: FnMut(&Self::Item) -> B { ... }
  • https://github.com/nikomatsakis/rayon/issues/148
• fn min_by<F>(self, compare: F) -> Option<Self::Item> where F: FnMut(&Self::Item, &Self::Item) -> Ordering { ... }
  • https://github.com/rayon-rs/rayon/pull/306
• fn rev(self) -> Rev<Self> where Self: DoubleEndedIterator { ... }
  • https://github.com/nikomatsakis/rayon/issues/150
• fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB) where FromA: Default + Extend<A>, FromB: Default + Extend<B>, Self: Iterator<Item=(A, B)> { ... }
  • like partition, a bit tricky perhaps
  • https://github.com/nikomatsakis/rayon/pull/326
• fn cloned<'a, T>(self) -> Cloned<Self> where Self: Iterator<Item=&'a T>, T: 'a + Clone { ... }
• fn cycle(self) -> Cycle<Self> where Self: Clone { ... }
  • https://github.com/rayon-rs/rayon/issues/330
  • This can probably be done for indexed parallel iterator, at least, sort of like chain?
  • Have to think about it =)
• fn sum<S>(self) -> S where S: Sum<Self::Item> { ... }
• fn product<P>(self) -> P where P: Product<Self::Item> { ... }
  • https://github.com/nikomatsakis/rayon/issues/149
• fn cmp<I>(self, other: I) -> Ordering where I: IntoIterator<Item=Self::Item>, Self::Item: Ord { ... }
  • https://github.com/nikomatsakis/rayon/issues/152
• fn partial_cmp<I>(self, other: I) -> Option<Ordering> where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • https://github.com/nikomatsakis/rayon/issues/152
• fn eq<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialEq<I::Item> { ... }
  • https://github.com/nikomatsakis/rayon/issues/152
• fn ne<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialEq<I::Item> { ... }
  • https://github.com/nikomatsakis/rayon/issues/152
• fn lt<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • https://github.com/nikomatsakis/rayon/issues/152
• fn le<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • https://github.com/nikomatsakis/rayon/issues/152
• fn gt<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • https://github.com/nikomatsakis/rayon/issues/152
• fn ge<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • https://github.com/nikomatsakis/rayon/issues/152