multipeek
multipeek copied to clipboard
An iterator adapter to peek at future elements without advancing the cursor of the underlying iterator.
multipeek
An iterator adapter to peek at future elements without advancing the cursor of the underlying iterator.
Check out the documentation for more details.
Example
use multipeek::multipeek;
let mut iter = multipeek([1, 2, 3, 4].into_iter());
// Peek at the first element.
let first_peek = iter.peek().cloned();
assert_eq!(first_peek, Some(1));
// Advance the iterator cursor to point at the first element.
let first = iter.next();
assert_eq!(first, first_peek);
// Peek two steps ahead, at the third element.
let third_peek = iter.peek_nth(1).cloned();
assert_eq!(third_peek, Some(3));
// Advance the iterator cursor twice.
// The iterator cursor will now point to the third element.
iter.next();
let third = iter.next();
assert_eq!(third_peek, third);
// Peeking beyond the end of the iterator returns `None`.
let ambitious_peek = iter.peek_nth(5);
assert!(ambitious_peek.is_none());
no_std
multipeek
can be used in no_std
environments. It requires an allocator.
Alternatives and previous art
Rust's standard library provides Peekable
.
It lets you peek at the next element in an iterator, but there is no way to look further ahead.
itertools
's provides MultiPeek
.
It lets you peek as far ahead as you want, but MultiPeek::peek
is not idempotent: calling peek
once returns the next element, calling peek
again
returns the second-next element.
multipeek
, just like itertools
, gives you the possibility to peek as far ahead as you want.
Our MultiPeek::peek
implementation is idempotent: MultiPeek::peek
always returns
the next element.
You can peek further ahead using MultiPeek::peek_nth
, you just need to specify how
many steps ahead you want to look at.
Our MultiPeek
implementation is directly inspired by itertools
' implementation.
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.