From a86f72d9a2adc6d65f2ba0990caca35c1a3f622d Mon Sep 17 00:00:00 2001 From: Aaron Turon Date: Thu, 6 Nov 2014 09:32:32 -0800 Subject: [PATCH] libs: stabilize iter module This is an initial pass at stabilizing the `iter` module. The module is fairly large, but is also pretty polished, so most of the stabilization leaves things as they are. Some changes: * Due to the new object safety rules, various traits needs to be split into object-safe traits and extension traits. This includes `Iterator` itself. While splitting up the traits adds some complexity, it will also increase flexbility: once we have automatic impls of `Trait` for trait objects over `Trait`, then things like the iterator adapters will all work with trait objects. * Iterator adapters that use up the entire iterator now take it by value, which makes the semantics more clear and helps catch bugs. Due to the splitting of Iterator, this does not affect trait objects. If the underlying iterator is still desired for some reason, `by_ref` can be used. (Note: this change had no fallout in the Rust distro except for the useless mut lint.) * In general, extension traits new and old are following an [in-progress convention](https://github.com/rust-lang/rfcs/pull/445). As such, they are marked `unstable`. * As usual, anything involving closures is `unstable` pending unboxed closures. * A few of the more esoteric/underdeveloped iterator forms (like `RandomAccessIterator` and `MutableDoubleEndedIterator`, along with various unfolds) are left experimental for now. * The `order` submodule is left `experimental` because it will hopefully be replaced by generalized comparison traits. * "Leaf" iterators (like `Repeat` and `Counter`) are uniformly constructed by free fns at the module level. That's because the types are not otherwise of any significance (if we had `impl Trait`, you wouldn't want to define a type at all). Closes #17701 Due to renamings and splitting of traits, this is a: [breaking-change] --- src/libcore/iter.rs | 243 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 199 insertions(+), 44 deletions(-) diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index 02242492e34a1..496e7979b726e 100644 --- a/src/libcore/iter.rs +++ b/src/libcore/iter.rs @@ -72,12 +72,14 @@ use uint; #[deprecated = "renamed to Extend"] pub use self::Extend as Extendable; /// Conversion from an `Iterator` +#[unstable = "may be replaced by a more general conversion trait"] pub trait FromIterator { /// Build a container with elements from an external iterator. fn from_iter>(iterator: T) -> Self; } /// A type growable from an `Iterator` implementation +#[unstable = "just renamed as part of collections reform"] pub trait Extend { /// Extend a container with the elements yielded by an arbitrary iterator fn extend>(&mut self, iterator: T); @@ -94,6 +96,7 @@ pub trait Extend { /// it wishes, either by returning `None` infinitely, or by doing something /// else. #[lang="iterator"] +#[unstable = "just split up for object safety"] pub trait Iterator { /// Advance the iterator and return the next value. Return `None` when the end is reached. fn next(&mut self) -> Option; @@ -104,7 +107,11 @@ pub trait Iterator { /// does not fit within a `uint`. #[inline] fn size_hint(&self) -> (uint, Option) { (0, None) } +} +#[unstable = "new convention for extension traits"] +/// An extension trait providing numerous methods applicable to all iterators. +pub trait IteratorExt: Iterator { /// Chain this iterator with another, returning a new iterator which will /// finish iterating over the current iterator, and then it will iterate /// over the other specified iterator. @@ -120,6 +127,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[stable] fn chain>(self, other: U) -> Chain { Chain{a: self, b: other, flag: false} } @@ -140,6 +148,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[stable] fn zip>(self, other: U) -> Zip { Zip{a: self, b: other} } @@ -157,6 +166,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[unstable = "waiting for unboxed closures"] fn map<'r, B>(self, f: |A|: 'r -> B) -> Map<'r, A, B, Self> { Map{iter: self, f: f} } @@ -174,6 +184,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[unstable = "waiting for unboxed closures"] fn filter<'r>(self, predicate: |&A|: 'r -> bool) -> Filter<'r, A, Self> { Filter{iter: self, predicate: predicate} } @@ -191,6 +202,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[unstable = "waiting for unboxed closures"] fn filter_map<'r, B>(self, f: |A|: 'r -> Option) -> FilterMap<'r, A, B, Self> { FilterMap { iter: self, f: f } } @@ -209,6 +221,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[stable] fn enumerate(self) -> Enumerate { Enumerate{iter: self, count: 0} } @@ -232,6 +245,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[stable] fn peekable(self) -> Peekable { Peekable{iter: self, peeked: None} } @@ -251,6 +265,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[unstable = "waiting for unboxed closures"] fn skip_while<'r>(self, predicate: |&A|: 'r -> bool) -> SkipWhile<'r, A, Self> { SkipWhile{iter: self, flag: false, predicate: predicate} } @@ -269,6 +284,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[unstable = "waiting for unboxed closures, may want to require peek"] fn take_while<'r>(self, predicate: |&A|: 'r -> bool) -> TakeWhile<'r, A, Self> { TakeWhile{iter: self, flag: false, predicate: predicate} } @@ -286,6 +302,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[stable] fn skip(self, n: uint) -> Skip { Skip{iter: self, n: n} } @@ -304,6 +321,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[stable] fn take(self, n: uint) -> Take { Take{iter: self, n: n} } @@ -329,6 +347,7 @@ pub trait Iterator { /// assert!(it.next().is_none()); /// ``` #[inline] + #[unstable = "waiting for unboxed closures"] fn scan<'r, St, B>(self, initial_state: St, f: |&mut St, A|: 'r -> Option) -> Scan<'r, A, B, Self, St> { Scan{iter: self, f: f, state: initial_state} @@ -353,6 +372,7 @@ pub trait Iterator { /// } /// ``` #[inline] + #[unstable = "waiting for unboxed closures"] fn flat_map<'r, B, U: Iterator>(self, f: |A|: 'r -> U) -> FlatMap<'r, A, Self, U> { FlatMap{iter: self, f: f, frontiter: None, backiter: None } @@ -386,6 +406,7 @@ pub trait Iterator { /// assert_eq!(process(x.into_iter()), 1006); /// ``` #[inline] + #[stable] fn fuse(self) -> Fuse { Fuse{iter: self, done: false} } @@ -409,6 +430,7 @@ pub trait Iterator { /// println!("{}", sum); /// ``` #[inline] + #[unstable = "waiting for unboxed closures"] fn inspect<'r>(self, f: |&A|: 'r) -> Inspect<'r, A, Self> { Inspect{iter: self, f: f} } @@ -428,6 +450,7 @@ pub trait Iterator { /// // xs.next() is now `5` /// assert!(xs.next() == Some(5)); /// ``` + #[stable] fn by_ref<'r>(&'r mut self) -> ByRef<'r, Self> { ByRef{iter: self} } @@ -443,8 +466,9 @@ pub trait Iterator { /// assert!(a.as_slice() == b.as_slice()); /// ``` #[inline] - fn collect>(&mut self) -> B { - FromIterator::from_iter(self.by_ref()) + #[unstable = "waiting for general conversion traits, just changed to take self by value"] + fn collect>(self) -> B { + FromIterator::from_iter(self) } /// Loops through `n` iterations, returning the `n`th element of the @@ -459,6 +483,7 @@ pub trait Iterator { /// assert!(it.nth(2) == None); /// ``` #[inline] + #[stable] fn nth(&mut self, mut n: uint) -> Option { for x in *self { if n == 0 { return Some(x) } @@ -477,9 +502,10 @@ pub trait Iterator { /// assert!(a.iter().last().unwrap() == &5); /// ``` #[inline] - fn last(&mut self) -> Option { + #[unstable = "just changed to take self by value"] + fn last(mut self) -> Option { let mut last = None; - for x in *self { last = Some(x); } + for x in self { last = Some(x); } last } @@ -493,9 +519,10 @@ pub trait Iterator { /// assert!(a.iter().fold(0, |a, &b| a + b) == 15); /// ``` #[inline] - fn fold(&mut self, init: B, f: |B, A| -> B) -> B { + #[unstable = "waiting for unboxed closures, just changed to take self by value"] + fn fold(mut self, init: B, f: |B, A| -> B) -> B { let mut accum = init; - for x in *self { + for x in self { accum = f(accum, x); } accum @@ -509,10 +536,10 @@ pub trait Iterator { /// let a = [1i, 2, 3, 4, 5]; /// let mut it = a.iter(); /// assert!(it.count() == 5); - /// assert!(it.count() == 0); /// ``` #[inline] - fn count(&mut self) -> uint { + #[unstable = "just changed to take self by value"] + fn count(self) -> uint { self.fold(0, |cnt, _x| cnt + 1) } @@ -526,8 +553,9 @@ pub trait Iterator { /// assert!(!a.iter().all(|x| *x > 2)); /// ``` #[inline] - fn all(&mut self, f: |A| -> bool) -> bool { - for x in *self { if !f(x) { return false; } } + #[unstable = "waiting for unboxed closures, just changed to take self by value"] + fn all(mut self, f: |A| -> bool) -> bool { + for x in self { if !f(x) { return false; } } true } @@ -543,6 +571,7 @@ pub trait Iterator { /// assert!(!it.any(|x| *x == 3)); /// ``` #[inline] + #[unstable = "waiting for unboxed closures"] fn any(&mut self, f: |A| -> bool) -> bool { for x in *self { if f(x) { return true; } } false @@ -552,6 +581,7 @@ pub trait Iterator { /// /// Does not consume the iterator past the first found element. #[inline] + #[unstable = "waiting for unboxed closures"] fn find(&mut self, predicate: |&A| -> bool) -> Option { for x in *self { if predicate(&x) { return Some(x) } @@ -561,6 +591,7 @@ pub trait Iterator { /// Return the index of the first element satisfying the specified predicate #[inline] + #[unstable = "waiting for unboxed closures"] fn position(&mut self, predicate: |A| -> bool) -> Option { let mut i = 0; for x in *self { @@ -584,7 +615,8 @@ pub trait Iterator { /// assert_eq!(*xs.iter().max_by(|x| x.abs()).unwrap(), -10); /// ``` #[inline] - fn max_by(&mut self, f: |&A| -> B) -> Option { + #[unstable = "waiting for unboxed closures, just changed to take self by value"] + fn max_by(self, f: |&A| -> B) -> Option { self.fold(None, |max: Option<(A, B)>, x| { let x_val = f(&x); match max { @@ -610,7 +642,8 @@ pub trait Iterator { /// assert_eq!(*xs.iter().min_by(|x| x.abs()).unwrap(), 0); /// ``` #[inline] - fn min_by(&mut self, f: |&A| -> B) -> Option { + #[unstable = "waiting for unboxed closures, just changed to take self by value"] + fn min_by(self, f: |&A| -> B) -> Option { self.fold(None, |min: Option<(A, B)>, x| { let x_val = f(&x); match min { @@ -625,14 +658,22 @@ pub trait Iterator { } } +#[unstable = "trait is unstable"] +impl IteratorExt for I where I: Iterator {} + /// A range iterator able to yield elements from both ends /// /// A `DoubleEndedIterator` can be thought of as a deque in that `next()` and `next_back()` exhaust /// elements from the *same* range, and do not work independently of each other. +#[unstable = "recently split into two traits"] pub trait DoubleEndedIterator: Iterator { /// Yield an element from the end of the range, returning `None` if the range is empty. fn next_back(&mut self) -> Option; +} +/// Extension methods for double-ended iterators. +#[unstable = "new extension trait convention"] +pub trait DoubleEndedIteratorExt: DoubleEndedIterator { /// Change the direction of the iterator /// /// The flipped iterator swaps the ends on an iterator that can already @@ -646,18 +687,24 @@ pub trait DoubleEndedIterator: Iterator { /// Note: Random access with flipped indices still only applies to the first /// `uint::MAX` elements of the original iterator. #[inline] + #[stable] fn rev(self) -> Rev { Rev{iter: self} } } +#[unstable = "trait is unstable"] +impl DoubleEndedIteratorExt for I where I: DoubleEndedIterator {} + /// A double-ended iterator yielding mutable references +#[experimental = "not widely used"] pub trait MutableDoubleEndedIterator { // FIXME: #5898: should be called `reverse` /// Use an iterator to reverse a container in-place fn reverse_(&mut self); } +#[experimental = "trait is experimental"] impl<'a, A:'a, T: DoubleEndedIterator<&'a mut A>> MutableDoubleEndedIterator for T { // FIXME: #5898: should be called `reverse` /// Use an iterator to reverse a container in-place @@ -678,6 +725,7 @@ impl<'a, A:'a, T: DoubleEndedIterator<&'a mut A>> MutableDoubleEndedIterator for /// Calling `next()` or `next_back()` on a `RandomAccessIterator` /// reduces the indexable range accordingly. That is, `it.idx(1)` will become `it.idx(0)` /// after `it.next()` is called. +#[experimental = "not widely used, may be better decomposed into Index and ExactSizeIterator"] pub trait RandomAccessIterator: Iterator { /// Return the number of indexable elements. At most `std::uint::MAX` /// elements are indexable, even if the iterator represents a longer range. @@ -694,7 +742,8 @@ pub trait RandomAccessIterator: Iterator { /// /// `Iterator::size_hint` *must* return the exact size of the iterator. /// Note that the size must fit in `uint`. -pub trait ExactSize : DoubleEndedIterator { +#[unstable = "could move DoubleEndedIterator bound onto rposition with method-level where clauses"] +pub trait ExactSizeIterator : DoubleEndedIterator { /// Return the index of the last element satisfying the specified predicate /// /// If no element matches, None is returned. @@ -702,7 +751,7 @@ pub trait ExactSize : DoubleEndedIterator { fn rposition(&mut self, predicate: |A| -> bool) -> Option { let len = self.len(); for i in range(0, len).rev() { - if predicate(self.next_back().expect("rposition: incorrect ExactSize")) { + if predicate(self.next_back().expect("rposition: incorrect ExactSizeIterator")) { return Some(i); } } @@ -724,19 +773,27 @@ pub trait ExactSize : DoubleEndedIterator { // All adaptors that preserve the size of the wrapped iterator are fine // Adaptors that may overflow in `size_hint` are not, i.e. `Chain`. -impl> ExactSize<(uint, A)> for Enumerate {} -impl<'a, A, T: ExactSize> ExactSize for Inspect<'a, A, T> {} -impl> ExactSize for Rev {} -impl<'a, A, B, T: ExactSize> ExactSize for Map<'a, A, B, T> {} -impl, U: ExactSize> ExactSize<(A, B)> for Zip {} +#[unstable = "trait is unstable"] +impl> ExactSizeIterator<(uint, A)> for Enumerate {} +#[unstable = "trait is unstable"] +impl<'a, A, T: ExactSizeIterator> ExactSizeIterator for Inspect<'a, A, T> {} +#[unstable = "trait is unstable"] +impl> ExactSizeIterator for Rev {} +#[unstable = "trait is unstable"] +impl<'a, A, B, T: ExactSizeIterator> ExactSizeIterator for Map<'a, A, B, T> {} +#[unstable = "trait is unstable"] +impl ExactSizeIterator<(A, B)> for Zip + where T: ExactSizeIterator, U: ExactSizeIterator {} /// An double-ended iterator with the direction inverted #[deriving(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Rev { iter: T } +#[unstable = "trait is unstable"] impl> Iterator for Rev { #[inline] fn next(&mut self) -> Option { self.iter.next_back() } @@ -744,11 +801,13 @@ impl> Iterator for Rev { fn size_hint(&self) -> (uint, Option) { self.iter.size_hint() } } +#[unstable = "trait is unstable"] impl> DoubleEndedIterator for Rev { #[inline] fn next_back(&mut self) -> Option { self.iter.next() } } +#[experimental = "trait is experimental"] impl + RandomAccessIterator> RandomAccessIterator for Rev { #[inline] @@ -762,10 +821,12 @@ impl + RandomAccessIterator> RandomAccessIterato /// A mutable reference to an iterator #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct ByRef<'a, T:'a> { iter: &'a mut T } +#[unstable = "trait is unstable"] impl<'a, A, T: Iterator+'a> Iterator for ByRef<'a, T> { #[inline] fn next(&mut self) -> Option { self.iter.next() } @@ -773,12 +834,14 @@ impl<'a, A, T: Iterator+'a> Iterator for ByRef<'a, T> { fn size_hint(&self) -> (uint, Option) { self.iter.size_hint() } } +#[unstable = "trait is unstable"] impl<'a, A, T: DoubleEndedIterator+'a> DoubleEndedIterator for ByRef<'a, T> { #[inline] fn next_back(&mut self) -> Option { self.iter.next_back() } } /// A trait for iterators over elements which can be added together +#[experimental = "needs to be re-evaluated as part of numerics reform"] pub trait AdditiveIterator { /// Iterates over the entire iterator, summing up all the elements /// @@ -791,14 +854,15 @@ pub trait AdditiveIterator { /// let mut it = a.iter().map(|&x| x); /// assert!(it.sum() == 15); /// ``` - fn sum(&mut self) -> A; + fn sum(self) -> A; } macro_rules! impl_additive { ($A:ty, $init:expr) => { + #[experimental = "trait is experimental"] impl> AdditiveIterator<$A> for T { #[inline] - fn sum(&mut self) -> $A { + fn sum(self) -> $A { self.fold($init, |acc, x| acc + x) } } @@ -818,6 +882,7 @@ impl_additive!(f32, 0.0) impl_additive!(f64, 0.0) /// A trait for iterators over elements which can be multiplied together. +#[experimental = "needs to be re-evaluated as part of numerics reform"] pub trait MultiplicativeIterator { /// Iterates over the entire iterator, multiplying all the elements /// @@ -833,14 +898,15 @@ pub trait MultiplicativeIterator { /// assert!(factorial(1) == 1); /// assert!(factorial(5) == 120); /// ``` - fn product(&mut self) -> A; + fn product(self) -> A; } macro_rules! impl_multiplicative { ($A:ty, $init:expr) => { + #[experimental = "trait is experimental"] impl> MultiplicativeIterator<$A> for T { #[inline] - fn product(&mut self) -> $A { + fn product(self) -> $A { self.fold($init, |acc, x| acc * x) } } @@ -860,7 +926,8 @@ impl_multiplicative!(f32, 1.0) impl_multiplicative!(f64, 1.0) /// A trait for iterators over elements which can be compared to one another. -pub trait OrdIterator { +#[unstable = "recently renamed for new extension trait conventions"] +pub trait IteratorOrdExt { /// Consumes the entire iterator to return the maximum element. /// /// # Example @@ -869,7 +936,7 @@ pub trait OrdIterator { /// let a = [1i, 2, 3, 4, 5]; /// assert!(a.iter().max().unwrap() == &5); /// ``` - fn max(&mut self) -> Option; + fn max(self) -> Option; /// Consumes the entire iterator to return the minimum element. /// @@ -879,7 +946,7 @@ pub trait OrdIterator { /// let a = [1i, 2, 3, 4, 5]; /// assert!(a.iter().min().unwrap() == &1); /// ``` - fn min(&mut self) -> Option; + fn min(self) -> Option; /// `min_max` finds the minimum and maximum elements in the iterator. /// @@ -914,12 +981,13 @@ pub trait OrdIterator { /// let v = [1i, 1, 1, 1]; /// assert!(v.iter().min_max() == MinMax(&1, &1)); /// ``` - fn min_max(&mut self) -> MinMaxResult; + fn min_max(self) -> MinMaxResult; } -impl> OrdIterator for T { +#[unstable = "trait is unstable"] +impl> IteratorOrdExt for T { #[inline] - fn max(&mut self) -> Option { + fn max(self) -> Option { self.fold(None, |max, x| { match max { None => Some(x), @@ -929,7 +997,7 @@ impl> OrdIterator for T { } #[inline] - fn min(&mut self) -> Option { + fn min(self) -> Option { self.fold(None, |min, x| { match min { None => Some(x), @@ -938,7 +1006,7 @@ impl> OrdIterator for T { }) } - fn min_max(&mut self) -> MinMaxResult { + fn min_max(mut self) -> MinMaxResult { let (mut min, mut max) = match self.next() { None => return NoElements, Some(x) => { @@ -982,8 +1050,9 @@ impl> OrdIterator for T { } } -/// `MinMaxResult` is an enum returned by `min_max`. See `OrdIterator::min_max` for more detail. +/// `MinMaxResult` is an enum returned by `min_max`. See `IteratorOrdExt::min_max` for more detail. #[deriving(Clone, PartialEq, Show)] +#[unstable = "waiting on namespaced enum conventions"] pub enum MinMaxResult { /// Empty iterator NoElements, @@ -995,6 +1064,7 @@ pub enum MinMaxResult { MinMax(T, T) } +#[stable] impl MinMaxResult { /// `into_option` creates an `Option` of type `(T,T)`. The returned `Option` has variant /// `None` if and only if the `MinMaxResult` has variant `NoElements`. Otherwise variant @@ -1025,14 +1095,15 @@ impl MinMaxResult { } /// A trait for iterators that contain cloneable elements -pub trait CloneIteratorExt { +#[unstable = "recently renamed for extension trait conventions"] +pub trait IteratorCloneExt { /// Creates an iterator that clones the elements it yields. Useful for converting an /// Iterator<&T> to an Iterator. fn cloned(self) -> Cloned; } - -impl, I: Iterator> CloneIteratorExt for I { +#[unstable = "trait is unstable"] +impl, I: Iterator> IteratorCloneExt for I { fn cloned(self) -> Cloned { Cloned { it: self } } @@ -1060,28 +1131,31 @@ impl, I: DoubleEndedIterator> } } -impl, I: ExactSize> ExactSize for Cloned {} +#[unstable = "trait is unstable"] +impl, I: ExactSizeIterator> ExactSizeIterator for Cloned {} -/// A trait for iterators that are cloneable. -pub trait CloneableIterator { +#[unstable = "recently renamed for extension trait conventions"] +/// An extension trait for cloneable iterators. +pub trait CloneIteratorExt { /// Repeats an iterator endlessly /// /// # Example /// /// ```rust - /// use std::iter::{CloneableIterator, count}; + /// use std::iter::{CloneIteratorExt, count}; /// /// let a = count(1i,1i).take(1); /// let mut cy = a.cycle(); /// assert_eq!(cy.next(), Some(1)); /// assert_eq!(cy.next(), Some(1)); /// ``` + #[stable] fn cycle(self) -> Cycle; } -impl> CloneableIterator for T { +impl CloneIteratorExt for I where I: Iterator + Clone { #[inline] - fn cycle(self) -> Cycle { + fn cycle(self) -> Cycle { Cycle{orig: self.clone(), iter: self} } } @@ -1089,11 +1163,13 @@ impl> CloneableIterator for T { /// An iterator that repeats endlessly #[deriving(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Cycle { orig: T, iter: T, } +#[unstable = "trait is unstable"] impl> Iterator for Cycle { #[inline] fn next(&mut self) -> Option { @@ -1114,6 +1190,7 @@ impl> Iterator for Cycle { } } +#[experimental = "trait is experimental"] impl> RandomAccessIterator for Cycle { #[inline] fn indexable(&self) -> uint { @@ -1141,12 +1218,14 @@ impl> RandomAccessIterator for Cycle /// An iterator which strings two iterators together #[deriving(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Chain { a: T, b: U, flag: bool, } +#[unstable = "trait is unstable"] impl, U: Iterator> Iterator for Chain { #[inline] fn next(&mut self) -> Option { @@ -1178,6 +1257,7 @@ impl, U: Iterator> Iterator for Chain { } } +#[unstable = "trait is unstable"] impl, U: DoubleEndedIterator> DoubleEndedIterator for Chain { #[inline] @@ -1189,6 +1269,7 @@ for Chain { } } +#[experimental = "trait is experimental"] impl, U: RandomAccessIterator> RandomAccessIterator for Chain { #[inline] @@ -1211,11 +1292,13 @@ for Chain { /// An iterator which iterates two other iterators simultaneously #[deriving(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Zip { a: T, b: U } +#[unstable = "trait is unstable"] impl, U: Iterator> Iterator<(A, B)> for Zip { #[inline] fn next(&mut self) -> Option<(A, B)> { @@ -1246,7 +1329,8 @@ impl, U: Iterator> Iterator<(A, B)> for Zip { } } -impl, U: ExactSize> DoubleEndedIterator<(A, B)> +#[unstable = "trait is unstable"] +impl, U: ExactSizeIterator> DoubleEndedIterator<(A, B)> for Zip { #[inline] fn next_back(&mut self) -> Option<(A, B)> { @@ -1268,6 +1352,7 @@ for Zip { } } +#[experimental = "trait is experimental"] impl, U: RandomAccessIterator> RandomAccessIterator<(A, B)> for Zip { #[inline] @@ -1289,6 +1374,7 @@ RandomAccessIterator<(A, B)> for Zip { /// An iterator which maps the values of `iter` with `f` #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Map<'a, A, B, T> { iter: T, f: |A|: 'a -> B @@ -1304,6 +1390,7 @@ impl<'a, A, B, T> Map<'a, A, B, T> { } } +#[unstable = "trait is unstable"] impl<'a, A, B, T: Iterator> Iterator for Map<'a, A, B, T> { #[inline] fn next(&mut self) -> Option { @@ -1317,6 +1404,7 @@ impl<'a, A, B, T: Iterator> Iterator for Map<'a, A, B, T> { } } +#[unstable = "trait is unstable"] impl<'a, A, B, T: DoubleEndedIterator> DoubleEndedIterator for Map<'a, A, B, T> { #[inline] fn next_back(&mut self) -> Option { @@ -1325,6 +1413,7 @@ impl<'a, A, B, T: DoubleEndedIterator> DoubleEndedIterator for Map<'a, A, } } +#[experimental = "trait is experimental"] impl<'a, A, B, T: RandomAccessIterator> RandomAccessIterator for Map<'a, A, B, T> { #[inline] fn indexable(&self) -> uint { @@ -1340,11 +1429,13 @@ impl<'a, A, B, T: RandomAccessIterator> RandomAccessIterator for Map<'a, A /// An iterator which filters the elements of `iter` with `predicate` #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Filter<'a, A, T> { iter: T, predicate: |&A|: 'a -> bool } +#[unstable = "trait is unstable"] impl<'a, A, T: Iterator> Iterator for Filter<'a, A, T> { #[inline] fn next(&mut self) -> Option { @@ -1365,6 +1456,7 @@ impl<'a, A, T: Iterator> Iterator for Filter<'a, A, T> { } } +#[unstable = "trait is unstable"] impl<'a, A, T: DoubleEndedIterator> DoubleEndedIterator for Filter<'a, A, T> { #[inline] fn next_back(&mut self) -> Option { @@ -1379,11 +1471,13 @@ impl<'a, A, T: DoubleEndedIterator> DoubleEndedIterator for Filter<'a, A, /// An iterator which uses `f` to both filter and map elements from `iter` #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct FilterMap<'a, A, B, T> { iter: T, f: |A|: 'a -> Option } +#[unstable = "trait is unstable"] impl<'a, A, B, T: Iterator> Iterator for FilterMap<'a, A, B, T> { #[inline] fn next(&mut self) -> Option { @@ -1403,6 +1497,7 @@ impl<'a, A, B, T: Iterator> Iterator for FilterMap<'a, A, B, T> { } } +#[unstable = "trait is unstable"] impl<'a, A, B, T: DoubleEndedIterator> DoubleEndedIterator for FilterMap<'a, A, B, T> { #[inline] @@ -1420,11 +1515,13 @@ for FilterMap<'a, A, B, T> { /// An iterator which yields the current count and the element during iteration #[deriving(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Enumerate { iter: T, count: uint } +#[unstable = "trait is unstable"] impl> Iterator<(uint, A)> for Enumerate { #[inline] fn next(&mut self) -> Option<(uint, A)> { @@ -1444,7 +1541,8 @@ impl> Iterator<(uint, A)> for Enumerate { } } -impl> DoubleEndedIterator<(uint, A)> for Enumerate { +#[unstable = "trait is unstable"] +impl> DoubleEndedIterator<(uint, A)> for Enumerate { #[inline] fn next_back(&mut self) -> Option<(uint, A)> { match self.iter.next_back() { @@ -1457,6 +1555,7 @@ impl> DoubleEndedIterator<(uint, A)> for Enumerate { } } +#[experimental = "trait is experimental"] impl> RandomAccessIterator<(uint, A)> for Enumerate { #[inline] fn indexable(&self) -> uint { @@ -1474,11 +1573,13 @@ impl> RandomAccessIterator<(uint, A)> for Enumerat /// An iterator with a `peek()` that returns an optional reference to the next element. #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Peekable { iter: T, peeked: Option, } +#[unstable = "trait is unstable"] impl> Iterator for Peekable { #[inline] fn next(&mut self) -> Option { @@ -1502,6 +1603,7 @@ impl> Iterator for Peekable { } } +#[stable] impl<'a, A, T: Iterator> Peekable { /// Return a reference to the next element of the iterator with out advancing it, /// or None if the iterator is exhausted. @@ -1525,12 +1627,14 @@ impl<'a, A, T: Iterator> Peekable { /// An iterator which rejects elements while `predicate` is true #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct SkipWhile<'a, A, T> { iter: T, flag: bool, predicate: |&A|: 'a -> bool } +#[unstable = "trait is unstable"] impl<'a, A, T: Iterator> Iterator for SkipWhile<'a, A, T> { #[inline] fn next(&mut self) -> Option { @@ -1552,12 +1656,14 @@ impl<'a, A, T: Iterator> Iterator for SkipWhile<'a, A, T> { /// An iterator which only accepts elements while `predicate` is true #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct TakeWhile<'a, A, T> { iter: T, flag: bool, predicate: |&A|: 'a -> bool } +#[unstable = "trait is unstable"] impl<'a, A, T: Iterator> Iterator for TakeWhile<'a, A, T> { #[inline] fn next(&mut self) -> Option { @@ -1588,11 +1694,13 @@ impl<'a, A, T: Iterator> Iterator for TakeWhile<'a, A, T> { /// An iterator which skips over `n` elements of `iter`. #[deriving(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Skip { iter: T, n: uint } +#[unstable = "trait is unstable"] impl> Iterator for Skip { #[inline] fn next(&mut self) -> Option { @@ -1634,6 +1742,7 @@ impl> Iterator for Skip { } } +#[experimental = "trait is experimental"] impl> RandomAccessIterator for Skip { #[inline] fn indexable(&self) -> uint { @@ -1653,11 +1762,13 @@ impl> RandomAccessIterator for Skip { /// An iterator which only iterates over the first `n` iterations of `iter`. #[deriving(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Take { iter: T, n: uint } +#[unstable = "trait is unstable"] impl> Iterator for Take { #[inline] fn next(&mut self) -> Option { @@ -1684,6 +1795,7 @@ impl> Iterator for Take { } } +#[experimental = "trait is experimental"] impl> RandomAccessIterator for Take { #[inline] fn indexable(&self) -> uint { @@ -1703,6 +1815,7 @@ impl> RandomAccessIterator for Take { /// An iterator to maintain state while iterating another iterator #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[unstable = "waiting for unboxed closures"] pub struct Scan<'a, A, B, T, St> { iter: T, f: |&mut St, A|: 'a -> Option, @@ -1711,6 +1824,7 @@ pub struct Scan<'a, A, B, T, St> { pub state: St, } +#[unstable = "trait is unstable"] impl<'a, A, B, T: Iterator, St> Iterator for Scan<'a, A, B, T, St> { #[inline] fn next(&mut self) -> Option { @@ -1728,6 +1842,7 @@ impl<'a, A, B, T: Iterator, St> Iterator for Scan<'a, A, B, T, St> { /// and yields the elements of the produced iterators /// #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[unstable = "waiting for unboxed closures"] pub struct FlatMap<'a, A, T, U> { iter: T, f: |A|: 'a -> U, @@ -1735,6 +1850,7 @@ pub struct FlatMap<'a, A, T, U> { backiter: Option, } +#[unstable = "trait is unstable"] impl<'a, A, T: Iterator, B, U: Iterator> Iterator for FlatMap<'a, A, T, U> { #[inline] fn next(&mut self) -> Option { @@ -1763,6 +1879,7 @@ impl<'a, A, T: Iterator, B, U: Iterator> Iterator for FlatMap<'a, A, T, } } +#[unstable = "trait is unstable"] impl<'a, A, T: DoubleEndedIterator, B, U: DoubleEndedIterator> DoubleEndedIterator @@ -1788,11 +1905,13 @@ impl<'a, /// yields `None` once. #[deriving(Clone)] #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[stable] pub struct Fuse { iter: T, done: bool } +#[unstable = "trait is unstable"] impl> Iterator for Fuse { #[inline] fn next(&mut self) -> Option { @@ -1819,6 +1938,7 @@ impl> Iterator for Fuse { } } +#[unstable = "trait is unstable"] impl> DoubleEndedIterator for Fuse { #[inline] fn next_back(&mut self) -> Option { @@ -1837,6 +1957,7 @@ impl> DoubleEndedIterator for Fuse { } // Allow RandomAccessIterators to be fused without affecting random-access behavior +#[experimental = "trait is experimental"] impl> RandomAccessIterator for Fuse { #[inline] fn indexable(&self) -> uint { @@ -1849,6 +1970,7 @@ impl> RandomAccessIterator for Fuse { } } +#[experimental = "seems marginal"] impl Fuse { /// Resets the fuse such that the next call to .next() or .next_back() will /// call the underlying iterator again even if it previously returned None. @@ -1861,6 +1983,7 @@ impl Fuse { /// An iterator that calls a function with a reference to each /// element before yielding it. #[must_use = "iterator adaptors are lazy and do nothing unless consumed"] +#[unstable = "waiting for unboxed closures"] pub struct Inspect<'a, A, T> { iter: T, f: |&A|: 'a @@ -1878,6 +2001,7 @@ impl<'a, A, T> Inspect<'a, A, T> { } } +#[unstable = "trait is unstable"] impl<'a, A, T: Iterator> Iterator for Inspect<'a, A, T> { #[inline] fn next(&mut self) -> Option { @@ -1891,6 +2015,7 @@ impl<'a, A, T: Iterator> Iterator for Inspect<'a, A, T> { } } +#[unstable = "trait is unstable"] impl<'a, A, T: DoubleEndedIterator> DoubleEndedIterator for Inspect<'a, A, T> { #[inline] @@ -1900,6 +2025,7 @@ for Inspect<'a, A, T> { } } +#[experimental = "trait is experimental"] impl<'a, A, T: RandomAccessIterator> RandomAccessIterator for Inspect<'a, A, T> { #[inline] @@ -1915,12 +2041,14 @@ for Inspect<'a, A, T> { } /// An iterator which just modifies the contained state throughout iteration. +#[experimental] pub struct Unfold<'a, A, St> { f: |&mut St|: 'a -> Option, /// Internal state that will be yielded on the next iteration pub state: St, } +#[experimental] impl<'a, A, St> Unfold<'a, A, St> { /// Creates a new iterator with the specified closure as the "iterator /// function" and an initial state to eventually pass to the iterator @@ -1934,6 +2062,7 @@ impl<'a, A, St> Unfold<'a, A, St> { } } +#[experimental] impl<'a, A, St> Iterator for Unfold<'a, A, St> { #[inline] fn next(&mut self) -> Option { @@ -1950,6 +2079,7 @@ impl<'a, A, St> Iterator for Unfold<'a, A, St> { /// An infinite iterator starting at `start` and advancing by `step` with each /// iteration #[deriving(Clone)] +#[unstable = "may be renamed"] pub struct Counter { /// The current state the counter is at (next value to be yielded) state: A, @@ -1959,10 +2089,12 @@ pub struct Counter { /// Creates a new counter with the specified start/step #[inline] +#[unstable = "may be renamed"] pub fn count(start: A, step: A) -> Counter { Counter{state: start, step: step} } +#[unstable = "trait is unstable"] impl + Clone> Iterator for Counter { #[inline] fn next(&mut self) -> Option { @@ -1979,6 +2111,7 @@ impl + Clone> Iterator for Counter { /// An iterator over the range [start, stop) #[deriving(Clone)] +#[unstable = "may be refactored due to numerics reform or ops reform"] pub struct Range { state: A, stop: A, @@ -2008,6 +2141,7 @@ pub fn range(start: A, stop: A) -> Range { } // FIXME: #10414: Unfortunate type bound +#[unstable = "trait is unstable"] impl Iterator for Range { #[inline] fn next(&mut self) -> Option { @@ -2055,6 +2189,7 @@ impl Iterator for Range { /// `Int` is required to ensure the range will be the same regardless of /// the direction it is consumed. +#[unstable = "trait is unstable"] impl DoubleEndedIterator for Range { #[inline] fn next_back(&mut self) -> Option { @@ -2069,6 +2204,7 @@ impl DoubleEndedIterator for Range { /// An iterator over the range [start, stop] #[deriving(Clone)] +#[unstable = "may be refactored due to numerics reform or ops reform"] pub struct RangeInclusive { range: Range, done: bool, @@ -2076,6 +2212,7 @@ pub struct RangeInclusive { /// Return an iterator over the range [start, stop] #[inline] +#[unstable = "may be refactored due to numerics reform or ops reform"] pub fn range_inclusive(start: A, stop: A) -> RangeInclusive { RangeInclusive { range: range(start, stop), @@ -2083,6 +2220,7 @@ pub fn range_inclusive(start: A, stop: A) -> RangeInclusive { } } +#[unstable = "trait is unstable"] impl Iterator for RangeInclusive { #[inline] fn next(&mut self) -> Option { @@ -2115,6 +2253,7 @@ impl Iterator for RangeInclusive { } } +#[unstable = "trait is unstable"] impl DoubleEndedIterator for RangeInclusive { #[inline] fn next_back(&mut self) -> Option { @@ -2133,6 +2272,7 @@ impl DoubleEndedIterator for RangeInclusive { /// An iterator over the range [start, stop) by `step`. It handles overflow by stopping. #[deriving(Clone)] +#[unstable = "may be refactored due to numerics reform or ops reform"] pub struct RangeStep { state: A, stop: A, @@ -2142,11 +2282,13 @@ pub struct RangeStep { /// Return an iterator over the range [start, stop) by `step`. It handles overflow by stopping. #[inline] +#[unstable = "may be refactored due to numerics reform or ops reform"] pub fn range_step(start: A, stop: A, step: A) -> RangeStep { let rev = step < Int::zero(); RangeStep{state: start, stop: stop, step: step, rev: rev} } +#[unstable = "trait is unstable"] impl Iterator for RangeStep { #[inline] fn next(&mut self) -> Option { @@ -2165,6 +2307,7 @@ impl Iterator for RangeStep { /// An iterator over the range [start, stop] by `step`. It handles overflow by stopping. #[deriving(Clone)] +#[unstable = "may be refactored due to numerics reform or ops reform"] pub struct RangeStepInclusive { state: A, stop: A, @@ -2175,6 +2318,7 @@ pub struct RangeStepInclusive { /// Return an iterator over the range [start, stop] by `step`. It handles overflow by stopping. #[inline] +#[unstable = "may be refactored due to numerics reform or ops reform"] pub fn range_step_inclusive(start: A, stop: A, step: A) -> RangeStepInclusive { let rev = step < Int::zero(); RangeStepInclusive { @@ -2186,6 +2330,7 @@ pub fn range_step_inclusive(start: A, stop: A, step: A) -> RangeStepIncl } } +#[unstable = "trait is unstable"] impl Iterator for RangeStepInclusive { #[inline] fn next(&mut self) -> Option { @@ -2205,6 +2350,7 @@ impl Iterator for RangeStepInclusive { /// An iterator that repeats an element endlessly #[deriving(Clone)] +#[stable] pub struct Repeat { element: A } @@ -2212,11 +2358,13 @@ pub struct Repeat { impl Repeat { /// Create a new `Repeat` that endlessly repeats the element `elt`. #[inline] + #[deprecated = "use iter::repeat instead"] pub fn new(elt: A) -> Repeat { Repeat{element: elt} } } +#[unstable = "trait is unstable"] impl Iterator for Repeat { #[inline] fn next(&mut self) -> Option { self.idx(0) } @@ -2224,11 +2372,13 @@ impl Iterator for Repeat { fn size_hint(&self) -> (uint, Option) { (uint::MAX, None) } } +#[unstable = "trait is unstable"] impl DoubleEndedIterator for Repeat { #[inline] fn next_back(&mut self) -> Option { self.idx(0) } } +#[experimental = "trait is experimental"] impl RandomAccessIterator for Repeat { #[inline] fn indexable(&self) -> uint { uint::MAX } @@ -2240,10 +2390,12 @@ type IterateState<'a, T> = (|T|: 'a -> T, Option, bool); /// An iterator that repeatedly applies a given function, starting /// from a given seed value. +#[experimental] pub type Iterate<'a, T> = Unfold<'a, T, IterateState<'a, T>>; /// Create a new iterator that produces an infinite sequence of /// repeated applications of the given function `f`. +#[experimental] pub fn iterate<'a, T: Clone>(seed: T, f: |T|: 'a -> T) -> Iterate<'a, T> { Unfold::new((f, Some(seed), true), |st| { let &(ref mut f, ref mut val, ref mut first) = st; @@ -2262,8 +2414,10 @@ pub fn iterate<'a, T: Clone>(seed: T, f: |T|: 'a -> T) -> Iterate<'a, T> { } /// Create a new iterator that endlessly repeats the element `elt`. +#[inline] +#[stable] pub fn repeat(elt: T) -> Repeat { - Repeat::new(elt) + Repeat{element: elt} } /// Functions for lexicographical ordering of sequences. @@ -2273,6 +2427,7 @@ pub fn repeat(elt: T) -> Repeat { /// /// If two sequences are equal up until the point where one ends, /// the shorter sequence compares less. +#[experimental = "likely to be removed after cmp reform"] pub mod order { use cmp; use cmp::{Eq, Ord, PartialOrd, PartialEq};