Module eso::borrow

The Take and Borrow traits abstract over the duality between owned and borrowed types, much in the same way as the standard-library Borrow and ToOwned traits do.

The difference between these and the standard-library traits is that the traits here are more generic. See the specific traits for details.

Eso differentiates three different categories of values:

	Category	Analogy	Description
E	Ephemeral	&'a str	A reference to a shared value with a limited lifetime
S	Static	&'static str	A reference to a shared value that client code can hold on to indefinitely
O	Owned	String	A value that is exclusively owned and can be mutated (if no references to it have been borrowed out)

These characteristics are enforced by Eso only on a per-function basis, but not in general. Client code should enforce them where necessary.

This module defines traits to convert between the categories:

From	To Ephemeral	To Static	To Owned
Ephemeral		TryInternRef, InternRef	Take
Static	Borrow		Take
Owned	Borrow	TryInternRef, TryIntern, InternRef, Intern

As can be seen from the table, there is some additional complexity regarding the interning operation:

1. Interning may fail: Depending on the implementation, not all values may have a static counterpart.
2. Owned values may offer optimization opportunities: If the owned value is not needed after the interning operation, it is cheaper to move it into the interning function.

Open questions / TODO

• actually implement the ...Intern... traits
• think about naming:
  • Borrow clashes with std
  • Take does not seem like a good description of what is actually happening
• is Borrowing from an Owned really the same operation as Borrowing from a static reference?

Traits

Borrow	A value that can be borrowed as a generalized reference of type T.
Intern	A value that can be interned from an owned value, where interning cannot fail.
InternRef	A value that can be interned from a reference, where interning cannot fail.
Take	A version of the ToOwned trait describing generalized references from which an owned form can be cloned.
TryIntern	A value that can be interned from an owned value, where interning may fail.
TryInternRef	A value that can be interned from a reference, where interning may fail.