pub struct Peekable<I>where
I: Iterator,{ /* private fields */ }
Expand description
Implementations§
source§impl<I> Peekable<I>where
I: Iterator,
impl<I> Peekable<I>where
I: Iterator,
sourcepub fn peek(&mut self) -> Option<&<I as Iterator>::Item>
pub fn peek(&mut self) -> Option<&<I as Iterator>::Item>
Returns a reference to the next() value without advancing the iterator.
Like next
, if there is a value, it is wrapped in a Some(T)
.
But if the iteration is over, None
is returned.
Because peek()
returns a reference, and many iterators iterate over
references, there can be a possibly confusing situation where the
return value is a double reference. You can see this effect in the
examples below.
§Examples
Basic usage:
let xs = [1, 2, 3];
let mut iter = xs.iter().peekable();
// peek() lets us see into the future
assert_eq!(iter.peek(), Some(&&1));
assert_eq!(iter.next(), Some(&1));
assert_eq!(iter.next(), Some(&2));
// The iterator does not advance even if we `peek` multiple times
assert_eq!(iter.peek(), Some(&&3));
assert_eq!(iter.peek(), Some(&&3));
assert_eq!(iter.next(), Some(&3));
// After the iterator is finished, so is `peek()`
assert_eq!(iter.peek(), None);
assert_eq!(iter.next(), None);
Run1.53.0 · sourcepub fn peek_mut(&mut self) -> Option<&mut <I as Iterator>::Item>
pub fn peek_mut(&mut self) -> Option<&mut <I as Iterator>::Item>
Returns a mutable reference to the next() value without advancing the iterator.
Like next
, if there is a value, it is wrapped in a Some(T)
.
But if the iteration is over, None
is returned.
Because peek_mut()
returns a reference, and many iterators iterate over
references, there can be a possibly confusing situation where the
return value is a double reference. You can see this effect in the examples
below.
§Examples
Basic usage:
let mut iter = [1, 2, 3].iter().peekable();
// Like with `peek()`, we can see into the future without advancing the iterator.
assert_eq!(iter.peek_mut(), Some(&mut &1));
assert_eq!(iter.peek_mut(), Some(&mut &1));
assert_eq!(iter.next(), Some(&1));
// Peek into the iterator and set the value behind the mutable reference.
if let Some(p) = iter.peek_mut() {
assert_eq!(*p, &2);
*p = &5;
}
// The value we put in reappears as the iterator continues.
assert_eq!(iter.collect::<Vec<_>>(), vec![&5, &3]);
Run1.51.0 · sourcepub fn next_if(
&mut self,
func: impl FnOnce(&<I as Iterator>::Item) -> bool
) -> Option<<I as Iterator>::Item>
pub fn next_if( &mut self, func: impl FnOnce(&<I as Iterator>::Item) -> bool ) -> Option<<I as Iterator>::Item>
Consume and return the next value of this iterator if a condition is true.
If func
returns true
for the next value of this iterator, consume and return it.
Otherwise, return None
.
§Examples
Consume a number if it’s equal to 0.
let mut iter = (0..5).peekable();
// The first item of the iterator is 0; consume it.
assert_eq!(iter.next_if(|&x| x == 0), Some(0));
// The next item returned is now 1, so `consume` will return `false`.
assert_eq!(iter.next_if(|&x| x == 0), None);
// `next_if` saves the value of the next item if it was not equal to `expected`.
assert_eq!(iter.next(), Some(1));
RunConsume any number less than 10.
let mut iter = (1..20).peekable();
// Consume all numbers less than 10
while iter.next_if(|&x| x < 10).is_some() {}
// The next value returned will be 10
assert_eq!(iter.next(), Some(10));
Run1.51.0 · sourcepub fn next_if_eq<T>(&mut self, expected: &T) -> Option<<I as Iterator>::Item>
pub fn next_if_eq<T>(&mut self, expected: &T) -> Option<<I as Iterator>::Item>
Consume and return the next item if it is equal to expected
.
§Example
Consume a number if it’s equal to 0.
let mut iter = (0..5).peekable();
// The first item of the iterator is 0; consume it.
assert_eq!(iter.next_if_eq(&0), Some(0));
// The next item returned is now 1, so `consume` will return `false`.
assert_eq!(iter.next_if_eq(&0), None);
// `next_if_eq` saves the value of the next item if it was not equal to `expected`.
assert_eq!(iter.next(), Some(1));
RunTrait Implementations§
1.38.0 · source§impl<I> DoubleEndedIterator for Peekable<I>where
I: DoubleEndedIterator,
impl<I> DoubleEndedIterator for Peekable<I>where
I: DoubleEndedIterator,
source§fn next_back(&mut self) -> Option<<Peekable<I> as Iterator>::Item>
fn next_back(&mut self) -> Option<<Peekable<I> as Iterator>::Item>
source§fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R
fn try_rfold<B, F, R>(&mut self, init: B, f: F) -> R
Iterator::try_fold()
: it takes
elements starting from the back of the iterator. Read moresource§fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
fn rfold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
source§fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero<usize>>
fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero<usize>>
iter_advance_by
#77404)n
elements. Read moresource§impl<I> ExactSizeIterator for Peekable<I>where
I: ExactSizeIterator,
impl<I> ExactSizeIterator for Peekable<I>where
I: ExactSizeIterator,
source§impl<I> Iterator for Peekable<I>where
I: Iterator,
impl<I> Iterator for Peekable<I>where
I: Iterator,
source§fn next(&mut self) -> Option<<I as Iterator>::Item>
fn next(&mut self) -> Option<<I as Iterator>::Item>
source§fn count(self) -> usize
fn count(self) -> usize
source§fn nth(&mut self, n: usize) -> Option<<I as Iterator>::Item>
fn nth(&mut self, n: usize) -> Option<<I as Iterator>::Item>
n
th element of the iterator. Read moresource§fn last(self) -> Option<<I as Iterator>::Item>
fn last(self) -> Option<<I as Iterator>::Item>
source§fn size_hint(&self) -> (usize, Option<usize>)
fn size_hint(&self) -> (usize, Option<usize>)
source§fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R
fn try_fold<B, F, R>(&mut self, init: B, f: F) -> R
source§fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
fn fold<Acc, Fold>(self, init: Acc, fold: Fold) -> Acc
source§fn next_chunk<const N: usize>(
&mut self
) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>where
Self: Sized,
fn next_chunk<const N: usize>(
&mut self
) -> Result<[Self::Item; N], IntoIter<Self::Item, N>>where
Self: Sized,
iter_next_chunk
#98326)N
values. Read moresource§fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>
fn advance_by(&mut self, n: usize) -> Result<(), NonZero<usize>>
iter_advance_by
#77404)n
elements. Read more1.28.0 · source§fn step_by(self, step: usize) -> StepBy<Self> ⓘwhere
Self: Sized,
fn step_by(self, step: usize) -> StepBy<Self> ⓘwhere
Self: Sized,
source§fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter> ⓘ
fn chain<U>(self, other: U) -> Chain<Self, <U as IntoIterator>::IntoIter> ⓘ
source§fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter> ⓘwhere
Self: Sized,
U: IntoIterator,
fn zip<U>(self, other: U) -> Zip<Self, <U as IntoIterator>::IntoIter> ⓘwhere
Self: Sized,
U: IntoIterator,
source§fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G> ⓘ
fn intersperse_with<G>(self, separator: G) -> IntersperseWith<Self, G> ⓘ
iter_intersperse
#79524)separator
between adjacent items of the original iterator. Read moresource§fn map<B, F>(self, f: F) -> Map<Self, F> ⓘ
fn map<B, F>(self, f: F) -> Map<Self, F> ⓘ
source§fn filter<P>(self, predicate: P) -> Filter<Self, P> ⓘ
fn filter<P>(self, predicate: P) -> Filter<Self, P> ⓘ
source§fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> ⓘ
fn filter_map<B, F>(self, f: F) -> FilterMap<Self, F> ⓘ
source§fn enumerate(self) -> Enumerate<Self> ⓘwhere
Self: Sized,
fn enumerate(self) -> Enumerate<Self> ⓘwhere
Self: Sized,
source§fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P> ⓘ
fn skip_while<P>(self, predicate: P) -> SkipWhile<Self, P> ⓘ
source§fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> ⓘ
fn take_while<P>(self, predicate: P) -> TakeWhile<Self, P> ⓘ
1.57.0 · source§fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P> ⓘ
fn map_while<B, P>(self, predicate: P) -> MapWhile<Self, P> ⓘ
source§fn skip(self, n: usize) -> Skip<Self> ⓘwhere
Self: Sized,
fn skip(self, n: usize) -> Skip<Self> ⓘwhere
Self: Sized,
n
elements. Read moresource§fn take(self, n: usize) -> Take<Self> ⓘwhere
Self: Sized,
fn take(self, n: usize) -> Take<Self> ⓘwhere
Self: Sized,
n
elements, or fewer
if the underlying iterator ends sooner. Read moresource§fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F> ⓘ
fn flat_map<U, F>(self, f: F) -> FlatMap<Self, U, F> ⓘ
source§fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N> ⓘ
fn map_windows<F, R, const N: usize>(self, f: F) -> MapWindows<Self, F, N> ⓘ
iter_map_windows
#87155)f
for each contiguous window of size N
over
self
and returns an iterator over the outputs of f
. Like slice::windows()
,
the windows during mapping overlap as well. Read moresource§fn inspect<F>(self, f: F) -> Inspect<Self, F> ⓘ
fn inspect<F>(self, f: F) -> Inspect<Self, F> ⓘ
source§fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
fn by_ref(&mut self) -> &mut Selfwhere
Self: Sized,
source§fn collect_into<E>(self, collection: &mut E) -> &mut E
fn collect_into<E>(self, collection: &mut E) -> &mut E
iter_collect_into
#94780)source§fn partition<B, F>(self, f: F) -> (B, B)
fn partition<B, F>(self, f: F) -> (B, B)
source§fn is_partitioned<P>(self, predicate: P) -> bool
fn is_partitioned<P>(self, predicate: P) -> bool
iter_is_partitioned
#62544)true
precede all those that return false
. Read more1.27.0 · source§fn try_for_each<F, R>(&mut self, f: F) -> R
fn try_for_each<F, R>(&mut self, f: F) -> R
1.51.0 · source§fn reduce<F>(self, f: F) -> Option<Self::Item>
fn reduce<F>(self, f: F) -> Option<Self::Item>
source§fn try_reduce<F, R>(
&mut self,
f: F
) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType
fn try_reduce<F, R>( &mut self, f: F ) -> <<R as Try>::Residual as Residual<Option<<R as Try>::Output>>>::TryType
iterator_try_reduce
#87053)source§fn all<F>(&mut self, f: F) -> bool
fn all<F>(&mut self, f: F) -> bool
source§fn any<F>(&mut self, f: F) -> bool
fn any<F>(&mut self, f: F) -> bool
source§fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
fn find<P>(&mut self, predicate: P) -> Option<Self::Item>
1.30.0 · source§fn find_map<B, F>(&mut self, f: F) -> Option<B>
fn find_map<B, F>(&mut self, f: F) -> Option<B>
source§fn try_find<F, R>(
&mut self,
f: F
) -> <<R as Try>::Residual as Residual<Option<Self::Item>>>::TryType
fn try_find<F, R>( &mut self, f: F ) -> <<R as Try>::Residual as Residual<Option<Self::Item>>>::TryType
try_find
#63178)source§fn position<P>(&mut self, predicate: P) -> Option<usize>
fn position<P>(&mut self, predicate: P) -> Option<usize>
1.6.0 · source§fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>
fn max_by_key<B, F>(self, f: F) -> Option<Self::Item>
1.15.0 · source§fn max_by<F>(self, compare: F) -> Option<Self::Item>
fn max_by<F>(self, compare: F) -> Option<Self::Item>
1.6.0 · source§fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>
fn min_by_key<B, F>(self, f: F) -> Option<Self::Item>
1.15.0 · source§fn min_by<F>(self, compare: F) -> Option<Self::Item>
fn min_by<F>(self, compare: F) -> Option<Self::Item>
source§fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)
fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)
1.36.0 · source§fn copied<'a, T>(self) -> Copied<Self> ⓘ
fn copied<'a, T>(self) -> Copied<Self> ⓘ
source§fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N> ⓘwhere
Self: Sized,
fn array_chunks<const N: usize>(self) -> ArrayChunks<Self, N> ⓘwhere
Self: Sized,
iter_array_chunks
#100450)N
elements of the iterator at a time. Read more1.11.0 · source§fn product<P>(self) -> P
fn product<P>(self) -> P
source§fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering
fn cmp_by<I, F>(self, other: I, cmp: F) -> Ordering
iter_order_by
#64295)Iterator
with those
of another with respect to the specified comparison function. Read more1.5.0 · source§fn partial_cmp<I>(self, other: I) -> Option<Ordering>
fn partial_cmp<I>(self, other: I) -> Option<Ordering>
PartialOrd
elements of
this Iterator
with those of another. The comparison works like short-circuit
evaluation, returning a result without comparing the remaining elements.
As soon as an order can be determined, the evaluation stops and a result is returned. Read moresource§fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>where
Self: Sized,
I: IntoIterator,
F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Option<Ordering>,
fn partial_cmp_by<I, F>(self, other: I, partial_cmp: F) -> Option<Ordering>where
Self: Sized,
I: IntoIterator,
F: FnMut(Self::Item, <I as IntoIterator>::Item) -> Option<Ordering>,
iter_order_by
#64295)Iterator
with those
of another with respect to the specified comparison function. Read moresource§fn eq_by<I, F>(self, other: I, eq: F) -> bool
fn eq_by<I, F>(self, other: I, eq: F) -> bool
iter_order_by
#64295)1.5.0 · source§fn lt<I>(self, other: I) -> bool
fn lt<I>(self, other: I) -> bool
Iterator
are lexicographically
less than those of another. Read more1.5.0 · source§fn le<I>(self, other: I) -> bool
fn le<I>(self, other: I) -> bool
Iterator
are lexicographically
less or equal to those of another. Read more1.5.0 · source§fn gt<I>(self, other: I) -> bool
fn gt<I>(self, other: I) -> bool
Iterator
are lexicographically
greater than those of another. Read more1.5.0 · source§fn ge<I>(self, other: I) -> bool
fn ge<I>(self, other: I) -> bool
Iterator
are lexicographically
greater than or equal to those of another. Read moresource§fn is_sorted_by<F>(self, compare: F) -> bool
fn is_sorted_by<F>(self, compare: F) -> bool
is_sorted
#53485)