# Crate multipeek

Expand description

An iterator adapter to peek at future elements without advancing the cursor of the underlying iterator.

Check out multipeek() 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.

## Structs

A wrapper type around the underlying iterator.

## Traits

An extension trait to add a multipeek method to all the types that implement the Iterator trait.

## Functions

An iterator adapter to peek at future elements without advancing the cursor of the underlying iterator.