From 26a029d407be480d791972afb5975cf62c9360a6 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 19 Apr 2024 02:47:55 +0200 Subject: Adding upstream version 124.0.1. Signed-off-by: Daniel Baumann --- third_party/rust/yoke/src/lib.rs | 66 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 third_party/rust/yoke/src/lib.rs (limited to 'third_party/rust/yoke/src/lib.rs') diff --git a/third_party/rust/yoke/src/lib.rs b/third_party/rust/yoke/src/lib.rs new file mode 100644 index 0000000000..e5adca62fb --- /dev/null +++ b/third_party/rust/yoke/src/lib.rs @@ -0,0 +1,66 @@ +// This file is part of ICU4X. For terms of use, please see the file +// called LICENSE at the top level of the ICU4X source tree +// (online at: https://github.com/unicode-org/icu4x/blob/main/LICENSE ). + +//! This crate provides [`Yoke`][Yoke], which allows one to "yoke" (attach) a zero-copy deserialized +//! object (say, a [`Cow<'a, str>`](alloc::borrow::Cow)) to the source it was deserialized from, (say, an [`Rc<[u8]>`](alloc::rc::Rc)), +//! known in this crate as a "cart", producing a type that looks like `Yoke, 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`](alloc::borrow::Cow), +//! [`ZeroVec`](https://docs.rs/zerovec), or an aggregate containing such types), and the cart `C` will be some smart pointer like +//! [`Box`](alloc::boxed::Box), [`Rc`](alloc::rc::Rc), or [`Arc`](std::sync::Arc), potentially wrapped in an [`Option`](Option). +//! +//! The key behind this crate is [`Yoke::get()`], where calling [`.get()`][Yoke::get] on a type like +//! `Yoke, _>` will get you a short-lived `&'a Cow<'a, str>`, restricted to the +//! lifetime of the borrow used during [`.get()`](Yoke::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()`](Yoke::get). +//! [`.get()`](Yoke::get) protects access by essentially reifying the erased lifetime to a safe local one +//! when necessary. +//! +//! See the documentation of [`Yoke`] for more details. + +// https://github.com/unicode-org/icu4x/blob/main/docs/process/boilerplate.md#library-annotations +#![cfg_attr(all(not(test), not(doc)), no_std)] +#![cfg_attr( + not(test), + deny( + clippy::indexing_slicing, + clippy::unwrap_used, + clippy::expect_used, + clippy::panic, + clippy::exhaustive_structs, + clippy::exhaustive_enums, + missing_debug_implementations, + ) +)] +// The lifetimes here are important for safety and explicitly writing +// them out is good even when redundant +#![allow(clippy::needless_lifetimes)] + +#[cfg(feature = "alloc")] +extern crate alloc; + +pub mod either; +#[cfg(feature = "alloc")] +pub mod erased; +mod kinda_sorta_dangling; +mod macro_impls; +pub mod trait_hack; +mod yoke; +mod yokeable; +#[cfg(feature = "zerofrom")] +mod zero_from; + +#[cfg(feature = "derive")] +pub use yoke_derive::Yokeable; + +pub use crate::yoke::{CloneableCart, Yoke}; +pub use crate::yokeable::Yokeable; + +#[cfg(feature = "zerofrom")] +use zerofrom::ZeroFrom; -- cgit v1.2.3