094 Intermediate

094 — Peekable Iterator

Functional Programming

Tutorial

The Problem

Use .peekable() to look ahead at the next iterator element without consuming it. Implement dedup — removing consecutive duplicates — as a demonstration: consume the current value, then skip ahead while the peek matches. Compare with OCaml's manual peekable wrapper built on Seq.

🎯 Learning Outcomes

• Convert any iterator to a Peekable<I> with .peekable()

• Use iter.peek() to inspect the next item as Option<&Item> without advancing

• Combine next() and peek() in a while let loop for look-ahead parsing

• Understand the double-reference in peek() — Some(&&val) for &[i32]

• Map Rust's built-in Peekable to OCaml's manually implemented peekable wrapper

• Recognise peekable iterators as essential for tokenizers and parsers

Code Example

#![allow(clippy::all)]
// 094: Peekable Iterator

fn dedup(v: &[i32]) -> Vec<i32> {
    let mut result = Vec::new();
    let mut iter = v.iter().peekable();
    while let Some(&val) = iter.next() {
        result.push(val);
        while iter.peek() == Some(&&val) {
            iter.next();
        }
    }
    result
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_dedup() {
        assert_eq!(dedup(&[1, 1, 2, 2, 2, 3, 3, 1]), vec![1, 2, 3, 1]);
        assert_eq!(dedup(&[]), Vec::<i32>::new());
        assert_eq!(dedup(&[5]), vec![5]);
    }

    #[test]
    fn test_peekable() {
        let mut iter = [1, 2, 3].iter().peekable();
        assert_eq!(iter.peek(), Some(&&1));
        assert_eq!(iter.next(), Some(&1));
        assert_eq!(iter.peek(), Some(&&2));
    }
}

(* 094: Peekable Iterator *)

(* OCaml: manual peekable wrapper *)
type 'a peekable = { mutable peeked: 'a option; seq: 'a Seq.t ref }

let make_peekable s = { peeked = None; seq = ref s }

let peek p =
  match p.peeked with
  | Some _ as v -> v
  | None ->
    match !(p.seq) () with
    | Seq.Nil -> None
    | Seq.Cons (x, rest) -> p.peeked <- Some x; p.seq := rest; Some x

let next p =
  match p.peeked with
  | Some x -> p.peeked <- None; Some x
  | None ->
    match !(p.seq) () with
    | Seq.Nil -> None
    | Seq.Cons (x, rest) -> p.seq := rest; Some x

(* Use: skip consecutive duplicates *)
let dedup s =
  let p = make_peekable s in
  let rec aux acc =
    match next p with
    | None -> List.rev acc
    | Some x ->
      (* skip while peek = x *)
      let rec skip () = match peek p with Some y when y = x -> ignore (next p); skip () | _ -> () in
      skip (); aux (x :: acc)
  in
  aux []

(* Tests *)
let () =
  let s = List.to_seq [1;1;2;2;2;3;3;1] in
  assert (dedup s = [1;2;3;1]);
  assert (dedup (List.to_seq []) = []);
  assert (dedup (List.to_seq [5]) = [5]);
  Printf.printf "✓ All tests passed\n"

Key Differences

Aspect	Rust	OCaml
Built-in	`Iterator::peekable()`	Manual `peekable` struct
Peek type	`Option<&Item>` (reference)	`'a option` (value)
Double ref	`Some(&&val)` for `&[T]` iterators	`Some x` directly
Mutable	Internally mutable in adapter	Mutable fields in record
Parser use	Common in tokenisers	Same manual wrapper
Standard	Yes	No

Peekable iterators are the foundation of hand-written parsers and tokenisers. By looking ahead without consuming, you can make branching decisions based on context — the backbone of recursive descent parsing.

OCaml Approach

OCaml's Seq has no built-in peek. The peekable record holds peeked: 'a option and seq: 'a Seq.t ref. peek checks the peeked slot, or forces the next thunk and caches it. next drains the peeked slot or forces the seq. This is a complete, correct implementation — just more code than Rust's built-in.

Full Source

#![allow(clippy::all)]
// 094: Peekable Iterator

fn dedup(v: &[i32]) -> Vec<i32> {
    let mut result = Vec::new();
    let mut iter = v.iter().peekable();
    while let Some(&val) = iter.next() {
        result.push(val);
        while iter.peek() == Some(&&val) {
            iter.next();
        }
    }
    result
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_dedup() {
        assert_eq!(dedup(&[1, 1, 2, 2, 2, 3, 3, 1]), vec![1, 2, 3, 1]);
        assert_eq!(dedup(&[]), Vec::<i32>::new());
        assert_eq!(dedup(&[5]), vec![5]);
    }

    #[test]
    fn test_peekable() {
        let mut iter = [1, 2, 3].iter().peekable();
        assert_eq!(iter.peek(), Some(&&1));
        assert_eq!(iter.next(), Some(&1));
        assert_eq!(iter.peek(), Some(&&2));
    }
}

(* 094: Peekable Iterator *)

(* OCaml: manual peekable wrapper *)
type 'a peekable = { mutable peeked: 'a option; seq: 'a Seq.t ref }

let make_peekable s = { peeked = None; seq = ref s }

let peek p =
  match p.peeked with
  | Some _ as v -> v
  | None ->
    match !(p.seq) () with
    | Seq.Nil -> None
    | Seq.Cons (x, rest) -> p.peeked <- Some x; p.seq := rest; Some x

let next p =
  match p.peeked with
  | Some x -> p.peeked <- None; Some x
  | None ->
    match !(p.seq) () with
    | Seq.Nil -> None
    | Seq.Cons (x, rest) -> p.seq := rest; Some x

(* Use: skip consecutive duplicates *)
let dedup s =
  let p = make_peekable s in
  let rec aux acc =
    match next p with
    | None -> List.rev acc
    | Some x ->
      (* skip while peek = x *)
      let rec skip () = match peek p with Some y when y = x -> ignore (next p); skip () | _ -> () in
      skip (); aux (x :: acc)
  in
  aux []

(* Tests *)
let () =
  let s = List.to_seq [1;1;2;2;2;3;3;1] in
  assert (dedup s = [1;2;3;1]);
  assert (dedup (List.to_seq []) = []);
  assert (dedup (List.to_seq [5]) = [5]);
  Printf.printf "✓ All tests passed\n"

✓ Tests Rust test suite

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_dedup() {
        assert_eq!(dedup(&[1, 1, 2, 2, 2, 3, 3, 1]), vec![1, 2, 3, 1]);
        assert_eq!(dedup(&[]), Vec::<i32>::new());
        assert_eq!(dedup(&[5]), vec![5]);
    }

    #[test]
    fn test_peekable() {
        let mut iter = [1, 2, 3].iter().peekable();
        assert_eq!(iter.peek(), Some(&&1));
        assert_eq!(iter.next(), Some(&1));
        assert_eq!(iter.peek(), Some(&&2));
    }
}

Deep Comparison

Core Insight

Peekable lets you inspect the next element without consuming it — essential for parsers and tokenizers

OCaml Approach

• See example.ml for implementation

Rust Approach

• See example.rs for implementation

Comparison Table

Feature	OCaml	Rust
See	example.ml	example.rs

Exercises

Implement a simple tokeniser that groups consecutive digit characters into Token::Number(u64) and other characters into Token::Other(char) using a peekable iterator.

Write group_by_peekable<T: PartialEq>(v: &[T]) -> Vec<Vec<T>> that groups consecutive equal elements using peekable.

Implement parse_csv_field(iter: &mut Peekable<impl Iterator<Item=char>>) -> String that reads until a comma or end of input.

Use peek to implement a take_while_peek that advances as long as the peeked element satisfies a predicate, stopping before consuming the first non-matching element.

In OCaml, add a peek_nth function to the peekable wrapper that allows looking n elements ahead by caching a VecDeque-style buffer.

Open Source Repos

functional-rust

View the source for this example on GitHub — OCaml and Rust side by side in the repo.

Rust