Struct Peekable
1.0.0 · Source
pub struct Peekable<I>where
I: Iterator,
{ /* private fields */ }Expand description
Source§
1.0.0 · Source
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);1.53.0 · Source
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]);1.51.0 · Source
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 `next_if` will return `None`.
assert_eq!(iter.next_if(|&x| x == 0), None);
// `next_if` retains the next item if the predicate evaluates to `false` for it.
assert_eq!(iter.next(), Some(1));Consume 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));1.51.0 · Source
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 `next_if_eq` will return `None`.
assert_eq!(iter.next_if_eq(&0), None);
// `next_if_eq` retains the next item if it was not equal to `expected`.
assert_eq!(iter.next(), Some(1));Source 🔬This is a nightly-only experimental API. (peekable_next_if_map #143702)
peekable_next_if_map #143702)Consumes the next value of this iterator and applies a function f on it,
returning the result if the closure returns Ok.
Otherwise if the closure returns Err the value is put back for the next iteration.
The content of the Err variant is typically the original value of the closure,
but this is not required. If a different value is returned,
the next peek() or next() call will result in this new value.
This is similar to modifying the output of peek_mut().
If the closure panics, the next value will always be consumed and dropped
even if the panic is caught, because the closure never returned an Err value to put back.
See also: next_if_map_mut.
§Examples
Parse the leading decimal number from an iterator of characters.
#![feature(peekable_next_if_map)]
let mut iter = "125 GOTO 10".chars().peekable();
let mut line_num = 0_u32;
while let Some(digit) = iter.next_if_map(|c| c.to_digit(10).ok_or(c)) {
line_num = line_num * 10 + digit;
}
assert_eq!(line_num, 125);
assert_eq!(iter.collect::<String>(), " GOTO 10");Matching custom types.
#![feature(peekable_next_if_map)]
#[derive(Debug, PartialEq, Eq)]
enum Node {
Comment(String),
Red(String),
Green(String),
Blue(String),
}
/// Combines all consecutive `Comment` nodes into a single one.
fn combine_comments(nodes: Vec<Node>) -> Vec<Node> {
let mut result = Vec::with_capacity(nodes.len());
let mut iter = nodes.into_iter().peekable();
let mut comment_text = None::<String>;
loop {
// Typically the closure in .next_if_map() matches on the input,
// extracts the desired pattern into an `Ok`,
// and puts the rest into an `Err`.
while let Some(text) = iter.next_if_map(|node| match node {
Node::Comment(text) => Ok(text),
other => Err(other),
}) {
comment_text.get_or_insert_default().push_str(&text);
}
if let Some(text) = comment_text.take() {
result.push(Node::Comment(text));
}
if let Some(node) = iter.next() {
result.push(node);
} else {
break;
}
}
result
}Source 🔬This is a nightly-only experimental API. (peekable_next_if_map #143702)
peekable_next_if_map #143702)Gives a mutable reference to the next value of the iterator and applies a function f to it,
returning the result and advancing the iterator if f returns Some.
Otherwise, if f returns None, the next value is kept for the next iteration.
If f panics, the item that is consumed from the iterator as if Some was returned from f.
The value will be dropped.
This is similar to next_if_map, except ownership of the item is not given to f.
This can be preferable if f would copy the item anyway.
§Examples
Parse the leading decimal number from an iterator of characters.
#![feature(peekable_next_if_map)]
let mut iter = "125 GOTO 10".chars().peekable();
let mut line_num = 0_u32;
while let Some(digit) = iter.next_if_map_mut(|c| c.to_digit(10)) {
line_num = line_num * 10 + digit;
}
assert_eq!(line_num, 125);
assert_eq!(iter.collect::<String>(), " GOTO 10");1.38.0 · Source§
Source§
This is the reverse version of Iterator::try_fold(): it takes
elements starting from the back of the iterator. Read more
Source§
An iterator method that reduces the iterator’s elements to a single, final value, starting from the back. Read more
1.0.0 · Source§
Source§
An iterator method that applies a function as long as it returns successfully, producing a single, final value. Read more
Source§
Folds every element into an accumulator by applying an operation, returning the final result. Read more
Source§
🔬This is a nightly-only experimental API. (iter_next_chunk #98326)
Advances the iterator and returns an array containing the next N values. Read more
Source§
🔬This is a nightly-only experimental API. (iter_advance_by #77404)
Advances the iterator by n elements. Read more
1.28.0 · Source§
Creates an iterator starting at the same point, but stepping by the given amount at each iteration. Read more
Source§
🔬This is a nightly-only experimental API. (iter_intersperse #79524)
Creates a new iterator which places a copy of separator between adjacent
items of the original iterator. Read more
Source§
🔬This is a nightly-only experimental API. (iter_intersperse #79524)
Creates a new iterator which places an item generated by separator
between adjacent items of the original iterator. Read more
1.0.0 · Source§
Takes a closure and creates an iterator which calls that closure on each element. Read more
1.0.0 · Source§
Creates an iterator which uses a closure to determine if an element should be yielded. Read more
1.0.0 · Source§
Creates an iterator which gives the current iteration count as well as the next value. Read more
1.0.0 · Source§
Creates an iterator which can use the peek and peek_mut methods
to look at the next element of the iterator without consuming it. See
their documentation for more information. Read more
1.57.0 · Source§
Creates an iterator that both yields elements based on a predicate and maps. Read more
1.0.0 · Source§
Creates an iterator that yields the first n elements, or fewer
if the underlying iterator ends sooner. Read more
1.0.0 · Source§
An iterator adapter which, like fold, holds internal state, but
unlike fold, produces a new iterator. Read more
Source§
🔬This is a nightly-only experimental API. (iter_map_windows #87155)
Calls the given function 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 more
Source§
🔬This is a nightly-only experimental API. (iterator_try_collect #94047)
Fallibly transforms an iterator into a collection, short circuiting if a failure is encountered. Read more
Source§
🔬This is a nightly-only experimental API. (iter_collect_into #94780)
Collects all the items from an iterator into a collection. Read more
Source§
🔬This is a nightly-only experimental API. (iter_partition_in_place #62543)
Reorders the elements of this iterator in-place according to the given predicate,
such that all those that return true precede all those that return false.
Returns the number of true elements found. Read more
Source§
🔬This is a nightly-only experimental API. (iter_is_partitioned #62544)
Checks if the elements of this iterator are partitioned according to the given predicate,
such that all those that return true precede all those that return false. Read more
1.27.0 · Source§
An iterator method that applies a fallible function to each item in the iterator, stopping at the first error and returning that error. Read more
1.51.0 · Source§
Reduces the elements to a single one, by repeatedly applying a reducing operation. Read more
Source§
🔬This is a nightly-only experimental API. (iterator_try_reduce #87053)
Reduces the elements to a single one by repeatedly applying a reducing operation. If the closure returns a failure, the failure is propagated back to the caller immediately. Read more
1.30.0 · Source§
Applies function to the elements of iterator and returns the first non-none result. Read more
Source§
🔬This is a nightly-only experimental API. (try_find #63178)
Applies function to the elements of iterator and returns the first true result or the first error. Read more
1.0.0 · Source§
Searches for an element in an iterator from the right, returning its index. Read more
1.6.0 · Source§
Returns the element that gives the maximum value from the specified function. Read more
1.15.0 · Source§
Returns the element that gives the maximum value with respect to the specified comparison function. Read more
1.6.0 · Source§
Returns the element that gives the minimum value from the specified function. Read more
1.15.0 · Source§
Returns the element that gives the minimum value with respect to the specified comparison function. Read more
Source§
🔬This is a nightly-only experimental API. (iter_array_chunks #100450)
Returns an iterator over N elements of the iterator at a time. Read more
Source§
🔬This is a nightly-only experimental API. (iter_order_by #64295)
Lexicographically compares the elements of this Iterator with those
of another with respect to the specified comparison function. Read more
1.5.0 · Source§
Lexicographically compares the 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 more
Source§
🔬This is a nightly-only experimental API. (iter_order_by #64295)
Lexicographically compares the elements of this Iterator with those
of another with respect to the specified comparison function. Read more
Source§
🔬This is a nightly-only experimental API. (iter_order_by #64295)
Determines if the elements of this Iterator are equal to those of
another with respect to the specified equality function. Read more
1.5.0 · Source§
Determines if the elements of this Iterator are not equal to those of
another. Read more