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.