Alternating Iterators

This crate aims to provides a convenient way to alternate between the items of two iterators. It allows you to iterate over two iterators in an alternating fashion, combining their elements into a single sequence.

For the easiest usage of this crate, bring the AlternatingExt trait into scope

use alternating_iter::AlternatingExt;

and use the alternate_with_all method to create new alternating iterators.

use alternating_iter::AlternatingExt;

let a = [1, 2];
let b = [3, 4, 5];

let mut iter = a.iter().alternate_with_all(b.iter());

assert_eq!(iter.next(), Some(&1)); // `a` first
assert_eq!(iter.next(), Some(&3)); // `b`
assert_eq!(iter.next(), Some(&2)); // `a`
assert_eq!(iter.next(), Some(&4)); // `b`
assert_eq!(iter.next(), Some(&5)); // also `b`
assert_eq!(iter.next(), None);

By default the alternate_with_all method creates an iterator that returns an element from a first, followed by element from b, and so on until both are exhausted.

Stopping after Exhaustion

If, however, you want the iteration to stop once either of the iterators is exhausted, you can use the alternate_with_no_remainder method, also provided by the AlternatingExt trait. This method returns an iterator that stops as soon as it needs to return more than one item consecutively from a single iterator.

use alternating_iter::AlternatingExt;

let a = [1, 2];
let b = [3, 4, 5];

let mut iter = a.iter().alternate_with_no_remainder(b.iter());

assert_eq!(iter.next(), Some(&1)); // `a` first
assert_eq!(iter.next(), Some(&3)); // `b`
assert_eq!(iter.next(), Some(&2)); // `a`
assert_eq!(iter.next(), Some(&4)); // `b`
assert_eq!(iter.next(), None);     // remaining items from `b` are not returned

The iteration stops after the fourth element because returning the fifth element from b would break the alternating pattern.

Alternating Even After Exhaustion

If alternating_with_all behavior is not desirable and you want to continue alternation even after an iterator is exhausted, use alternating_with, the simplest iterator of the three.

use alternating_iter::AlternatingExt;

let a = [1, 2];
let b = [3, 4, 5];

let mut iter = a.iter().alternate_with(b.iter());

assert_eq!(iter.next(), Some(&1)); // `a` first
assert_eq!(iter.next(), Some(&3)); // `b`
assert_eq!(iter.next(), Some(&2)); // `a`
assert_eq!(iter.next(), Some(&4)); // `b`
assert_eq!(iter.next(), None); // `a` exhausted
assert_eq!(iter.next(), Some(&5)); // `b`
assert_eq!(iter.next(), None); // `b` exhausted

The iterator will simply keep alternating blindly, so Some can appear between None if one of the input iterator is larger than the other.