yoke

Crates.ioyoke
lib.rsyoke
version0.7.4
sourcesrc
created_at2021-05-01 00:44:23.745711
updated_at2024-05-28 19:58:17.965715
descriptionAbstraction allowing borrowed data to be carried along with the backing data it borrows from
homepage
repositoryhttps://github.com/unicode-org/icu4x
max_upload_size
id391760
size118,682
icu4x-release (github:unicode-org:icu4x-release)

documentation

README

yoke crates.io

This crate provides [Yoke<Y, C>][Yoke], 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()][Yoke::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.

More Information

For more information on development, authorship, contributing etc. please visit ICU4X home page.

Commit count: 3247

cargo fmt