Enum eso::Eso

pub enum Eso<E, S, O> {
    E(E),
    S(S),
    O(O),
}

A three-way choice between an Ephemeral reference (i.e. with a lifetime that is not 'static), a Static reference and an Owned value.

All three of the type parameters can be An<T> or No<T>, which allows to construct subsets of the fullfunctionality, and to statically keep track of which variants may exist at any given point in the code.

If the parameter types statically specify that only one variant can have a value, e.g. Eso<An<E>, No<S>, No<O>> then the runtime representation should be as efficient as that of the sole present type.

Many type signatures in the impls use the type aliases defined in the x module to express how the type of the resulting Eso is related to the type parameters of the input Eso.

Variants

E(E)

An ephemeral value

S(S)

A shared or static value, meaning that client code can hold on to an S without being limited by any given lifetime.

O(O)

An owned value, meaning that client code has sole possession of the contained object (albeit it may be borrowed out by reference)

Implementations

impl<E, MS, MO> Eso<An<E>, MS, MO>

pub const fn from_ref(e: E) -> Self

Create an Eso from a reference

type Str<'a> = t::ESO<&'a str, &'static str, String>;
fn make_a_str<'a>(s: &'a str) -> Str<'a> {
    Str::from_ref(s)
}
let my_string = String::from("Hello World");
let my_str = make_a_str(my_string.as_str());

impl<ME, S, MO> Eso<ME, An<S>, MO>

pub const fn from_static(s: S) -> Self

Create an Eso from a shared/static reference

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_str = Str::from_static("Hello World");

impl<ME, MS, O> Eso<ME, MS, An<O>>

pub const fn from_owned(o: O) -> Self

Create an Eso from an owned object

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_str = Str::from_owned("Hello World".into());

impl<E, MS, O> Eso<An<E>, MS, An<O>>

pub fn from_cow<'a, T: ToOwned + ?Sized>(cow: Cow<'a, T>) -> Self where
    E: From<&'a T>,
    O: From<T::Owned>, 

Create an Eso from a Cow.

This will either convert the reference from a Cow::Borrowed into the correct generalized reference type via Borrow or take ownership of the owned value from a Cow::Owned.

type Str<'a> = t::EO<&'a str, &'static str, String>;

let owned_eso = Str::from_cow(Cow::Owned("Hello World".to_string()));
assert!(owned_eso.is_owning());
assert_eq!(owned_eso.get_ref::<&str>(), "Hello World");

let borrowed_eso = Str::from_cow(Cow::Borrowed("Hello World"));
assert!(borrowed_eso.is_reference());
assert_eq!(borrowed_eso.get_ref::<&str>(), "Hello World");

impl<ME, MS, O> Eso<ME, MS, An<O>>

pub fn to_mut(&mut self) -> &mut O where
    ME: MTake<O> + Clone,
    MS: MTake<O> + Clone, 

Get a mutable reference to the contained owned value, cloning out of a referenced object if necessary.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let mut my_str = Str::from_ref("Hello ");
my_str.to_mut().push_str("World!");
assert!(my_str.is_owning());
assert_eq!(my_str.get_ref::<&str>(), "Hello World!");

pub fn mutate<F, T>(&mut self, f: F) -> T where
    ME: MTake<O> + Clone,
    MS: MTake<O> + Clone,
    F: FnOnce(&mut O) -> T, 

Mutate the owned value. If no owned value is contained, the referenced value will be cloned into an owned form.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let mut my_str = Str::from_ref("Hello ");
my_str.mutate(|s| s.push_str("World!"));
assert!(my_str.is_owning());
assert_eq!(my_str.get_ref::<&str>(), "Hello World!");

impl<ME, MS, MO> Eso<ME, MS, MO>

pub fn get_ref<'a, T: 'a>(&'a self) -> T where
    ME: MBorrow<'a, T>,
    MS: MBorrow<'a, T>,
    MO: MBorrow<'a, T>, 

Borrow a generalized reference of type T from this Eso.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let ephemeral = Str::from_ref("Hello World");
let owning = Str::from_owned("Hello World".to_string());
assert_eq!(ephemeral.get_ref::<&str>(), owning.get_ref::<&str>());

pub fn try_get_mut(&mut self) -> Option<&mut MO::Inner> where
    MO: Maybe, 

Mutably borrow the owned value contained in this Eso, if it actually contains an owned value:

type Int<'a> = t::ESO<&'a i32, &'static i32, i32>;
let mut my_int = Int::from_owned(40);
if let Some(mut_ref) = my_int.try_get_mut() {
    *mut_ref += 2;
}
assert_eq!(my_int.get_ref::<&i32>(), &42);

Return None if self contains a reference:

type Int<'a> = t::ESO<&'a i32, &'static i32, i32>;
let mut my_int = Int::from_ref(&42);
assert!(matches!(my_int.try_get_mut(), None));

If clone-on-write behavior is desired, use the get_mut method instead.

pub fn into_cow<'a, T: ?Sized + ToOwned + 'a>(self) -> Cow<'a, T> where
    ME: MUnwrapInto<&'a T>,
    MS: MUnwrapInto<&'a T>,
    MO: MUnwrapInto<T::Owned>, 

Transform into a Cow.

The contained references must already be compatible with the requirements of [Cow<'a, T>]:

• The E and S inner values must be [Into<&'a T>]
• The O inner value must be Into<T::Owned>

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_ref("Hello World");
let my_owned = Str::from_owned("Hello World".to_string());
assert!(matches!(my_ref.into_cow(), Cow::Borrowed("Hello World")));
assert!(matches!(my_owned.into_cow(), Cow::Owned(_)));

pub fn merge(self) -> ME::Inner where
    ME: Maybe,
    MS: Maybe<Inner = ME::Inner>,
    MO: Maybe<Inner = ME::Inner>, 

Extract the contained value, if all variants may contain the same type.

impl<E, S, O> Eso<An<E>, No<S>, No<O>>

pub fn safe_unwrap_ephemeral(self) -> E

Safely move the ephemeral reference out of this Eso.

type OnlyE<'a> = t::E<&'a str, &'static str, String>;
let only_e = OnlyE::from_ref("Hello World");
let unwrapped = only_e.safe_unwrap_ephemeral();
assert_eq!(unwrapped, "Hello World");

This method is only callable on an Eso that is statically proven to contain an ephemeral reference, and thus cannot fail.

type MaybeS<'a> = t::ES<&'a str, &'static str, String>;
let maybe_s = MaybeS::from_ref("Hello World");
// Compile error: maybe_s could also contain a static reference!
let unwrapped = maybe_s.safe_unwrap_ephemeral();

impl<E, S, O> Eso<No<E>, No<S>, An<O>>

pub fn safe_unwrap_owned(self) -> O

Safely move the owned value out of this Eso.

type OnlyO<'a> = t::O<&'a str, &'static str, String>;
let only_o = OnlyO::from_owned("Hello World".to_string());
let unwrapped = only_o.safe_unwrap_owned();
assert_eq!(&unwrapped, "Hello World");

This method is only callable on an Eso that is statically proven to contain an owned value, and thus cannot fail.

type MaybeS<'a> = t::SO<&'a str, &'static str, String>;
let maybe_s = MaybeS::from_owned("Hello World".to_string());
// Compile error: maybe_s could also contain a static reference!
let unwrapped = maybe_s.safe_unwrap_owned();

pub fn get_owned_ref(&self) -> &O

Safely reference the owned value contained in this Eso.

type OnlyO<'a> = t::O<&'a str, &'static str, String>;
let only_o = OnlyO::from_owned("Hello World".to_string());
assert!(only_o.get_owned_ref().capacity() >= 11);

This method is only callable on an Eso that is statically proven to contain an ephemeral reference, and thus cannot fail.

type MaybeS<'a> = t::SO<&'a str, &'static str, String>;
let maybe_s = MaybeS::from_owned("Hello World".to_string());
maybe_s.get_owned_ref()

pub fn get_mut(&mut self) -> &mut O

Safely and mutably reference the owned value contained in this Eso.

type OnlyO<'a> = t::O<&'a str, &'static str, String>;
let mut only_o = OnlyO::from_owned("Hello ".to_string());
only_o.get_mut().push_str("World");
assert_eq!(only_o.get_ref::<&str>(), "Hello World");

This method is only callable on an Eso that is statically proven to contain an ephemeral reference, and thus cannot fail.

type MaybeS<'a> = t::SO<&'a str, &'static str, String>;
let maybe_s = MaybeS::from_owned("Hello World".to_string());
maybe_s.get_mut()

impl<E, S, O> Eso<No<E>, An<S>, No<O>>

pub fn safe_unwrap_static(self) -> S

Safely move the static/shared reference out of this Eso.

type OnlyS<'a> = t::S<&'a str, &'static str, String>;
let only_s = OnlyS::from_static("Hello World");
let unwrapped = only_s.safe_unwrap_static();
assert_eq!(unwrapped, "Hello World");

This method is only callable on an Eso that is statically proven to contain a static/shared reference, and thus cannot fail.

type MaybeE<'a> = t::ES<&'a str, &'static str, String>;
let maybe_e = MaybeE::from_static("Hello World");
// Compile error: maybe_s could also contain a static reference!
let unwrapped = maybe_e.safe_unwrap_owned();

impl<ME, MS, MO> Eso<ME, MS, MO>

pub fn map_e<F, T>(self, f: F) -> Eso<ME::Out, MS, MO> where
    ME: MaybeMap<T>,
    F: FnOnce(ME::Inner) -> T, 

Transform self´ by applying a function to the E` variant while preserving the other variants.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_ref("Hello World");
let mapped = my_ref.map_e(|_| "Ha!");
assert_eq!(mapped.get_ref::<&str>(), "Ha!");

let my_static = Str::from_static("Hello World");
let mapped = my_static.map_e(|_| "Ha!");
assert_eq!(mapped.get_ref::<&str>(), "Hello World");

pub fn map_s<F, T>(self, f: F) -> Eso<ME, MS::Out, MO> where
    MS: MaybeMap<T>,
    F: FnOnce(MS::Inner) -> T, 

Transform self´ by applying a function to the E` variant while preserving the other variants.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_static = Str::from_static("Hello World");
let mapped = my_static.map_s(|_| "Ha!");
assert_eq!(mapped.get_ref::<&str>(), "Ha!");

let my_ref = Str::from_ref("Hello World");
let mapped = my_ref.map_s(|_| "Ha!");
assert_eq!(mapped.get_ref::<&str>(), "Hello World");

pub fn map_o<F, T>(self, f: F) -> Eso<ME, MS, MO::Out> where
    MO: MaybeMap<T>,
    F: FnOnce(MO::Inner) -> T, 

Transform self´ by applying a function to the E` variant while preserving the other variants.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_owned("Hello World".to_string());
let mapped = my_ref.map_o(|e| e.to_uppercase());
assert_eq!(mapped.get_ref::<&str>(), "HELLO WORLD");

let my_static = Str::from_static("Hello World");
let mapped = my_static.map_o(|e| e.to_uppercase());
assert_eq!(mapped.get_ref::<&str>(), "Hello World");

pub fn map<EF, ET, SF, ST, OF, OT>(
    self,
    ef: EF,
    sf: SF,
    of: OF
) -> Eso<ME::Out, MS::Out, MO::Out> where
    ME: MaybeMap<ET>,
    MS: MaybeMap<ST>,
    MO: MaybeMap<OT>,
    EF: FnOnce(ME::Inner) -> ET,
    SF: FnOnce(MS::Inner) -> ST,
    OF: FnOnce(MO::Inner) -> OT, 

Transform `self´ by applying a different function to each of the variants.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
fn check(s: Str, into: &str) {
    let mapped = s.map(
            |e| "Ephemeral",
            |s| "Static",
            |o| o.to_uppercase());
    let the_string = mapped.get_ref::<&str>();
    assert_eq!(the_string, into);
}
check(Str::from_ref("Hello World"), "Ephemeral");
check(Str::from_static("Hello World"), "Static");
check(Str::from_owned("Hello World".to_string()), "HELLO WORLD");

pub fn flat_map<EF, SF, OF, ME1, MS1, MO1>(
    self,
    ef: EF,
    sf: SF,
    of: OF
) -> Eso<ME1, MS1, MO1> where
    ME: Maybe,
    MS: Maybe,
    MO: Maybe,
    EF: FnOnce(ME::Inner) -> Eso<ME1, MS1, MO1>,
    SF: FnOnce(MS::Inner) -> Eso<ME1, MS1, MO1>,
    OF: FnOnce(MO::Inner) -> Eso<ME1, MS1, MO1>, 

Special case of merge_with to match the expected name for operations that map a contained value into the container type.

pub fn merge_with<EF, SF, OF, T>(self, ef: EF, sf: SF, of: OF) -> T where
    ME: Maybe,
    MS: Maybe,
    MO: Maybe,
    EF: FnOnce(ME::Inner) -> T,
    SF: FnOnce(MS::Inner) -> T,
    OF: FnOnce(MO::Inner) -> T, 

Select one of the given functions to run based on which of the possible values is selected. The function will run on the inner values of the Maybes.

type Str = t::ESO<i32, char, String>;
fn check(s: Str, should: &str) {
    let str = s.merge_with(
        |e| (format!("{}", e)),
        |s| (format!("{}", s)),
        |o| o);
    assert_eq!(&str, should);
}
check(Str::from_ref(42), "42");
check(Str::from_static('!'), "!");
check(Str::from_owned("Hello World".to_owned()), "Hello World");

pub fn outer_map<EF, SF, OF, ME1, MS1, MO1>(
    self,
    ef: EF,
    sf: SF,
    of: OF
) -> Eso<ME1, MS1, MO1> where
    EF: FnOnce(ME) -> ME1,
    SF: FnOnce(MS) -> MS1,
    OF: FnOnce(MO) -> MO1, 

Select one of the given functions to run based on which of the possible values is selected. The function will run on the Maybes themselves.

impl<ME, MS, MO> Eso<ME, MS, MO>

pub fn try_split_ephemeral(self) -> Result<E<ME, MS, MO>, so<ME, MS, MO>> where
    ME: Maybe,
    MS: Maybe,
    MO: Maybe, 

Match on the ephemeral case, and modify the type parameters to prove the match, if successful.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_ref("Hello World");
let ephemeral = my_ref.try_split_ephemeral().unwrap();
//  ^^^^^^^^^---- carries type-level prrof that it can only be an Eso::E!
let the_ref = ephemeral.safe_unwrap_ephemeral();
assert_eq!(the_ref, "Hello World");

Otherwise, casts the type parameters to prove the non-match:

type Str<'a> = t::EO<&'a str, &'static str, String>;
let my_ref = Str::from_owned("Hello World".to_string());
let owned = my_ref.try_split_ephemeral().unwrap_err();
//  ^^^^^---- carries type-level prrof that it can not be an Eso::E.
//            Since we used the t::EO alias, that only leaves Eso::O.
let the_string: String = owned.safe_unwrap_owned();
assert_eq!(&the_string, "Hello World");

pub fn try_split_static(self) -> Result<S<ME, MS, MO>, eo<ME, MS, MO>> where
    ME: Maybe,
    MS: Maybe,
    MO: Maybe, 

Match on the static/shared case, and modify the type parameters to prove the match, if successful.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_static("Hello World");
let shared = my_ref.try_split_static().unwrap();
//  ^^^^^^^^^---- carries type-level prrof that it can only be an Eso::E!
let the_ref = shared.safe_unwrap_static();
assert_eq!(the_ref, "Hello World");

Otherwise, casts the type parameters to prove the non-match:

type Str<'a> = t::SO<&'a str, &'static str, String>;
let my_ref = Str::from_owned("Hello World".to_string());
let owned = my_ref.try_split_static().unwrap_err();
//  ^^^^^---- carries type-level prrof that it can not be an Eso::E.
//            Since we used the t::EO alias, that only leaves Eso::O.
let the_string: String = owned.safe_unwrap_owned();
assert_eq!(&the_string, "Hello World");

pub fn try_split_owned(self) -> Result<O<ME, MS, MO>, es<ME, MS, MO>> where
    ME: Maybe,
    MS: Maybe,
    MO: Maybe, 

Match on the owned case, and modify the type parameters to prove the match, if successful.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_owned("Hello World".to_string());
let owned = my_ref.try_split_owned().unwrap();
//  ^^^^^---- carries type-level prrof that it can only be an Eso::E!
let the_string = owned.safe_unwrap_owned();
assert_eq!(&the_string, "Hello World");

Otherwise, casts the type parameters to prove the non-match:

type Str<'a> = t::SO<&'a str, &'static str, String>;
let my_ref = Str::from_static("Hello World");
let shared = my_ref.try_split_owned().unwrap_err();
//  ^^^^^^---- carries type-level prrof that it can not be an Eso::E.
//             Since we used the t::EO alias, that only leaves Eso::O.
let the_str = shared.safe_unwrap_static();
assert_eq!(the_str, "Hello World");

pub fn try_unwrap_ephemeral(self) -> Result<ME::Inner, so<ME, MS, MO>> where
    ME: Maybe, 

Retrieve the contained ephemeral reference, if self is Eso::E.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_ref("Hello World");
assert_eq!(
    my_ref.try_unwrap_ephemeral().unwrap(),
    "Hello World"
);

Otherwise, casts the type parameters to prove the non-match:

type Str<'a> = t::EO<&'a str, &'static str, String>;
let my_ref = Str::from_owned("Hello World".to_string());
let owned = my_ref.try_unwrap_ephemeral().unwrap_err();
//  ^^^^^---- carries type-level prrof that it can not be an Eso::E.
//            Since we used the t::EO alias, that only leaves Eso::O.
let the_string: String = owned.safe_unwrap_owned();
assert_eq!(&the_string, "Hello World");

pub fn try_unwrap_owned(self) -> Result<MO::Inner, es<ME, MS, MO>> where
    MO: Maybe, 

Retrieve the contained owned value.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_owned("Hello World".to_string());
assert_eq!(
    my_ref.try_unwrap_owned().unwrap(),
    "Hello World".to_string()
);

Otherwise, casts the type parameters to prove the non-match:

type Str<'a> = t::EO<&'a str, &'static str, String>;
let my_ref = Str::from_ref("Hello World");
let ephemeral = my_ref.try_unwrap_owned().unwrap_err();
//  ^^^^^^^^^---- carries type-level prrof that it can not be an Eso::E.
//                Since we used the t::EO alias, that only leaves Eso::O.
let the_str = ephemeral.safe_unwrap_ephemeral();
assert_eq!(the_str, "Hello World");

pub fn try_unwrap_static(self) -> Result<MS::Inner, eo<ME, MS, MO>> where
    MS: Maybe, 

Retrieve the contained static/shared value.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_ref = Str::from_static("Hello World");
assert_eq!(
    my_ref.try_unwrap_static().unwrap(),
    "Hello World"
);

Otherwise, casts the type parameters to prove the non-match:

type Str<'a> = t::SO<&'a str, &'static str, String>;
let my_ref = Str::from_owned("Hello World".to_string());
let owned = my_ref.try_unwrap_static().unwrap_err();
//  ^^^^^---- carries type-level prrof that it can not be an Eso::E.
//            Since we used the t::SO alias, that only leaves Eso::O.
let the_string = owned.safe_unwrap_owned();
assert_eq!(&the_string, "Hello World");

pub fn relax<ME1, MS1, MO1>(self) -> Eso<ME1, MS1, MO1> where
    ME: Relax<ME1>,
    MS: Relax<MS1>,
    MO: Relax<MO1>, 

Relax the type parameters to fit an expected combination of type parameters.

See Relax for the rules about relaxation.

An Eso always carries all three of its type parameters in its type signature. Sometimes this leads to errors:

type Str<'a> = t::SO<&'a str, &'static str, String>;
fn tie_to_lifetime<'a>(lifetime_of: &'a i32) -> Str<'a> {
    Str::from_static("Hello World")
}
let i = 42;
let my_str = tie_to_lifetime(&i); // <-- tied to i's lifetime
function_that_expects_a_static(my_str); // <-- ERROR

Since the t::SO alias contains type-level proof that the E case is not possible, the first type parameter can be safely changed from &'a str to &'static str:

let i = 42;
let my_str = tie_to_lifetime(&i); // <-- tied to i's lifetime
let my_str: Str<'static> = my_str.relax(); // <-- known to be static
function_that_expects_a_static(my_str); // No Error

pub fn clone_relax<ME1, MS1, MO1>(&self) -> Eso<ME1, MS1, MO1> where
    ME: Clone + Relax<ME1>,
    MS: Clone + Relax<MS1>,
    MO: Clone + Relax<MO1>, 

Clone the Eso with relaxed type parameters, to fit an expected configuration. See Eso::relax for more information.

pub fn split(self) -> ConstrainedEsoOfEso<ME, MS, MO> where
    ME: Maybe,
    MS: Maybe,
    MO: Maybe, 

Distinguish the three cases of Eso while maintaining the inner Eso-ness of the resulting values.

Since Eso does not implement Maybe, the return value is pretty much only useful for pattern matching, as none of the Eso machinery will be applicable to the result type.

pub fn unify(self) -> ME::Out3 where
    ME: Unify3<MS, MO>, 

Merge the three possible values into one by selecting from the variants according to the rules of unify

type E<'a> = t::E<&'a i32, &'static i32, i32>;
type S<'a> = t::S<&'a i32, &'static i32, i32>;
type O<'a> = t::O<&'a i32, &'static i32, i32>;
type Nested<'a> = Eso<E<'a>, S<'a>, O<'a>>;
type Merged<'a> = t::ESO<&'a i32, &'static i32, i32>;

let eso1: Merged = Nested::E(E::from_ref(r)).unify();
let eso2: Merged = Nested::S(S::from_static(&12)).unify();
let eso3: Merged = Nested::O(O::from_owned(42)).unify();
assert_eq!(eso1.get_ref::<&i32>(), r);
assert_eq!(eso2.get_ref::<&i32>(), &12);
assert_eq!(eso3.get_ref::<&i32>(), &42);

As in unify, any No values can be unified with anything else:

type E = t::E<i32, T1, T2>;
type S = t::S<T3, i32, T4>;
type O = t::O<T5, T6, i32>;
type Nested = Eso<E, S, O>;
type Merged = t::ESO<i32, i32, i32>;

let eso1: Merged = Nested::E(E::from_ref(1)).unify();
let eso2: Merged = Nested::S(S::from_static(2)).unify();
let eso3: Merged = Nested::O(O::from_owned(3)).unify();
assert_eq!(eso1.merge(), 1);
assert_eq!(eso2.merge(), 2);
assert_eq!(eso3.merge(), 3);

impl<E, S, O, ES, EO, SE, SO, OE, OS> Eso<E<E, ES, EO>, S<SE, S, SO>, O<OE, OS, O>>

pub fn unsplit(self) -> ESO<E, S, O>

Undo a split. This is a constrained special case of Eso::unify.

impl<ME, MS, MO> Eso<ME, MS, MO>

Functions to ask about the status of an Eso.

pub fn is_ephemeral(&self) -> bool

Returns true if the Eso is of the Eso::E variant.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
fn my_function(a_borrowed_str: &str) {
    let ephemeral = Str::from_ref(a_borrowed_str);
    let shared = Str::from_static("Hello World");
    let owned = Str::from_owned("Hello World".to_string());
    assert!(ephemeral.is_ephemeral());
    assert!(!shared.is_ephemeral());
    assert!(!owned.is_ephemeral());
}
my_function("Hello World");

pub fn is_static(&self) -> bool

Returns true if the Eso is of the Eso::S variant.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
fn my_function(a_borrowed_str: &str) {
    let ephemeral = Str::from_ref(a_borrowed_str);
    let shared = Str::from_static("Hello World");
    let owned = Str::from_owned("Hello World".to_string());
    assert!(!ephemeral.is_static());
    assert!(shared.is_static());
    assert!(!owned.is_static());
}
my_function("Hello World");

pub fn is_owning(&self) -> bool

Returns true if the Eso is of the Eso::O variant.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
fn my_function(a_borrowed_str: &str) {
    let ephemeral = Str::from_ref(a_borrowed_str);
    let shared = Str::from_static("Hello World");
    let owned = Str::from_owned("Hello World".to_string());
    assert!(!ephemeral.is_owning());
    assert!(!shared.is_owning());
    assert!(owned.is_owning());
}
my_function("Hello World");

pub fn is_reference(&self) -> bool

Returns true if the Eso does not own the contained value, i. e. it is of the Eso::E or Eso::S variants.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
fn my_function(a_borrowed_str: &str) {
    let ephemeral = Str::from_ref(a_borrowed_str);
    let shared = Str::from_static("Hello World");
    let owned = Str::from_owned("Hello World".to_string());
    assert!(ephemeral.is_reference());
    assert!(shared.is_reference());
    assert!(!owned.is_reference());
}
my_function("Hello World");

pub fn is_lasting(&self) -> bool

Returns true if the Eso is lasting, i. e. it is not an ephemeral reference.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
fn my_function(a_borrowed_str: &str) {
    let ephemeral = Str::from_ref(a_borrowed_str);
    let shared = Str::from_static("Hello World");
    let owned = Str::from_owned("Hello World".to_string());
    assert!(!ephemeral.is_lasting());
    assert!(shared.is_lasting());
    assert!(owned.is_lasting());
}
my_function("Hello World");

impl<ME, MS, MO> Eso<ME, MS, MO>

Methods to transform an Eso between its different states.

pub fn into_static(self) -> sO<ME, MS, MO> where
    ME: MTake<MO::Inner>,
    MO: Maybe, 

Transform this Eso into one that can only be a static/shared reference or an owned value.

This clones an ephemeral reference into an owned value via Take but will move a shared/static reference or an owned value into the result unchanged.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
type StaticStr<'a> = t::SO<&'a str, &'static str, String>;
let my_reference = Str::from_ref("Hello World");
assert!(my_reference.is_ephemeral());
let my_static: StaticStr = my_reference.into_static();
assert!(my_static.is_lasting());

The conversion will not remove the lifetimes from the type of the reference:

fn my_fn(borrowed: &str) {
    let my_reference = Str::from_ref(borrowed);
    let my_static = my_reference.into_static();
    function_consuming_static(my_static);
}
my_fn("Hello World");

However, given that there is a type-level proof that the return value of this function cannot be of the E variant, the relax function can be used to drop the 'a lifetime:

fn my_fn(borrowed: &str) {
    let my_reference = Str::from_ref(borrowed);
    let my_static: Str<'static> = my_reference.into_static().relax();
    function_consuming_static(my_static);
}
my_fn("Hello World");

pub fn to_static(&self) -> sO<ME, MS, MO> where
    ME: MTake<MO::Inner> + Clone,
    MS: Maybe + Clone,
    MO: Maybe + Clone, 

Clone this Eso into one that can only be a static/shared reference or an owned value.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
fn my_fn(borrowed: &str) -> Str {
    let my_reference = Str::from_ref(borrowed);
    let my_static: Str<'static> = my_reference.to_static().relax();
    function_consuming_static(my_static);
    my_reference
}
assert_eq!(my_fn("Hello World").get_ref::<&str>(), "Hello World");

The to_static method clones an ephemeral reference into an owned value via Take::own but clones a shared/static reference or an owned value into the result unchanged.

See Eso::into_static for considerations regarding the lifetime of the result.

pub fn into_owning(self) -> O<ME, MS, MO> where
    ME: MTake<MO::Inner>,
    MS: MTake<MO::Inner>,
    MO: Maybe, 

Transform this Eso into one that is definitely an owned value.

Any reference will be cloned into an owned form via Take, and an owned value will be moved into the result unchanged.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_str = Str::from_ref("Hello World");
let my_owned = my_str.into_owning();
assert!(my_owned.is_owning());

pub fn to_owning(&self) -> O<ME, MS, MO> where
    ME: MTake<MO::Inner> + Clone,
    MS: MTake<MO::Inner> + Clone,
    MO: Maybe + Clone, 

Clone this Eso into one that is definitely an owned value.

Any reference will be cloned into an owned form via Take, and an owned value will be cloned into the result via Clone.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_str = Str::from_ref("Hello World");
let my_owned = my_str.to_owning();
assert!(my_str.is_ephemeral()); // <-- my_str is still alive
assert!(my_owned.is_owning());

pub fn reference<'a>(&'a self) -> ES<ME, MS, MO> where
    ME: Maybe + Clone,
    MS: Maybe + Clone,
    MO: MBorrow<'a, ME::Inner>, 

Borrow an ephemeral reference or preserve a static/shared reference. If the Eso contains an owned value, borrow a reference to it.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_shared = Str::from_static("Hello World");
let my_owned = Str::from_owned("Hello World".to_string());
assert!(my_shared.reference().is_static());
assert!(my_owned.reference().is_ephemeral());

pub fn ephemeral<'a>(&'a self) -> E<ME, MS, MO> where
    ME: Maybe + Clone,
    MS: MBorrow<'a, ME::Inner>,
    MO: MBorrow<'a, ME::Inner>, 

Borrow an ephemeral reference.

Clones an already-existing ephemeral reference, and borrows from a static reference or an owned value.

type Str<'a> = t::ESO<&'a str, &'static str, String>;
let my_shared = Str::from_static("Hello World");
let my_owned = Str::from_owned("Hello World".to_string());
assert!(my_shared.ephemeral().is_ephemeral());
assert!(my_owned.ephemeral().is_ephemeral());

pub fn try_intern_ephemeral(self) -> Result<S<ME, MS, MO>, eo<ME, MS, MO>> where
    ME: MTryInternRef<MS::Inner>,
    MS: Maybe,
    MO: Maybe, 

Try transforming an ephemeral reference into a shared/static reference by interning.

type Str<'a> = t::ESO<&'a str, Rc<str>, String>;
let ephemeral = Str::from_ref("Hello World");
let shared = ephemeral.try_intern_ephemeral().expect("Should have worked");
assert!(shared.is_static());
assert_eq!(shared.get_ref::<&str>(), "Hello World");

pub fn try_intern(self) -> Result<S<ME, MS, MO>, eo<ME, MS, MO>> where
    ME: MTryInternRef<MS::Inner>,
    MS: Maybe,
    MO: MTryIntern<MS::Inner>, 

Try transforming an ephemeral reference or an owned value into a shared/static reference by interning.

type Str<'a> = t::ESO<&'a str, Rc<str>, String>;
let owned = Str::from_owned("Hello World".to_string());
let shared = owned.try_intern().expect("Should have worked");
assert!(shared.is_static());
assert_eq!(shared.get_ref::<&str>(), "Hello World");

pub fn intern_or_take(self) -> SO<ME, MS, MO> where
    ME: MTryInternRef<MS::Inner> + MTake<MO::Inner>,
    MS: Maybe,
    MO: Maybe, 

Try transforming an ephemeral reference or an owned value into a shared/static reference by interning, and if this does not work, clone it into an owned value via Take::own.

type Str<'a> = t::ESO<&'a str, Rc<str>, String>;
let my_ref = Str::from_ref("Hello World");
let interned = my_ref.intern_or_take();
assert!(interned.is_static());
assert_eq!(interned.get_ref::<&str>(), "Hello World");
// TODO an example for failed interning

pub fn intern_ephemeral(self) -> SO<ME, MS, MO> where
    ME: MInternRef<MS::Inner>,
    MS: Maybe,
    MO: Maybe, 

Try transforming an ephemeral reference into a shared/static reference by interning.

type Str<'a> = t::ESO<&'a str, Rc<str>, String>;
let ephemeral = Str::from_ref("Hello World");
let shared = ephemeral.intern_ephemeral();
assert!(shared.is_static());
assert_eq!(shared.get_ref::<&str>(), "Hello World");

pub fn intern(self) -> S<ME, MS, MO> where
    ME: MInternRef<MS::Inner>,
    MS: Maybe,
    MO: MIntern<MS::Inner>, 

Try transforming an ephemeral reference or an owned value into a shared/static reference by interning.

type Str<'a> = t::ESO<&'a str, Rc<str>, String>;
let owned = Str::from_owned("Hello World".to_string());
let shared = owned.intern();
assert!(shared.is_static());
assert_eq!(shared.get_ref::<&str>(), "Hello World");

Trait Implementations

impl<E: Clone, S: Clone, O: Clone> Clone for Eso<E, S, O>

fn clone(&self) -> Eso<E, S, O>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<E: Debug, S: Debug, O: Debug> Debug for Eso<E, S, O>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a, T, E, MS, MO> From<&'a T> for Eso<An<E>, MS, MO> where
    E: From<&'a T>, 

fn from(r: &'a T) -> Self

Performs the conversion.

impl<'a, T: ToOwned, MS> From<Cow<'a, T>> for Eso<An<&'a T>, MS, An<T::Owned>>

fn from(it: Cow<'a, T>) -> Self

Performs the conversion.

impl<E, S, O> Impossible for Eso<No<E>, No<S>, No<O>>

fn absurd<T>(&self) -> T

Conjure up anything from the nonexistant value.

impl<AE, AS, AO, BE, BS, BO> Unify<Eso<BE, BS, BO>> for Eso<AE, AS, AO> where
    AE: Unify<BE>,
    AS: Unify<BS>,
    AO: Unify<BO>, 

type Out = Eso<AE::Out, AS::Out, AO::Out>

The result of unifying Self and B

fn inject_a(self) -> Self::Out

Make an Out value, given a value of type Self

fn inject_b(b: Eso<BE, BS, BO>) -> Self::Out

Make an Out value, given a value of type B