1 // This file is part of ICU4X. For terms of use, please see the file 2 // called LICENSE at the top level of the ICU4X source tree 3 // (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). 4 5 //! This crate provides [`Yoke<Y, C>`][Yoke], which allows one to "yoke" (attach) a zero-copy deserialized 6 //! object (say, a [`Cow<'a, str>`](alloc::borrow::Cow)) to the source it was deserialized from, (say, an [`Rc<[u8]>`](alloc::rc::Rc)), 7 //! known in this crate as a "cart", producing a type that looks like `Yoke<Cow<'static, str>, Rc<[u8]>>` 8 //! and can be moved around with impunity. 9 //! 10 //! Succinctly, this allows one to "erase" static lifetimes and turn them into dynamic ones, similarly 11 //! to how `dyn` allows one to "erase" static types and turn them into dynamic ones. 12 //! 13 //! Most of the time the yokeable `Y` type will be some kind of zero-copy deserializable 14 //! abstraction, potentially with an owned variant (like [`Cow`](alloc::borrow::Cow), 15 //! [`ZeroVec`](https://docs.rs/zerovec), or an aggregate containing such types), and the cart `C` will be some smart pointer like 16 //! [`Box<T>`](alloc::boxed::Box), [`Rc<T>`](alloc::rc::Rc), or [`Arc<T>`](std::sync::Arc), potentially wrapped in an [`Option<T>`](Option). 17 //! 18 //! The key behind this crate is [`Yoke::get()`], where calling [`.get()`][Yoke::get] on a type like 19 //! `Yoke<Cow<'static, str>, _>` will get you a short-lived `&'a Cow<'a, str>`, restricted to the 20 //! lifetime of the borrow used during [`.get()`](Yoke::get). This is entirely safe since the `Cow` borrows from 21 //! the cart type `C`, which cannot be interfered with as long as the `Yoke` is borrowed by [`.get()`](Yoke::get). 22 //! [`.get()`](Yoke::get) protects access by essentially reifying the erased lifetime to a safe local one 23 //! when necessary. 24 //! 25 //! See the documentation of [`Yoke`] for more details. 26 27 // https://github.com/unicode-org/icu4x/blob/main/documents/process/boilerplate.md#library-annotations 28 #![cfg_attr(all(not(test), not(doc)), no_std)] 29 #![cfg_attr( 30 not(test), 31 deny( 32 clippy::indexing_slicing, 33 clippy::unwrap_used, 34 clippy::expect_used, 35 clippy::panic, 36 clippy::exhaustive_structs, 37 clippy::exhaustive_enums, 38 missing_debug_implementations, 39 ) 40 )] 41 // The lifetimes here are important for safety and explicitly writing 42 // them out is good even when redundant 43 #![allow(clippy::needless_lifetimes)] 44 45 #[cfg(feature = "alloc")] 46 extern crate alloc; 47 48 pub mod cartable_ptr; 49 pub mod either; 50 #[cfg(feature = "alloc")] 51 pub mod erased; 52 mod kinda_sorta_dangling; 53 mod macro_impls; 54 pub mod trait_hack; 55 mod yoke; 56 mod yokeable; 57 #[cfg(feature = "zerofrom")] 58 mod zero_from; 59 60 #[cfg(feature = "derive")] 61 pub use yoke_derive::Yokeable; 62 63 pub use crate::yoke::{CloneableCart, Yoke}; 64 pub use crate::yokeable::Yokeable; 65 66 #[cfg(feature = "zerofrom")] 67 use zerofrom::ZeroFrom; 68