12
12
//!
13
13
//! # The `Iterator` trait
14
14
//!
15
- //! This module defines Rust's core iteration trait. The `Iterator` trait has one
16
- //! unimplemented method, `next`. All other methods are derived through default
17
- //! methods to perform operations such as `zip`, `chain`, `enumerate`, and `fold`.
15
+ //! This module defines Rust's core iteration trait. The `Iterator` trait has
16
+ //! one unimplemented method, `next`. All other methods are derived through
17
+ //! default methods to perform operations such as `zip`, `chain`, `enumerate`,
18
+ //! and `fold`.
18
19
//!
19
20
//! The goal of this module is to unify iteration across all containers in Rust.
20
- //! An iterator can be considered as a state machine which is used to track which
21
- //! element will be yielded next.
21
+ //! An iterator can be considered as a state machine which is used to track
22
+ //! which element will be yielded next.
22
23
//!
23
- //! There are various extensions also defined in this module to assist with various
24
- //! types of iteration, such as the `DoubleEndedIterator` for iterating in reverse,
25
- //! the `FromIterator` trait for creating a container from an iterator, and much
26
- //! more.
24
+ //! There are various extensions also defined in this module to assist with
25
+ //! various types of iteration, such as the `DoubleEndedIterator` for iterating
26
+ //! in reverse, the `FromIterator` trait for creating a container from an
27
+ //! iterator, and much more.
27
28
//!
28
29
//! ## Rust's `for` loop
29
30
//!
30
31
//! The special syntax used by rust's `for` loop is based around the `Iterator`
31
- //! trait defined in this module. For loops can be viewed as a syntactical expansion
32
- //! into a `loop`, for example, the `for` loop in this example is essentially
33
- //! translated to the `loop` below.
32
+ //! trait defined in this module. For loops can be viewed as a syntactical
33
+ //! expansion into a `loop`, for example, the `for` loop in this example is
34
+ //! essentially translated to the `loop` below.
34
35
//!
35
36
//! ```
36
37
//! let values = vec![1, 2, 3];
@@ -64,8 +65,8 @@ use cmp::Ord;
64
65
use default:: Default ;
65
66
use marker;
66
67
use mem;
67
- use num:: { Int , Zero , One , ToPrimitive } ;
68
- use ops:: { Add , Sub , FnMut , RangeFrom } ;
68
+ use num:: { Int , Zero , One } ;
69
+ use ops:: { self , Add , Sub , FnMut , RangeFrom } ;
69
70
use option:: Option :: { self , Some , None } ;
70
71
use marker:: Sized ;
71
72
use usize;
@@ -84,21 +85,22 @@ fn _assert_is_object_safe(_: &Iterator) {}
84
85
/// else.
85
86
#[ lang="iterator" ]
86
87
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
87
- #[ rustc_on_unimplemented = "`{Self}` is not an iterator; maybe try calling `.iter()` or a similar \
88
- method"]
88
+ #[ rustc_on_unimplemented = "`{Self}` is not an iterator; maybe try calling \
89
+ `.iter()` or a similar method"]
89
90
pub trait Iterator {
90
91
/// The type of the elements being iterated
91
92
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
92
93
type Item ;
93
94
94
- /// Advance the iterator and return the next value. Return `None` when the end is reached.
95
+ /// Advance the iterator and return the next value. Return `None` when the
96
+ /// end is reached.
95
97
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
96
98
fn next ( & mut self ) -> Option < Self :: Item > ;
97
99
98
100
/// Returns a lower and upper bound on the remaining length of the iterator.
99
101
///
100
- /// An upper bound of `None` means either there is no known upper bound, or the upper bound
101
- /// does not fit within a `usize`.
102
+ /// An upper bound of `None` means either there is no known upper bound, or
103
+ /// the upper bound does not fit within a `usize`.
102
104
#[ inline]
103
105
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
104
106
fn size_hint ( & self ) -> ( usize , Option < usize > ) { ( 0 , None ) }
@@ -274,7 +276,8 @@ pub trait Iterator {
274
276
/// iterator plus the current index of iteration.
275
277
///
276
278
/// `enumerate` keeps its count as a `usize`. If you want to count by a
277
- /// different sized integer, the `zip` function provides similar functionality.
279
+ /// different sized integer, the `zip` function provides similar
280
+ /// functionality.
278
281
///
279
282
/// # Examples
280
283
///
@@ -612,7 +615,8 @@ pub trait Iterator {
612
615
true
613
616
}
614
617
615
- /// Tests whether any element of an iterator satisfies the specified predicate.
618
+ /// Tests whether any element of an iterator satisfies the specified
619
+ /// predicate.
616
620
///
617
621
/// Does not consume the iterator past the first found element.
618
622
///
@@ -776,7 +780,8 @@ pub trait Iterator {
776
780
/// element in the iterator and all elements are equal.
777
781
///
778
782
/// On an iterator of length `n`, `min_max` does `1.5 * n` comparisons,
779
- /// and so is faster than calling `min` and `max` separately which does `2 * n` comparisons.
783
+ /// and so is faster than calling `min` and `max` separately which does `2 *
784
+ /// n` comparisons.
780
785
///
781
786
/// # Examples
782
787
///
@@ -810,10 +815,11 @@ pub trait Iterator {
810
815
} ;
811
816
812
817
loop {
813
- // `first` and `second` are the two next elements we want to look at.
814
- // We first compare `first` and `second` (#1). The smaller one is then compared to
815
- // current minimum (#2). The larger one is compared to current maximum (#3). This
816
- // way we do 3 comparisons for 2 elements.
818
+ // `first` and `second` are the two next elements we want to look
819
+ // at. We first compare `first` and `second` (#1). The smaller one
820
+ // is then compared to current minimum (#2). The larger one is
821
+ // compared to current maximum (#3). This way we do 3 comparisons
822
+ // for 2 elements.
817
823
let first = match self . next ( ) {
818
824
None => break ,
819
825
Some ( x) => x
@@ -1038,7 +1044,8 @@ pub trait FromIterator<A> {
1038
1044
/// assert_eq!(colors_set.len(), 3);
1039
1045
/// ```
1040
1046
///
1041
- /// `FromIterator` is more commonly used implicitly via the `Iterator::collect` method:
1047
+ /// `FromIterator` is more commonly used implicitly via the
1048
+ /// `Iterator::collect` method:
1042
1049
///
1043
1050
/// ```
1044
1051
/// use std::collections::HashSet;
@@ -1105,12 +1112,13 @@ impl<'a, I: DoubleEndedIterator + ?Sized> DoubleEndedIterator for &'a mut I {
1105
1112
1106
1113
/// An object implementing random access indexing by `usize`
1107
1114
///
1108
- /// A `RandomAccessIterator` should be either infinite or a `DoubleEndedIterator`.
1109
- /// Calling `next()` or `next_back()` on a `RandomAccessIterator`
1110
- /// reduces the indexable range accordingly. That is, `it.idx(1)` will become `it.idx(0)`
1111
- /// after `it.next()` is called.
1115
+ /// A `RandomAccessIterator` should be either infinite or a
1116
+ /// `DoubleEndedIterator`. Calling `next()` or `next_back()` on a
1117
+ /// `RandomAccessIterator` reduces the indexable range accordingly. That is,
1118
+ /// `it.idx(1)` will become `it.idx(0)` after `it.next()` is called.
1112
1119
#[ unstable( feature = "core" ,
1113
- reason = "not widely used, may be better decomposed into Index and ExactSizeIterator" ) ]
1120
+ reason = "not widely used, may be better decomposed into Index \
1121
+ and ExactSizeIterator") ]
1114
1122
pub trait RandomAccessIterator : Iterator {
1115
1123
/// Return the number of indexable elements. At most `std::usize::MAX`
1116
1124
/// elements are indexable, even if the iterator represents a longer range.
@@ -1155,13 +1163,15 @@ impl<I: ExactSizeIterator, F> ExactSizeIterator for Inspect<I, F> where
1155
1163
F : FnMut ( & I :: Item ) ,
1156
1164
{ }
1157
1165
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1158
- impl < I > ExactSizeIterator for Rev < I > where I : ExactSizeIterator + DoubleEndedIterator { }
1166
+ impl < I > ExactSizeIterator for Rev < I >
1167
+ where I : ExactSizeIterator + DoubleEndedIterator { }
1159
1168
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1160
1169
impl < B , I : ExactSizeIterator , F > ExactSizeIterator for Map < I , F > where
1161
1170
F : FnMut ( I :: Item ) -> B ,
1162
1171
{ }
1163
1172
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
1164
- impl < A , B > ExactSizeIterator for Zip < A , B > where A : ExactSizeIterator , B : ExactSizeIterator { }
1173
+ impl < A , B > ExactSizeIterator for Zip < A , B >
1174
+ where A : ExactSizeIterator , B : ExactSizeIterator { }
1165
1175
1166
1176
/// An double-ended iterator with the direction inverted
1167
1177
#[ derive( Clone ) ]
@@ -1188,7 +1198,9 @@ impl<I> DoubleEndedIterator for Rev<I> where I: DoubleEndedIterator {
1188
1198
}
1189
1199
1190
1200
#[ unstable( feature = "core" , reason = "trait is experimental" ) ]
1191
- impl < I > RandomAccessIterator for Rev < I > where I : DoubleEndedIterator + RandomAccessIterator {
1201
+ impl < I > RandomAccessIterator for Rev < I >
1202
+ where I : DoubleEndedIterator + RandomAccessIterator
1203
+ {
1192
1204
#[ inline]
1193
1205
fn indexable ( & self ) -> usize { self . iter . indexable ( ) }
1194
1206
#[ inline]
@@ -1291,7 +1303,8 @@ impl_multiplicative! { usize, 1 }
1291
1303
impl_multiplicative ! { f32 , 1.0 }
1292
1304
impl_multiplicative ! { f64 , 1.0 }
1293
1305
1294
- /// `MinMaxResult` is an enum returned by `min_max`. See `Iterator::min_max` for more detail.
1306
+ /// `MinMaxResult` is an enum returned by `min_max`. See `Iterator::min_max` for
1307
+ /// more detail.
1295
1308
#[ derive( Clone , PartialEq , Debug ) ]
1296
1309
#[ unstable( feature = "core" ,
1297
1310
reason = "unclear whether such a fine-grained result is widely useful" ) ]
@@ -1302,15 +1315,17 @@ pub enum MinMaxResult<T> {
1302
1315
/// Iterator with one element, so the minimum and maximum are the same
1303
1316
OneElement ( T ) ,
1304
1317
1305
- /// More than one element in the iterator, the first element is not larger than the second
1318
+ /// More than one element in the iterator, the first element is not larger
1319
+ /// than the second
1306
1320
MinMax ( T , T )
1307
1321
}
1308
1322
1309
1323
impl < T : Clone > MinMaxResult < T > {
1310
- /// `into_option` creates an `Option` of type `(T,T)`. The returned `Option` has variant
1311
- /// `None` if and only if the `MinMaxResult` has variant `NoElements`. Otherwise variant
1312
- /// `Some(x,y)` is returned where `x <= y`. If `MinMaxResult` has variant `OneElement(x)`,
1313
- /// performing this operation will make one clone of `x`.
1324
+ /// `into_option` creates an `Option` of type `(T,T)`. The returned `Option`
1325
+ /// has variant `None` if and only if the `MinMaxResult` has variant
1326
+ /// `NoElements`. Otherwise variant `Some(x,y)` is returned where `x <= y`.
1327
+ /// If `MinMaxResult` has variant `OneElement(x)`, performing this operation
1328
+ /// will make one clone of `x`.
1314
1329
///
1315
1330
/// # Examples
1316
1331
///
@@ -2522,7 +2537,7 @@ impl<A: Step> RangeFrom<A> {
2522
2537
}
2523
2538
2524
2539
#[ allow( deprecated) ]
2525
- impl < A : Step > :: ops:: Range < A > {
2540
+ impl < A : Step > ops:: Range < A > {
2526
2541
/// Creates an iterator with the same range, but stepping by the
2527
2542
/// given amount at each iteration.
2528
2543
///
@@ -2588,7 +2603,9 @@ pub struct RangeInclusive<A> {
2588
2603
#[ inline]
2589
2604
#[ unstable( feature = "core" ,
2590
2605
reason = "likely to be replaced by range notation and adapters" ) ]
2591
- pub fn range_inclusive < A : Int > ( start : A , stop : A ) -> RangeInclusive < A > {
2606
+ pub fn range_inclusive < A > ( start : A , stop : A ) -> RangeInclusive < A >
2607
+ where A : Step + One + Clone
2608
+ {
2592
2609
RangeInclusive {
2593
2610
range : start..stop,
2594
2611
done : false ,
@@ -2597,7 +2614,7 @@ pub fn range_inclusive<A: Int>(start: A, stop: A) -> RangeInclusive<A> {
2597
2614
2598
2615
#[ unstable( feature = "core" ,
2599
2616
reason = "likely to be replaced by range notation and adapters" ) ]
2600
- impl < A : Int + ToPrimitive > Iterator for RangeInclusive < A > {
2617
+ impl < A : Step + One + Clone > Iterator for RangeInclusive < A > {
2601
2618
type Item = A ;
2602
2619
2603
2620
#[ inline]
@@ -2633,12 +2650,15 @@ impl<A: Int + ToPrimitive> Iterator for RangeInclusive<A> {
2633
2650
2634
2651
#[ unstable( feature = "core" ,
2635
2652
reason = "likely to be replaced by range notation and adapters" ) ]
2636
- impl < A : Int + ToPrimitive > DoubleEndedIterator for RangeInclusive < A > {
2653
+ impl < A > DoubleEndedIterator for RangeInclusive < A >
2654
+ where A : Step + One + Clone ,
2655
+ for < ' a > & ' a A : Sub < Output =A >
2656
+ {
2637
2657
#[ inline]
2638
2658
fn next_back ( & mut self ) -> Option < A > {
2639
2659
if self . range . end > self . range . start {
2640
2660
let result = self . range . end . clone ( ) ;
2641
- self . range . end = self . range . end - A :: one ( ) ;
2661
+ self . range . end = & self . range . end - & A :: one ( ) ;
2642
2662
Some ( result)
2643
2663
} else if !self . done && self . range . start == self . range . end {
2644
2664
self . done = true ;
@@ -2651,7 +2671,7 @@ impl<A: Int + ToPrimitive> DoubleEndedIterator for RangeInclusive<A> {
2651
2671
2652
2672
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2653
2673
#[ allow( deprecated) ]
2654
- impl < A : Step + Zero + Clone > Iterator for StepBy < A , :: ops:: Range < A > > {
2674
+ impl < A : Step + Zero + Clone > Iterator for StepBy < A , ops:: Range < A > > {
2655
2675
type Item = A ;
2656
2676
2657
2677
#[ inline]
@@ -2754,13 +2774,13 @@ impl<A: Int> Iterator for RangeStepInclusive<A> {
2754
2774
macro_rules! range_exact_iter_impl {
2755
2775
( $( $t: ty) * ) => ( $(
2756
2776
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2757
- impl ExactSizeIterator for :: ops:: Range <$t> { }
2777
+ impl ExactSizeIterator for ops:: Range <$t> { }
2758
2778
) * )
2759
2779
}
2760
2780
2761
2781
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2762
2782
#[ allow( deprecated) ]
2763
- impl < A : Step + One + Clone > Iterator for :: ops:: Range < A > {
2783
+ impl < A : Step + One + Clone > Iterator for ops:: Range < A > {
2764
2784
type Item = A ;
2765
2785
2766
2786
#[ inline]
@@ -2799,7 +2819,7 @@ range_exact_iter_impl!(usize u8 u16 u32 isize i8 i16 i32);
2799
2819
2800
2820
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2801
2821
#[ allow( deprecated) ]
2802
- impl < A : Step + One + Clone > DoubleEndedIterator for :: ops:: Range < A > where
2822
+ impl < A : Step + One + Clone > DoubleEndedIterator for ops:: Range < A > where
2803
2823
for < ' a > & ' a A : Sub < & ' a A , Output = A >
2804
2824
{
2805
2825
#[ inline]
@@ -2815,7 +2835,7 @@ impl<A: Step + One + Clone> DoubleEndedIterator for ::ops::Range<A> where
2815
2835
2816
2836
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
2817
2837
#[ allow( deprecated) ]
2818
- impl < A : Step + One > Iterator for :: ops:: RangeFrom < A > {
2838
+ impl < A : Step + One > Iterator for ops:: RangeFrom < A > {
2819
2839
type Item = A ;
2820
2840
2821
2841
#[ inline]
0 commit comments