lender 🙂

Lending Iterator: a niche, yet seemingly pervasive, antipattern[^1]. This crate provides one such implementation, 'utilizing' #84533 and #25860.

Ok, maybe 'antipattern' is a little tough, but let's spare the antagonizing examples, if you can avoid using lending iterators, you generally should. You should heed the counsel of Polonious: "Neither a borrower nor a lender be".

ℹ️A GAT implementation has been published at [gat-lending-iterator], go check it out if you can!

Forewarning, before you go on with this crate, you should consider using a more seasoned 'lending iterator' crate, like the [lending-iterator] or [streaming-iterator] crates. Also, if a dyn Lender trait object is in your future, this crate definitely isn't going to work. This crate was not made to be used in any sort of production code, so please, use at your own risk (Documentation be damned! Unsafe transmutes beware!).

Commonly known as a "lending iterator", a lender is a kind of iterator over items that live at least as long as the mutable reference to the lender in a call to Lender::next(). In other words, a kind of iterator that lends an item one at a time, a pattern not implementable by the current definition of Iterator which only encompasses iterators over items that live at least as long as the iterators themselves, i.e. Self: 'this implies <Self as Iterator>::Item: 'this.

Examples

I present to you WindowsMut.

```rust use ::lender::prelude::*;

struct WindowsMut<'a, T> { slice: &'a mut [T], begin: usize, len: usize, } impl<'lend, 'a, T> Lending<'lend> for WindowsMut<'a, T> { type Lend = &'lend mut [T]; } impl<'a, T> Lender for WindowsMut<'a, T> { fn next<'lend>(&'lend mut self) -> Option<&'lend mut [T]> { let begin = self.begin; self.begin = self.begin.saturatingadd(1); self.slice.getmut(begin..begin + self.len) } } // Fibonacci sequence let mut data = vec![0u32; 3 * 3]; data[1] = 1; WindowsMut { slice: &mut data, begin: 0, len: 3 } .foreach(hrcmut!(for<'lend> |w: &'lend mut [u32]| { w[2] = w[0] + w[1] })); assert_eq!(data, [0, 1, 1, 2, 3, 5, 8, 13, 21]); ```

As all great standard examples are, a WindowsMut just for a Fibonacci sequence is actually a great example of what you shouldn't use lending iterators for. Libraries can just provide Index and IndexMut on their collections and it's a lot of boilerplate for something a simple for loop can do.

rust let mut data = vec![0; 3 * 3]; data[1] = 1; for i in 2..data.len() { data[i] = data[i - 1] + data[i - 2]; } assert_eq!(data, [0, 1, 1, 2, 3, 5, 8, 13, 21]);

So, let's look at a slightly more interesting example, LinesStr, an io::Lines with an Item of &str instead of String. It's a good example of borrowing from the iterator itself.

```rust use std::io; use ::lender::prelude::*;

struct LinesStr { buf: B, line: String, } impl<'lend, B: io::BufRead> Lending<'lend> for LinesStr { type Lend = io::Result<&'lend str>; } impl Lender for LinesStr { fn next<'lend>(&'lend mut self) -> Option> { self.line.clear(); match self.buf.readline(&mut self.line) { Err(e) => return Some(Err(e)), Ok(0) => return None, Ok(nread) => (), }; if self.line.endswith('\n') { self.line.pop(); if self.line.endswith('\r') { self.line.pop(); } } Some(Ok(&self.line)) } }