iter-chunks 0.3.0

Extend Iterator with chunks
Documentation

iter-chunks

Crates.io Docs.rs Rust 1.85+ License: MIT OR Apache-2.0

iter-chunks extends the standard Iterator trait with a chunks method that yields lending iterators without resorting to interior mutability.

Please read the API documentation on docs.rs for details.

Usage

Add this to your Cargo.toml:

[dependencies]
iter-chunks = "0.3"

Examples

Chunks implements a lending iterator, so iteration currently happens via a while let loop.

use iter_chunks::IterChunks;

let arr = [1, 1, 2, 2, 3];
let expected = [vec![1, 1], vec![2, 2], vec![3]];
let mut chunks = arr.into_iter().chunks(2);
let mut i = 0;
while let Some(chunk) = chunks.next() {
    assert_eq!(chunk.collect::<Vec<_>>(), expected[i]);
    i += 1;
}

Why create this crate?

itertools provides many awesome extensions, including chunks. It is very handy, but it uses RefCell internally, so the resulting iterator is not Send.

It's a very common usecase in async context, which requires Chunks to be Send:

async fn do_some_work(input: impl Iterator<Item = i32>) {
    for chunk in input.chunks(1024) {
        for v in chunk {
            handle(v).await
        }
        do_some_flush().await
    }
}

This crate implements chunks without RefCell, so Chunks is both Send and Sync. As a trade-off, Chunks cannot currently implement Iterator because the standard library still lacks a lending iterator abstraction, even though GAT is now stable.

Future works

The lack of the Iterator implementation is inconvenient, and the best solution is to wait for a stable lending iterator trait (either in std or via crates such as lending-iterator). In the short term we can provide more helper adaptors such as nth, for_each, try_for_each, and so on.

Contributions are welcome.

License

Licensed under either of

at your option.