Skip to content

Iterator Trait Parity

Jump to bottom Edit New page
Josh Stone edited this page Dec 19, 2017 · 13 revisions

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> { ... }
  • 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> { ... }
  • fn take(self, n: usize) -> Take<Self> { ... }
  • 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> { ... }
  • 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 { ... }
  • fn position<P>(&mut self, predicate: P) -> Option<usize> where P: FnMut(Self::Item) -> bool { ... }
  • fn rposition<P>(&mut self, predicate: P) -> Option<usize> where P: FnMut(Self::Item) -> bool, Self: ExactSizeIterator + DoubleEndedIterator { ... }
  • fn max(self) -> Option<Self::Item> where Self::Item: Ord { ... }
  • fn min(self) -> Option<Self::Item> where Self::Item: Ord { ... }
  • fn max_by_key<B, F>(self, f: F) -> Option<Self::Item> where B: Ord, F: FnMut(&Self::Item) -> B { ... }
  • fn max_by<F>(self, compare: F) -> Option<Self::Item> where F: FnMut(&Self::Item, &Self::Item) -> Ordering { ... }
  • fn min_by_key<B, F>(self, f: F) -> Option<Self::Item> where B: Ord, F: FnMut(&Self::Item) -> B { ... }
  • fn min_by<F>(self, compare: F) -> Option<Self::Item> where F: FnMut(&Self::Item, &Self::Item) -> Ordering { ... }
  • fn rev(self) -> Rev<Self> where Self: DoubleEndedIterator { ... }
  • fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB) where FromA: Default + Extend<A>, FromB: Default + Extend<B>, Self: Iterator<Item=(A, B)> { ... }
  • fn cloned<'a, T>(self) -> Cloned<Self> where Self: Iterator<Item=&'a T>, T: 'a + Clone { ... }
  • fn cycle(self) -> Cycle<Self> where Self: Clone { ... }
  • fn sum<S>(self) -> S where S: Sum<Self::Item> { ... }
  • fn product<P>(self) -> P where P: Product<Self::Item> { ... }
  • fn cmp<I>(self, other: I) -> Ordering where I: IntoIterator<Item=Self::Item>, Self::Item: Ord { ... }
  • fn partial_cmp<I>(self, other: I) -> Option<Ordering> where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • fn eq<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialEq<I::Item> { ... }
  • fn ne<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialEq<I::Item> { ... }
  • fn lt<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • fn le<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • fn gt<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
  • fn ge<I>(self, other: I) -> bool where I: IntoIterator, Self::Item: PartialOrd<I::Item> { ... }
Add a custom footer
Add a custom sidebar
Clone this wiki locally