#lifetime #borrow #macro

no-std borrowme

The missing compound borrowing for Rust

15 releases

0.0.15 May 18, 2024
0.0.14 May 2, 2023

#422 in Rust patterns

Download history 8/week @ 2024-03-16 31/week @ 2024-03-23 37/week @ 2024-03-30 46/week @ 2024-04-06 19/week @ 2024-04-13 23/week @ 2024-04-20 2/week @ 2024-04-27 188/week @ 2024-05-18 19/week @ 2024-05-25 14/week @ 2024-06-01 49/week @ 2024-06-08 33/week @ 2024-06-15 5/week @ 2024-06-22 1/week @ 2024-06-29

92 downloads per month
Used in 2 crates

MIT/Apache

61KB
591 lines

borrowme

github crates.io docs.rs build status

The missing compound borrowing for Rust.

Rust comes with two sibling traits which that can convert from owned to borrowed: ToOwned, Borrow and BorrowMut.

These can convert most simple types such as &str to and from String. But lets think of this in a broader perspective. How to we convert a type that has lifetimes, to one which does not? This crate defines its own ToOwned, Borrow and BorrowMut traits which serve a similar purpose to the ones in std but are implemented so that they can do this not only for simple references but also for compound types which receives lifetimes.

To help us implement these traits the #[borrowme] attribute macro is provided (see this section for why it's not a derive).

#[borrowme]
#[derive(Clone)]
#[borrowed_attr(derive(Copy))]
struct Word<'a> {
    text: &'a str,
}

From this we get the following types and implementations:

#[derive(Clone, Copy)]
struct Word<'a> {
    text: &'a str,
}

#[derive(Clone)]
struct OwnedWord {
    text: String,
}

impl borrowme::ToOwned for Word<'_> {
    type Owned = OwnedWord;

    fn to_owned(&self) -> OwnedWord {
        /* .. */
    }
}

impl borrowme::Borrow for OwnedWord {
    type Target<'a> = Word<'a>;

    fn borrow(&self) -> Word<'_> {
        /* .. */
    }
}

By itself this isn't much, but here's the big trick. Types using this crate can be composed and converted into their borrowed or owned counterparts as needed:

use std::collections::HashMap;

#[borrowme]
struct Word<'a> {
    text: &'a str,
}

#[borrowme]
struct Dictionary<'a> {
    words: HashMap<&'a str, Word<'a>>,
}

let dictionary = Dictionary {
    /* .. */
};

let owned_dictionary: OwnedDictionary = borrowme::to_owned(&dictionary);
let dictionary2: Dictionary<'_> = borrowme::borrow(&owned_dictionary);

Dependencies

~300–760KB
~18K SLoC