Crate yoke

This crate provides Yoke<Y, C>, which allows one to “yoke” (attach) a zero-copy deserialized object (say, a Cow<'a, str>) to the source it was deserialized from, (say, an Rc<[u8]>), known in this crate as a “cart”, producing a type that looks like Yoke<Cow<'static, str>, Rc<[u8]>> and can be moved around with impunity.

Succinctly, this allows one to “erase” static lifetimes and turn them into dynamic ones, similarly to how dyn allows one to “erase” static types and turn them into dynamic ones.

Most of the time the yokeable Y type will be some kind of zero-copy deserializable abstraction, potentially with an owned variant (like Cow, ZeroVec, or an aggregate containing such types), and the cart C will be some smart pointer like Box<T>, Rc<T>, or Arc<T>, potentially wrapped in an Option<T>.

The key behind this crate is Yoke::get(), where calling .get() on a type like Yoke<Cow<'static, str>, _> will get you a short-lived &'a Cow<'a, str>, restricted to the lifetime of the borrow used during .get(). This is entirely safe since the Cow borrows from the cart type C, which cannot be interfered with as long as the Yoke is borrowed by .get(). .get() protects access by essentially reifying the erased lifetime to a safe local one when necessary.

See the documentation of Yoke for more details.

Modules

• cartable_ptr
  Types for optional pointers with niche optimization.
• either
  Types to enable polymorphic carts.
• erased
  This module contains helper types for erasing Cart types.
• trait_hack
  Workarounds for adding trait bounds to yoke objects.

Structs

• Yoke
  A Cow-like borrowed object “yoked” to its backing data.

Traits

• CloneableCart
  This trait marks cart types that do not change source on cloning
• Yokeable
  The Yokeable<'a> trait is implemented on the 'static version of any zero-copy type; for example, Cow<'static, T> implements Yokeable<'a> (for all 'a). One can use Yokeable::Output on this trait to obtain the “lifetime’d” value of the Cow<'static, T>, e.g. <Cow<'static, T> as Yokeable<'a>'>::Output is Cow<'a, T>.

Derive Macros

• Yokeable
  Custom derive for yoke::Yokeable,