Crate gat_lending_iterator

This crate uses generic associated types to supply an iterator trait that allows the items to [mutably] borrow from the iterator. See the GAT anouncement

Most Iterator methods can work as is on LendingIterators, but some wouldn’t make sense. Basically any method that needs to look at more than one element at once isn’t possible, or needs to be modified.

Some LendingIterator methods may return something that can act as an Iterator. For example cloned, or map, when the function passed to it returns a value that isn’t tied to the lifetime of its input. In these cases, my design choice was to conditionally implement IntoIterator for the adapter.

This crate also provides an extension trait ToLendingIterator: Iterator for iterators that allows turning them into lending iterators (over windows of elements). There may be more methods added to this trait in the future.

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:

1
3
6
10
15
21

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.

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.

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.

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).