# Relend: A Generalized Reborrowing Mechanism

This Rust library implements a generalized reborrowing mechanism that extends beyond simple references. It allows for implementing traits that work with reborrowing for custom types, providing more flexibility and control over lifetime management.

## Key Features

1. **Zero-Cost Abstraction**: `Relend` adheres to Rust's zero-cost abstraction principle. It allows for creating flexible, generic structures that can be efficiently specialized for different use cases without runtime overhead. Unused fields or functionality are optimized away at compile-time.

2. **Generalized Reborrowing**: Extends the concept of reborrowing beyond simple references to work with custom types.

3. **Flexible Lifetime Management**: Allows for fine-grained control over lifetimes in complex data structures.

4. **Trait-based Design**: Uses Rust's trait system to provide a flexible and extensible API.

5. **Extensibility**: Can be applied to various Rust constructs, including iterators, as shown in the examples.

6. **Optimized Memory Usage and Performance**: By generalizing references into storable structures and allowing for the application of `()` when a field is unused, this approach reduces unnecessary dereferencing and can lead to more compact data structures.

## Core Concepts

### `Relend` Trait

The `Relend` trait is the foundation of this library. It defines an associated type `Target` and a `reborrow` method that allows creating a new borrowed version of a type with a potentially shorter lifetime.

```rust
pub trait Relend {
    type Target<'short> where Self: 'short;
    fn reborrow<'short, 'long>(this: &'short mut Self::Target<'long>) -> Self::Target<'short>;
}
```

### `IntoRelend` Trait

This trait is automatically implemented for any type that implements `Relend` and meets certain lifetime constraints. It provides a `lend` method to create a `Lend<T>` wrapper.

### `Lend<T>` Struct

This wrapper type stores a `Target` of a `Relend` type and provides methods for reborrowing. It implements `Deref` and `DerefMut` for convenient access to the underlying data.

### `RelendRef` and `IntoRelendRef` Traits

These traits are similar to `Relend` and `IntoRelend` but work with shared references instead of mutable references.

## Usage Examples

### Basic Reborrowing

```rust
# use relend::Lend;
let mut value = 42;
let mut lend = Lend::new(&mut value);
let reborrowed = lend.rb();
```

### Optimizing Struct Memory Usage

The `Relend` trait allows for flexible and efficient struct definitions. Here's an example demonstrating how unused fields can be optimized:

```rust
# use relend::{IntoRelend, Lend, Relend};
struct Arg<'a, A: Relend, B: Relend = ()>(Lend<'a, (A, B)>);
impl<'a, A: IntoRelend<'a>, B: IntoRelend<'a>> Arg<'a, A, B> {
    fn new(a: A, b: B) -> Self {
        Arg((a, b).lend())
    }
}
impl<A: Relend, B: Relend> Arg<'_, A, B> {
    fn rb(&mut self) -> Arg<A, B> {
        Arg(self.0.rb())
    }
}

let mut x = 5;
let mut y = String::from("hello");
let mut both: Arg<&mut i32, &mut String> = Arg::new(&mut x, &mut y);

assert_eq!(std::mem::size_of_val(&both), 16);

*both.rb().0.target.0 += 1;
assert_eq!(both.0.target.1.pop(), Some('o'));
assert_eq!((x, y), (6, "hell".to_string()));

let mut z = 5;
let first_only: Arg<&mut i32> = Arg::new(&mut z, ());
assert_eq!(std::mem::size_of_val(&first_only), 8);

// `first_only` will have a smaller memory footprint than `both`
// and avoid unnecessary dereferencing for the second field
```

This example showcases several key aspects of `Relend`:

1. **Generic Structs with Relend**: `Arg` is defined with two generic parameters `A` and `B`, both constrained by the `Relend` trait. This allows for flexible combinations of types.

2. **Default Type Parameters**: The `B` parameter has a default type of `()`, allowing for easy creation of single-argument instances.

3. **Reborrowing Method**: The `rb` method demonstrates how `Relend` can be used to create new borrowed versions of the struct with potentially shorter lifetimes.

4. **Zero-Cost Optimization**: When `()` is used for the `B` parameter (as in `first_only`), the compiler can optimize away the unused field, reducing memory usage and potential dereferencing overhead.

### Applying Relend to Iterators

The library demonstrates how `Relend` can be applied to iterators, allowing for complex compositions of reborrowing iterators. Here's a simplified example based on the test code:

```rust
# use relend::{Lend, Relend, IntoRelend};
pub struct IterLend<'a, T: Relend>(Lend<'a, T>);
impl<T: RelendIterator> IterLend<'_, T> {
    fn rb<'short>(&'short mut self) -> IterLend<'short, T> {
        IterLend(self.0.rb())
    }
    fn next(self) -> Option<T::Item> {
        T::next(self.0.target)
    }
}

pub trait RelendIterator: Relend {
    type Item;
    fn next(this: Self::Target<'_>) -> Option<Self::Item>;
}

impl<T: Iterator> RelendIterator for &mut T {
    type Item = T::Item;
    fn next(this: &mut T) -> Option<Self::Item> {
        this.next()
    }
}
impl<T: RelendIterator, U: RelendIterator> RelendIterator for (T, U) {
    type Item = (T::Item, U::Item);
    fn next(this: Self::Target<'_>) -> Option<Self::Item> {
        Some((T::next(this.0)?, U::next(this.1)?))
    }
}

// Example of a custom iterator using Relend
struct WithIndex<'a, T: Relend> {
    index: &'a mut usize,
    iter: Lend<'a, T>,
}
impl<'a, T: RelendIterator + IntoRelend<'a>> WithIndex<'a, T> {
    pub fn new(iter: T, index: &'a mut usize) -> Self {
        Self { index, iter: Lend::new(iter) }
    }
}
impl<T: RelendIterator> Relend for WithIndex<'_, T> {
    type Target<'short> = WithIndex<'short, T> where Self: 'short;
    fn reborrow<'short, 'long>(this: &'short mut WithIndex<'long, T>) -> WithIndex<'short, T> {
        WithIndex { index: this.index, iter: this.iter.rb() }
    }
}
impl<T: RelendIterator> RelendIterator for WithIndex<'_, T> {
    type Item = T::Item;
    fn next(this: WithIndex<'_, T>) -> Option<Self::Item> {
        let item = IterLend(this.iter).next()?;
        *this.index += 1;
        Some(item)
    }
}

// Usage
let (mut index, mut iter1, mut iter2) = (0, [0, 1, 2].into_iter(), [3, 4, 5, 6].into_iter());
let mut iter = IterLend(Lend::new((WithIndex::new(&mut iter1, &mut index), &mut iter2)));

assert_eq!(iter.rb().next(), Some((0, 3)));
assert_eq!(iter.rb().next(), Some((1, 4)));
assert_eq!(iter.rb().next(), Some((2, 5)));
assert_eq!(iter.rb().next(), None);
assert_eq!(index, 3);
```

This example demonstrates several advanced features of `Relend`:

1. **Custom Iterator Wrappers**: `IterLend` wraps any type implementing `Relend`, providing a unified interface for iteration.

2. **Trait-Based Iterator Design**: The `RelendIterator` trait extends `Relend`, allowing for custom iterator implementations that can be reborrowed.

3. **Complex Borrowing Patterns**: `WithIndex` showcases how `Relend` can be used to create iterators that maintain mutable state (the index) alongside the iteration.

4. **Composition of Relend Types**: The example composes multiple `Relend` types (`WithIndex` and a mutable reference) into a single iterator, demonstrating the flexibility of this approach.

5. **Fine-Grained Lifetime Control**: The `rb` method on `IterLend` allows for creating new borrowed versions of the iterator with potentially shorter lifetimes, crucial for complex borrowing scenarios.

These examples illustrate how `Relend` provides powerful tools for creating flexible, efficient, and composable abstractions in Rust, whether working with data structures or iterators.

## Implementation Details

- The library makes extensive use of Rust's advanced type system features, including associated types, higher-rank trait bounds, and complex lifetime relationships.
- It provides implementations for common standard library types like `Option`, `Result`, and references.
- The `Lend<T>` struct serves as a convenient wrapper that implements `Deref` and `DerefMut`, allowing for ergonomic usage of reborrowed values.

## Conclusion

This library provides a powerful and flexible way to work with reborrowing in Rust, extending beyond simple references to allow for custom implementations on arbitrary types. It's particularly useful for complex data structures where fine-grained control over lifetimes is necessary, and can be applied to various constructs including iterators.