lockstep 0.3.1

An iterator adaptor for selective zipping
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

# A lockstep iterator adaptor
The *lockstep* iterator adaptor is an adapter similar to [`zip`](core::iter::zip), but instead
uses a control flow closure to selectively skip elements from either the left or the right
iterator, or yield the pair. This adaptor is primarily useful when working with sorted data.

The main entrypoint is the [`lockstep`](https://docs.rs/lockstep/latest/lockstep/fn.lockstep.html) function.

This crate is `#![no_std]` and `#![forbid(unsafe_code)]`.

## Examples
Re-implement [`zip`](core::iter::zip).
```rust
use lockstep::{lockstep, Control};

pub fn zip<L, R>(left: L, right: R) -> impl Iterator<Item = (L::Item, R::Item)>
where
    L: IntoIterator,
    R: IntoIterator,
{
    lockstep(left.into_iter(), right.into_iter(), |_, _| Control::Yield)
}
```
Compose two sorted iterators to only yield elements which they have in common.
```rust
use core::cmp::Ordering;

use lockstep::{lockstep, Control};

/// Assumes that `left` and `right` are sorted.
pub fn intersection<L, R, T>(left: L, right: R) -> impl Iterator<Item = T>
where
    L: IntoIterator<Item = T>,
    R: IntoIterator<Item = T>,
    T: Ord,
{
    lockstep(left.into_iter(), right.into_iter(), |l, r| {
        match l.cmp(r) {
            Ordering::Less => Control::SkipLeft,
            Ordering::Equal => Control::Yield,
            Ordering::Greater => Control::SkipRight,
        }
    })
    .map(|(l, _)| l)
}
```