::lending-iterator
Fully generic LendingIterators in stable Rust.
this pattern used to be called StreamingIterator, but since Streams entered
the picture (as the async/.await version of Iterators, that is,
AsyncIterators), it has been deemed more suitable to go for the lending
naming convention.
LendingIterator
lending impl Futures, which would effectively make it another flavor
of AsyncIterator, but not quite the Stream variant).For context, this crate is a generalization of other crates such as:
which hard-code their lending Item type to &_ and Result<&_, _>
respectively.
This crate does not hardcode such dependent types, and thus encompasses both of those traits, and infinitely more!
Mainly, it allows lending &mut _ Items, which means it can handle the
infamously challenging [windows_mut()] pattern!
Click to see/hide
windows_mut()!```rust use ::lending_iterator::prelude::*;
let mut array = [0; 15];
array[1] = 1;
// Cumulative sums are trivial with a mut sliding window,
// so let's showcase that by generating a Fibonacci sequence.
let mut iter = array.windowsmut::<3>();
while let Some(&mut [a, b, ref mut next]) = iter.next() {
*next = a + b;
}
asserteq!(
array,
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377],
);
```
from_fn constructorFromFn flavor of it to enjoy "named arguments")```rust use ::lending_iterator::prelude::*;
let mut array = [0; 15];
array[1] = 1;
// Let's hand-roll our iterator lending &mut sliding windows:
let mut iter = {
let mut start = 0;
lendingiterator::FromFn::&mut [u8] -> &mut [u8; 3]
.unwrap()
;
start += 1;
Some(toyield)
},
phantom: <_>::default(),
}
};
while let Some(&mut [a, b, ref mut next]) = iter.next() {
*next = a + b;
}
asserteq!(
array,
[0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, 233, 377],
);
```
where that [HKT!](\&mut [u16; 3]) is a [higher-kinded] type
parameter that has to be turbofished to let the generic context
properly figure out the return type of the next closure.
Indeed, if we were to let type inference, alone, figure it out, it wouldn't
be able to know which lifetimes would be fixed/tied to call-site captures,
and which would be tied to the "lending-ness" of the iterator (higher-order
return type).
See ::higher-order-closure for
more info about this.
LendingIterator adaptersSee [lending_iterator::adapters].
See higher_kinded_types for a presentation about them.
.sort_by_key() that is fully generic over the key lending modeAs noted in this 6-year-old issue:
Such an API can easily be provided using the HKT API of this crate:
Click to see/hide
```rust use ::lendingiterator::higherkinded_types::{*, Apply as A};
fn slicesortbykey
// ---- Demo ----
struct Client { key: String, version: u8 }
fn main () { let clients: &mut [Client] = &mut [];
// Error: cannot infer an appropriate lifetime for autoref due to conflicting requirements
// clients.sort_by_key(|c| &c.key);
// OK
slice_sort_by_key::<HKT!(&str), _, _>(clients, |c| &c.key);
// Important: owned case works too!
slice_sort_by_key::<HKT!(u8), _, _>(clients, |c| c.version);
} ```