Crate alternating_iter 

Alternating Iterators

This crate aims to provide 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 an 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 the alternate_with_all behavior is not desirable and you want to continue alternation even after an iterator is exhausted, use alternate_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 iterators is larger than the other.

Changelog

• 0.2: Renamed methods on the extension trait and fixed erroneous FusedIterator implementation
• 0.3: Removed erroneous FixedSizedIterator implementations

Structs

Alternating

Struct for alternating between the items of two iterators.

AlternatingAll

Struct for alternating between the items of two iterators while handling size difference intuitively.

AlternatingNoRemainder

Struct for alternating between the items of two iterators until one is exhausted.

Traits

AlternatingExt

Extension trait that provides methods for creating alternating iterators.