Crate gat_lending_iterator

Expand description

§Lending Iterators with Generic Associated Types

A lending iterator yields items that borrow from the iterator itself, unlike standard Iterator where each item must be independent. This is enabled by Generic Associated Types (GATs) (motivation).

Standard iterators cannot return items that borrow from &mut self due to lifetime constraints. Lending iterators solve this, enabling patterns like overlapping mutable windows without cloning.

Most Iterator methods work on LendingIterator, except those requiring multiple items simultaneously (e.g., collect, peekable). Some methods like map and cloned conditionally implement IntoIterator when the returned value doesn’t borrow from input.

This crate provides ToLendingIterator to convert standard iterators into lending iterators, enabling methods like windows() and windows_mut().

§Examples

Using windows on a range, filtering it and chaining it:

use gat_lending_iterator::{LendingIterator, ToLendingIterator};

(0..5)
    .windows(3)
    .filter(|x| x[0] % 2 == 0)
    .chain((0..6).windows(2))
    .for_each(|x| println!("{x:?}"));

Prints:

[0, 1, 2]
[2, 3, 4]
[0, 1]
[1, 2]
[2, 3]
[3, 4]
[4, 5]

Using windows_mut on a range, mutating it and mapping it:

use gat_lending_iterator::{LendingIterator, ToLendingIterator};

for sum in (0..7).windows_mut(2).map(|slice: &mut [usize]| {
    slice[1] += slice[0];
    slice[1]
}) {
    println!("{sum}");
}

Prints:

Using windows on a range, and mapping it:

use gat_lending_iterator::{LendingIterator, ToLendingIterator};
fn second(slice: &[usize]) -> &usize {
    &slice[1]
}

for n in (0..5).windows(3).map(second).cloned() {
    println!("{n}");
}

Prints:

1
2
3

Structs§

Chain: A lending iterator that iterates over the elements of two iterators in sequence.
Cloned: A lending iterator that clones the elements of an underlying lending iterator.
Copied: A lending iterator that copies the elements of an underlying lending iterator.
Cycle: A lending iterator that repeats endlessly.
Enumerate: A lending iterator that yields the current count and the element during iteration.
Filter: A lending iterator that filters the elements of iter with predicate.
FilterMap: A lending iterator that uses f to both filter and map elements from iter.
Fuse: A lending iterator that yields None forever after the underlying iterator yields None once.
Inspect: A lending iterator that calls a function with a reference to each element before yielding it.
IntoIter: An iterator that maps the elements of iter with f.
IntoLending: A lending iterator that iterates over an iterator.
LendRefs: A lending iterator that given an iterator, lends references to the given iterator’s items.
LendRefsMut: A lending iterator that given an iterator, lends mutable references to the given iterator’s items.
Map: A lending iterator that maps the elements of iter with f.
MapWhile: A lending iterator that maps elements and yields while the mapping returns Some.
Scan: A lending iterator that maintains internal state and maps elements using that state.
Skip: A lending iterator that skips over the first n items of iter.
SkipWhile: A lending iterator that that rejects elements while predicate returns true.
StepBy: A lending iterator for stepping lending iterators by a custom amount.
Take: A Lending iterator that only lends the first n iterations of iter.
TakeWhile: A lending iterator that yields items based on a predicate.
Windows: A lending iterator over windows.
WindowsMut: A lending iterator over mutable windows.
Zip: A lending iterator that iterates two other lending iterators simultaneously.

Traits§

LendingIterator: Like Iterator, but items may borrow from &mut self.
OptionTrait: Used in cases that a function needs to return an Option who’s lifetime is tied to the input.
SingleArgFn: Placeholder for Fn
SingleArgFnMut: Placeholder for FnMut
SingleArgFnOnce: Placeholder for FnOnce
ToLendingIterator: An extension trait for iterators that allows turning them into lending iterators (over windows of elements).