eso

Crates.ioeso
lib.rseso
version0.0.2
sourcesrc
created_at2021-05-18 18:11:08.315789
updated_at2021-05-22 16:11:22.635761
descriptionType machinery to build Cow-like containers
homepagehttps://github.com/braunse/eso
repositoryhttps://github.com/braunse/eso.git
max_upload_size
id399062
size128,434
(braunse)

documentation

https://docs.rs/eso

README

Eso - type-level building block for making Cow-like containers

Crates.io docs.rs GitHub issues GitHub pull requests GitHub last commit GitHub Workflow Status Crates.io

This library provids the Eso struct, a versatile building block for making newtypes that may own or reference their contents.

How to use

Add to your Cargo.toml like:

[dependencies]
eso = "0.0.0"

Example

Here is how to make a basic Cow-like type:

use eso::t;

pub struct SmartString<'a>(t::SO<&'a str, &'a str, String>);

impl SmartString {
    fn from_ref(c: &'static str) -> Self {
        SmartString(t::SO::from_static(c))
    }

    fn from_string(s: String) -> Self {
        SmartString(t::SO::from_owned(s))
    }

    fn into_owned(self) -> String {
        self.0.into_owning().safe_unwrap_owned()
    }

    fn is_owned(&self) -> bool {
        self.0.is_owning()
    }

    fn is_borrowed(&self) -> bool {
        self.0.is_reference()
    }

    fn to_mut(&mut self) -> &mut String {
        self.0.to_mut()
    }
}

impl Deref for SmartString {
    type Target = str;

    fn deref(&self) -> &str {
        self.0.get_ref()
    }
}

Details

Eso is very flexible, because it is meant as a building block for library authors who will restrict its flexibility to make sense for their respective use cases:

  • The Eso type itself can represent a choice out of any subset of

    • a borrowed reference
    • a static or shared reference
    • an owned value

    Which of these variants exist in the Eso type depends on the type parameters and can vary between usages in the client code.

  • Eso generalizes references and ownership.

    For example, you can make a Cow-like type that stores a custom type instead of a normal reference, so you could make a copy-on-write OwningRef

The price for this flexibility is ergonomics. When using eso the types can get rather long and the where-clauses in the library are rather unwieldy.

To Do

  • More API docs
  • More tests
  • More examples
Commit count: 31

cargo fmt