From 4547b622d8d29df964fa2914213088b148c498fc Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 14:18:32 +0200 Subject: Merging upstream version 1.67.1+dfsg1. Signed-off-by: Daniel Baumann --- vendor/yoke/.cargo-checksum.json | 1 + vendor/yoke/Cargo.toml | 83 +++ vendor/yoke/LICENSE | 51 ++ vendor/yoke/README.md | 27 + vendor/yoke/src/either.rs | 87 +++ vendor/yoke/src/erased.rs | 41 ++ vendor/yoke/src/is_covariant.rs | 142 +++++ vendor/yoke/src/lib.rs | 67 +++ vendor/yoke/src/macro_impls.rs | 109 ++++ vendor/yoke/src/trait_hack.rs | 318 +++++++++++ vendor/yoke/src/yoke.rs | 1142 ++++++++++++++++++++++++++++++++++++++ vendor/yoke/src/yokeable.rs | 325 +++++++++++ vendor/yoke/src/zero_from.rs | 54 ++ 13 files changed, 2447 insertions(+) create mode 100644 vendor/yoke/.cargo-checksum.json create mode 100644 vendor/yoke/Cargo.toml create mode 100644 vendor/yoke/LICENSE create mode 100644 vendor/yoke/README.md create mode 100644 vendor/yoke/src/either.rs create mode 100644 vendor/yoke/src/erased.rs create mode 100644 vendor/yoke/src/is_covariant.rs create mode 100644 vendor/yoke/src/lib.rs create mode 100644 vendor/yoke/src/macro_impls.rs create mode 100644 vendor/yoke/src/trait_hack.rs create mode 100644 vendor/yoke/src/yoke.rs create mode 100644 vendor/yoke/src/yokeable.rs create mode 100644 vendor/yoke/src/zero_from.rs (limited to 'vendor/yoke') diff --git a/vendor/yoke/.cargo-checksum.json b/vendor/yoke/.cargo-checksum.json new file mode 100644 index 000000000..1052beac5 --- /dev/null +++ b/vendor/yoke/.cargo-checksum.json @@ -0,0 +1 @@ +{"files":{"Cargo.toml":"a26eaa79fc44d47a95490b583429bc252338eafe17172ddecc5fed5b90709748","LICENSE":"4ad7541d66a407234e2c84902124cef325c29f3e966353efdb800bedb8b8da21","README.md":"30321954bbc84770e2b50e8cc6da2a9e98f97698cbf1fe829747d4f3c6f6f791","src/either.rs":"028bb043392d1f3d608589d65d997a241b5ba7bb5114cf023179a38bf1c1cf2b","src/erased.rs":"97e545e421f08ae22c6bd8b4d89c9f91876a0b502cc74984dce77f0506decc4d","src/is_covariant.rs":"2d7f92083473be10847b4471917994eee060bf9e31f5d2672ac78cfe64be91b9","src/lib.rs":"5cf0694e0168c8240de935a2187d3f34d2b1ebe03429662df45b5bd97d3226ff","src/macro_impls.rs":"7d626660f4f7a0148710c5b308511604bff1010b813f124ba43ec4e591057981","src/trait_hack.rs":"d3a8b93e0a984febabd288af558d25e5a93019e2bf9209bc023762c9182aa7fc","src/yoke.rs":"8ec18fbbeaf9a87d87a3b5cbc859c49d5929a0bdbf43586d70000294c6dae26f","src/yokeable.rs":"1b2e04f620ab7c06c557d23c44b7ebb67736ae239c44277f4fbefbacc011e549","src/zero_from.rs":"c863d016c1e73bbac25f189c78c544ae65649d20fc9412f385a023d30c9a16f5"},"package":"1fe1d55ca72c32d573bfbd5cb2f0ca65a497854c44762957a6d3da96041a5184"} \ No newline at end of file diff --git a/vendor/yoke/Cargo.toml b/vendor/yoke/Cargo.toml new file mode 100644 index 000000000..d8629127d --- /dev/null +++ b/vendor/yoke/Cargo.toml @@ -0,0 +1,83 @@ +# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO +# +# When uploading crates to the registry Cargo will automatically +# "normalize" Cargo.toml files for maximal compatibility +# with all versions of Cargo and also rewrite `path` dependencies +# to registry (e.g., crates.io) dependencies. +# +# If you are reading this file be aware that the original Cargo.toml +# will likely look very different (and much more reasonable). +# See Cargo.toml.orig for the original contents. + +[package] +edition = "2018" +name = "yoke" +version = "0.6.2" +authors = ["Manish Goregaokar "] +include = [ + "src/**/*", + "examples/**/*", + "benches/**/*", + "Cargo.toml", + "LICENSE", + "README.md", +] +description = "Abstraction allowing borrowed data to be carried along with the backing data it borrows from" +keywords = [ + "zerocopy", + "serialization", + "lifetime", + "borrow", + "self-referential", +] +categories = [ + "data-structures", + "memory-management", + "caching", + "no-std", +] +license = "Unicode-DFS-2016" +repository = "https://github.com/unicode-org/icu4x" +resolver = "2" + +[package.metadata.docs.rs] +all-features = true + +[dependencies.serde] +version = "1.0" +optional = true +default-features = false + +[dependencies.stable_deref_trait] +version = "1.2.0" +default-features = false + +[dependencies.yoke-derive] +version = "0.6.0" +optional = true + +[dependencies.zerofrom] +version = "0.1.0" +optional = true +default-features = false + +[dev-dependencies.bincode] +version = "1.3.3" + +[dev-dependencies.serde] +version = "1.0.125" + +[features] +alloc = [ + "stable_deref_trait/alloc", + "serde/alloc", + "zerofrom/alloc", +] +default = [ + "alloc", + "zerofrom", +] +derive = [ + "yoke-derive", + "zerofrom/derive", +] diff --git a/vendor/yoke/LICENSE b/vendor/yoke/LICENSE new file mode 100644 index 000000000..9858d01ab --- /dev/null +++ b/vendor/yoke/LICENSE @@ -0,0 +1,51 @@ +UNICODE, INC. LICENSE AGREEMENT - DATA FILES AND SOFTWARE + +See Terms of Use +for definitions of Unicode Inc.’s Data Files and Software. + +NOTICE TO USER: Carefully read the following legal agreement. +BY DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING UNICODE INC.'S +DATA FILES ("DATA FILES"), AND/OR SOFTWARE ("SOFTWARE"), +YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE +TERMS AND CONDITIONS OF THIS AGREEMENT. +IF YOU DO NOT AGREE, DO NOT DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE +THE DATA FILES OR SOFTWARE. + +COPYRIGHT AND PERMISSION NOTICE + +Copyright © 1991-2022 Unicode, Inc. All rights reserved. +Distributed under the Terms of Use in https://www.unicode.org/copyright.html. + +Permission is hereby granted, free of charge, to any person obtaining +a copy of the Unicode data files and any associated documentation +(the "Data Files") or Unicode software and any associated documentation +(the "Software") to deal in the Data Files or Software +without restriction, including without limitation the rights to use, +copy, modify, merge, publish, distribute, and/or sell copies of +the Data Files or Software, and to permit persons to whom the Data Files +or Software are furnished to do so, provided that either +(a) this copyright and permission notice appear with all copies +of the Data Files or Software, or +(b) this copyright and permission notice appear in associated +Documentation. + +THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT OF THIRD PARTY RIGHTS. +IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS +NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL +DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, +DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER +TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR +PERFORMANCE OF THE DATA FILES OR SOFTWARE. + +Except as contained in this notice, the name of a copyright holder +shall not be used in advertising or otherwise to promote the sale, +use or other dealings in these Data Files or Software without prior +written authorization of the copyright holder. + +— + +Portions of ICU4X may have been adapted from ICU4C and/or ICU4J. +ICU 1.8.1 to ICU 57.1 © 1995-2016 International Business Machines Corporation and others. diff --git a/vendor/yoke/README.md b/vendor/yoke/README.md new file mode 100644 index 000000000..f7577b8d0 --- /dev/null +++ b/vendor/yoke/README.md @@ -0,0 +1,27 @@ +# yoke [![crates.io](https://img.shields.io/crates/v/yoke)](https://crates.io/crates/yoke) + +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. + +## More Information + +For more information on development, authorship, contributing etc. please visit [`ICU4X home page`](https://github.com/unicode-org/icu4x). diff --git a/vendor/yoke/src/either.rs b/vendor/yoke/src/either.rs new file mode 100644 index 000000000..3706177a2 --- /dev/null +++ b/vendor/yoke/src/either.rs @@ -0,0 +1,87 @@ +// 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 ). + +//! Types to enable polymorphic carts. + +use crate::CloneableCart; + +use core::ops::Deref; +use stable_deref_trait::StableDeref; + +/// A cart that can be one type or the other. Enables ergonomic polymorphic carts. +/// +/// `EitherCart` enables yokes originating from different data sources and therefore +/// having different cart types to be merged into the same yoke type, but still being +/// able to recover the original cart type if necessary. +/// +/// All relevant Cart traits are implemented for `EitherCart`, and carts can be +/// safely wrapped in an `EitherCart`. +/// +/// Also see [`Yoke::erase_box_cart()`](crate::Yoke::erase_box_cart). +/// +/// # Examples +/// +/// ``` +/// use std::borrow::Cow; +/// use std::rc::Rc; +/// use yoke::either::EitherCart; +/// use yoke::Yoke; +/// +/// let y1: Yoke<&'static str, Rc> = +/// Yoke::attach_to_zero_copy_cart("reference counted hello world".into()); +/// +/// let y2: Yoke<&'static str, &str> = Yoke::attach_to_zero_copy_cart("borrowed hello world"); +/// +/// type CombinedYoke<'a> = Yoke<&'static str, EitherCart, &'a str>>; +/// +/// // Both yokes can be combined into a single yoke type despite different carts +/// let y3: CombinedYoke = y1.wrap_cart_in_either_a(); +/// let y4: CombinedYoke = y2.wrap_cart_in_either_b(); +/// +/// assert_eq!(*y3.get(), "reference counted hello world"); +/// assert_eq!(*y4.get(), "borrowed hello world"); +/// +/// // The resulting yoke is cloneable if both cart types implement CloneableCart +/// let y5 = y4.clone(); +/// assert_eq!(*y5.get(), "borrowed hello world"); +/// ``` +#[derive(Clone, PartialEq, Eq)] +#[allow(clippy::exhaustive_enums)] // stable +pub enum EitherCart { + A(C0), + B(C1), +} + +impl Deref for EitherCart +where + C0: Deref, + C1: Deref, +{ + type Target = T; + fn deref(&self) -> &T { + use EitherCart::*; + match self { + A(a) => a.deref(), + B(b) => b.deref(), + } + } +} + +// Safe because both sub-types implement the trait. +unsafe impl StableDeref for EitherCart +where + C0: StableDeref, + C1: StableDeref, + C0: Deref, + C1: Deref, +{ +} + +// Safe because both sub-types implement the trait. +unsafe impl CloneableCart for EitherCart +where + C0: CloneableCart, + C1: CloneableCart, +{ +} diff --git a/vendor/yoke/src/erased.rs b/vendor/yoke/src/erased.rs new file mode 100644 index 000000000..c314d5186 --- /dev/null +++ b/vendor/yoke/src/erased.rs @@ -0,0 +1,41 @@ +// 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 module contains helper types for erasing Cart types. +//! +//! See the docs of [`Yoke::erase_rc_cart()`](crate::Yoke::erase_rc_cart) +//! and [`Yoke::erase_box_cart()`](crate::Yoke::erase_box_cart) for more info. +//! +//! Available with the `"alloc"` feature enabled. + +use alloc::boxed::Box; +use alloc::rc::Rc; +use alloc::sync::Arc; + +/// Dummy trait that lets us `dyn Drop` +/// +/// `dyn Drop` isn't legal (and doesn't make sense since `Drop` is not +/// implement on all destructible types). However, all trait objects come with +/// a destructor, so we can just use an empty trait to get a destructor object. +pub trait ErasedDestructor: 'static {} +impl ErasedDestructor for T {} + +/// A type-erased Cart that has `Arc` semantics +/// +/// See the docs of [`Yoke::erase_arc_cart()`](crate::Yoke::erase_rc_cart) for more info. +/// +/// Available with the `"alloc"` feature enabled. +pub type ErasedArcCart = Arc; +/// A type-erased Cart that has `Rc` semantics +/// +/// See the docs of [`Yoke::erase_rc_cart()`](crate::Yoke::erase_rc_cart) for more info. +/// +/// Available with the `"alloc"` feature enabled. +pub type ErasedRcCart = Rc; +/// A type-erased Cart that has `Box` semantics +/// +/// See the docs of [`Yoke::erase_box_cart()`](crate::Yoke::erase_box_cart) for more info. +/// +/// Available with the `"alloc"` feature enabled. +pub type ErasedBoxCart = Box; diff --git a/vendor/yoke/src/is_covariant.rs b/vendor/yoke/src/is_covariant.rs new file mode 100644 index 000000000..75d123c84 --- /dev/null +++ b/vendor/yoke/src/is_covariant.rs @@ -0,0 +1,142 @@ +// 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 ). + +#[cfg(feature = "alloc")] +use alloc::{ + borrow::{Cow, ToOwned}, + boxed::Box, + rc::Rc, + string::String, +}; + +/// A type implementing `IsCovariant<'a>` is covariant with respect to lifetime `'a`. +/// +/// Lifetime parameters that are safely cast in [`Yokeable`] are also valid for `IsCovariant`. +/// +/// `IsCovariant` exists primarily to serve in trait bounds. The primary use case is to safely +/// perform lifetime casting on trait objects (`dyn Trait`). This enables a type-erased [`Yoke`] +/// consisting of only trait objects. See the examples. +/// +/// `IsCovariant` is auto-implemented in [`#[derive(Yokeable)]`](macro@crate::Yokeable). +/// +/// # Safety +/// +/// This trait is safe to implement on types with a _covariant_ lifetime parameter. This will +/// occur when the lifetime parameter is used within references, but not in the arguments of +/// function pointers or in mutable positions (either in `&mut` or via interior mutability). +/// +/// If a struct has multiple lifetime parameters, only the one used in `IsCovariant<'a>` needs to +/// be covariant. +/// +/// # Examples +/// +/// Implementing on a simple struct with a single covariant lifetime: +/// +/// ``` +/// # use yoke::*; +/// struct MyStruct<'a>(&'a str); +/// +/// // This is safe because 'a is covariant +/// unsafe impl<'a> IsCovariant<'a> for MyStruct<'a> {} +/// ``` +/// +/// By constraining the trait `ExampleTrait<'a>` on `IsCovariant<'a>`, we can safely implement +/// [`Yokeable`] and [`ZeroFrom`] on its trait object: +/// +/// ``` +/// # use yoke::*; +/// # use zerofrom::*; +/// # use core::mem; +/// trait ExampleTrait<'a>: IsCovariant<'a> { +/// fn get_message(&self) -> &'a str; +/// } +/// +/// // This wrapper is required because of the blanket Yokeable impl on &'static T +/// pub struct ExampleTraitDynRef<'a>(pub &'a dyn ExampleTrait<'a>); +/// +/// // The following impl is safe because the trait object requires IsCovariant. +/// unsafe impl<'a> Yokeable<'a> for ExampleTraitDynRef<'static> { +/// type Output = ExampleTraitDynRef<'a>; +/// fn transform(&'a self) -> &'a Self::Output { +/// unsafe { mem::transmute(self) } +/// } +/// +/// fn transform_owned(self) -> Self::Output { +/// unsafe { mem::transmute(self) } +/// } +/// +/// unsafe fn make(from: Self::Output) -> Self { +/// unsafe { mem::transmute(from) } +/// } +/// +/// fn transform_mut(&'a mut self, f: F) +/// where +/// F: 'static + FnOnce(&'a mut Self::Output), +/// { +/// unsafe { f(mem::transmute::<&mut Self, &mut Self::Output>(self)) } +/// } +/// } +/// +/// impl<'zf, 'a> ZeroFrom<'zf, dyn ExampleTrait<'a> + 'a> for ExampleTraitDynRef<'zf> { +/// fn zero_from(this: &'zf (dyn ExampleTrait<'a> + 'a)) -> ExampleTraitDynRef<'zf> { +/// // This is safe because the trait object requires IsCovariant. +/// ExampleTraitDynRef(unsafe { core::mem::transmute(this) }) +/// } +/// } +/// +/// // Implement ExampleTrait on the struct from the previous example +/// # struct MyStruct<'a>(&'a str); +/// # unsafe impl<'a> IsCovariant<'a> for MyStruct<'a> {} +/// impl<'a> ExampleTrait<'a> for MyStruct<'a> { +/// fn get_message(&self) -> &'a str { +/// self.0 +/// } +/// } +/// +/// // Example usage: a Yoke of a trait object +/// let s = "Hello World".to_string(); +/// let yoke: Yoke, Box> = +/// Yoke::attach_to_zero_copy_cart(Box::new(MyStruct(&s))); +/// +/// assert_eq!(yoke.get().0.get_message(), "Hello World"); +/// ``` +/// +/// [`Yoke`]: crate::Yoke +/// [`Yokeable`]: crate::Yokeable +/// [`ZeroFrom`]: crate::ZeroFrom +pub unsafe trait IsCovariant<'a>: 'a {} + +// IsCovariant is implemented on the standard library Copy types in macro_impls.rs + +// The following impls are safe because there is only one lifetime, 'a, and 'a is covariant + +unsafe impl<'a> IsCovariant<'a> for () {} + +unsafe impl<'a> IsCovariant<'a> for str {} +#[cfg(feature = "alloc")] +unsafe impl<'a> IsCovariant<'a> for String {} + +unsafe impl<'a, T: IsCovariant<'a>> IsCovariant<'a> for Option {} + +unsafe impl<'a, T1: IsCovariant<'a>, T2: IsCovariant<'a>> IsCovariant<'a> for (T1, T2) {} + +unsafe impl<'a, T: IsCovariant<'a>> IsCovariant<'a> for [T] {} + +unsafe impl<'a, T: IsCovariant<'a>, const N: usize> IsCovariant<'a> for [T; N] {} + +#[cfg(feature = "alloc")] +unsafe impl<'a, T: IsCovariant<'a> + ?Sized> IsCovariant<'a> for Box {} + +#[cfg(feature = "alloc")] +unsafe impl<'a, T: IsCovariant<'a> + ?Sized> IsCovariant<'a> for Rc {} + +// This is safe because T has a covariant lifetime, and Cow's lifetime is also covariant +#[cfg(feature = "alloc")] +unsafe impl<'a, T: IsCovariant<'a> + ToOwned + ?Sized> IsCovariant<'a> for Cow<'a, T> where + ::Owned: Sized +{ +} + +// This is safe because T has a covariant lifetime, and the reference lifetime is also covariant +unsafe impl<'a, T: IsCovariant<'a> + ?Sized> IsCovariant<'a> for &'a T {} diff --git a/vendor/yoke/src/lib.rs b/vendor/yoke/src/lib.rs new file mode 100644 index 000000000..666e179e9 --- /dev/null +++ b/vendor/yoke/src/lib.rs @@ -0,0 +1,67 @@ +// 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, + // TODO(#2266): enable 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 is_covariant; +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::is_covariant::IsCovariant; +pub use crate::yoke::{CloneableCart, Yoke}; +pub use crate::yokeable::Yokeable; + +#[cfg(feature = "zerofrom")] +use zerofrom::ZeroFrom; diff --git a/vendor/yoke/src/macro_impls.rs b/vendor/yoke/src/macro_impls.rs new file mode 100644 index 000000000..664816818 --- /dev/null +++ b/vendor/yoke/src/macro_impls.rs @@ -0,0 +1,109 @@ +// 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 ). + +// In this case consistency between impls is more important +// than using pointer casts +#![allow(clippy::transmute_ptr_to_ptr)] + +use crate::{IsCovariant, Yokeable}; +use core::{mem, ptr}; + +macro_rules! copy_yoke_impl { + () => { + #[inline] + fn transform(&self) -> &Self::Output { + self + } + #[inline] + fn transform_owned(self) -> Self::Output { + self + } + #[inline] + unsafe fn make(this: Self::Output) -> Self { + this + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + f(self) + } + }; +} +macro_rules! impl_copy_type { + ($ty:ident) => { + unsafe impl<'a> Yokeable<'a> for $ty { + type Output = Self; + copy_yoke_impl!(); + } + unsafe impl<'a> IsCovariant<'a> for $ty {} + }; +} + +impl_copy_type!(u8); +impl_copy_type!(u16); +impl_copy_type!(u32); +impl_copy_type!(u64); +impl_copy_type!(u128); +impl_copy_type!(usize); +impl_copy_type!(i8); +impl_copy_type!(i16); +impl_copy_type!(i32); +impl_copy_type!(i64); +impl_copy_type!(i128); +impl_copy_type!(isize); +impl_copy_type!(char); +impl_copy_type!(bool); + +// This is for when we're implementing Yoke on a complex type such that it's not +// obvious to the compiler that the lifetime is covariant +macro_rules! unsafe_complex_yoke_impl { + () => { + fn transform(&'a self) -> &'a Self::Output { + unsafe { mem::transmute(self) } + } + + fn transform_owned(self) -> Self::Output { + debug_assert!(mem::size_of::() == mem::size_of::()); + unsafe { + let ptr: *const Self::Output = (&self as *const Self).cast(); + mem::forget(self); + ptr::read(ptr) + } + } + + unsafe fn make(from: Self::Output) -> Self { + debug_assert!(mem::size_of::() == mem::size_of::()); + let ptr: *const Self = (&from as *const Self::Output).cast(); + mem::forget(from); + ptr::read(ptr) + } + + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + // Cast away the lifetime of Self + unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } + } + }; +} + +unsafe impl<'a, T: 'static + for<'b> Yokeable<'b>> Yokeable<'a> for Option { + type Output = Option<>::Output>; + unsafe_complex_yoke_impl!(); +} + +unsafe impl<'a, T1: 'static + for<'b> Yokeable<'b>, T2: 'static + for<'b> Yokeable<'b>> Yokeable<'a> + for (T1, T2) +{ + type Output = (>::Output, >::Output); + unsafe_complex_yoke_impl!(); +} + +unsafe impl<'a, T: Yokeable<'a>, const N: usize> Yokeable<'a> for [T; N] { + type Output = [>::Output; N]; + unsafe_complex_yoke_impl!(); +} diff --git a/vendor/yoke/src/trait_hack.rs b/vendor/yoke/src/trait_hack.rs new file mode 100644 index 000000000..7687903f7 --- /dev/null +++ b/vendor/yoke/src/trait_hack.rs @@ -0,0 +1,318 @@ +// 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 ). + +//! Workarounds for adding trait bounds to `yoke` objects. +//! +//! # Trait bounds in Yoke +//! +//! [Compiler bug #89196](https://github.com/rust-lang/rust/issues/89196) makes it tricky to add +//! trait bounds involving `yoke` types. +//! +//! For example, you may want to write: +//! +//! `where for<'a> >::Output: MyTrait` +//! +//! The above trait bound will compile, but at call sites, you get errors such as: +//! +//! > the trait `for<'de> MyTrait` is not implemented for `>::Output` +//! +//! There are two known workarounds: +//! +//! 1. If the trait is well-defined on references, like `Debug`, bind the trait to a reference: +//! `where for<'a> &'a >::Output: MyTrait` +//! 2. If the trait involves `Self`, like `Clone`, use [`YokeTraitHack`]: +//! `where for<'a> YokeTraitHack<>::Output>: MyTrait` +//! +//! # Examples +//! +//! Code that does not compile ([playground](https://play.rust-lang.org/?version=beta&mode=debug&edition=2018&gist=ebbda5b15a398d648bdff9e439b27dc0)): +//! +//! ```compile_fail +//! use yoke::*; +//! +//! trait MiniDataMarker { +//! type Yokeable: for<'a> Yokeable<'a>; +//! } +//! +//! struct MiniDataPayload +//! where +//! M: MiniDataMarker +//! { +//! pub yoke: Yoke, +//! } +//! +//! impl Clone for MiniDataPayload +//! where +//! M: MiniDataMarker, +//! for<'a> >::Output: Clone, +//! { +//! fn clone(&self) -> Self { +//! unimplemented!() +//! } +//! } +//! +//! trait MiniDataProvider +//! where +//! M: MiniDataMarker +//! { +//! fn mini_load_data(&self) -> MiniDataPayload; +//! } +//! +//! struct MiniStructProvider +//! where +//! M: MiniDataMarker, +//! { +//! pub payload: MiniDataPayload, +//! } +//! +//! impl MiniDataProvider for MiniStructProvider +//! where +//! M: MiniDataMarker, +//! for<'a> >::Output: Clone, +//! { +//! fn mini_load_data(&self) -> MiniDataPayload { +//! self.payload.clone() +//! } +//! } +//! +//! #[derive(Clone)] +//! struct SimpleStruct(pub u32); +//! +//! unsafe impl<'a> Yokeable<'a> for SimpleStruct { +//! // (not shown; see `Yokeable` for examples) +//! # type Output = SimpleStruct; +//! # fn transform(&'a self) -> &'a Self::Output { +//! # self +//! # } +//! # fn transform_owned(self) -> Self::Output { +//! # self +//! # } +//! # unsafe fn make(from: Self::Output) -> Self { +//! # std::mem::transmute(from) +//! # } +//! # fn transform_mut(&'a mut self, f: F) +//! # where +//! # F: 'static + for<'b> FnOnce(&'b mut Self::Output), +//! # { +//! # unsafe { +//! # f(std::mem::transmute::<&'a mut Self, &'a mut Self::Output>( +//! # self, +//! # )) +//! # } +//! # } +//! } +//! +//! impl MiniDataMarker for SimpleStruct { +//! type Yokeable = SimpleStruct; +//! } +//! +//! let provider = MiniStructProvider { +//! payload: MiniDataPayload { +//! yoke: Yoke::new_always_owned(SimpleStruct(42)) +//! } +//! }; +//! +//! // Broken: +//! // "method cannot be called on `MiniStructProvider<_>` due to unsatisfied trait bounds" +//! let payload: MiniDataPayload = provider.mini_load_data(); +//! +//! // Working: +//! let payload = MiniDataProvider::::mini_load_data(&provider); +//! +//! assert_eq!(payload.yoke.get().0, 42); +//! ``` +//! +//! Example for binding the trait to a reference: +//! +//! ``` +//! use yoke::Yoke; +//! use yoke::Yokeable; +//! +//! // Example trait and struct for illustration purposes: +//! trait MyTrait { +//! fn demo(&self) -> u32; +//! } +//! struct MyStruct(u32); +//! impl MyTrait for MyStruct { +//! fn demo(&self) -> u32 { +//! self.0 +//! } +//! } +//! unsafe impl<'a> Yokeable<'a> for MyStruct { +//! // (not shown; see `Yokeable` for examples) +//! # type Output = MyStruct; +//! # fn transform(&'a self) -> &'a Self::Output { +//! # self +//! # } +//! # fn transform_owned(self) -> Self::Output { +//! # self +//! # } +//! # unsafe fn make(from: Self::Output) -> Self { +//! # std::mem::transmute(from) +//! # } +//! # fn transform_mut(&'a mut self, f: F) +//! # where +//! # F: 'static + for<'b> FnOnce(&'b mut Self::Output), +//! # { +//! # unsafe { +//! # f(std::mem::transmute::<&'a mut Self, &'a mut Self::Output>( +//! # self, +//! # )) +//! # } +//! # } +//! } +//! +//! // The trait needs to be defined on references: +//! impl<'a, T> MyTrait for &'a T +//! where +//! T: MyTrait, +//! { +//! fn demo(&self) -> u32 { +//! self.demo() +//! } +//! } +//! +//! impl MyTrait for Yoke +//! where +//! Y: for<'a> Yokeable<'a>, +//! for<'a> &'a >::Output: MyTrait, +//! { +//! fn demo(&self) -> u32 { +//! self.get().demo() +//! } +//! } +//! +//! fn example() { +//! let y = Yoke::::new_always_owned(MyStruct(42)); +//! let _: &dyn MyTrait = &y; +//! } +//! ``` +//! +//! Example for using [`YokeTraitHack`]: +//! +//! ``` +//! use std::rc::Rc; +//! use yoke::trait_hack::YokeTraitHack; +//! use yoke::Yoke; +//! use yoke::Yokeable; +//! +//! // Example trait and struct for illustration purposes: +//! trait MyTrait { +//! fn demo(data: u32) -> Self; +//! } +//! struct MyStruct(u32); +//! impl MyTrait for MyStruct { +//! fn demo(data: u32) -> Self { +//! Self(data) +//! } +//! } +//! unsafe impl<'a> Yokeable<'a> for MyStruct { +//! // (not shown; see `Yokeable` for examples) +//! # type Output = MyStruct; +//! # fn transform(&'a self) -> &'a Self::Output { +//! # self +//! # } +//! # fn transform_owned(self) -> Self::Output { +//! # self +//! # } +//! # unsafe fn make(from: Self::Output) -> Self { +//! # std::mem::transmute(from) +//! # } +//! # fn transform_mut(&'a mut self, f: F) +//! # where +//! # F: 'static + for<'b> FnOnce(&'b mut Self::Output), +//! # { +//! # unsafe { +//! # f(std::mem::transmute::<&'a mut Self, &'a mut Self::Output>( +//! # self, +//! # )) +//! # } +//! # } +//! } +//! +//! // The trait needs to be defined on YokeTraitHack: +//! impl<'a, T> MyTrait for YokeTraitHack +//! where +//! T: MyTrait, +//! { +//! fn demo(data: u32) -> Self { +//! YokeTraitHack(T::demo(data)) +//! } +//! } +//! +//! impl MyTrait for Yoke> +//! where +//! Y: for<'a> Yokeable<'a>, +//! for<'a> YokeTraitHack<>::Output>: MyTrait, +//! { +//! fn demo(data: u32) -> Self { +//! let rc_u32: Rc = Rc::new(data); +//! Yoke::attach_to_cart(rc_u32, |u| { +//! YokeTraitHack::<::Output>::demo(*u).0 +//! }) +//! } +//! } +//! +//! fn example() { +//! let _ = Yoke::>::demo(42); +//! } +//! ``` + +use core::mem; + +/// A wrapper around a type `T`, forwarding trait calls down to the inner type. +/// +/// `YokeTraitHack` supports [`Clone`], [`PartialEq`], [`Eq`], and [`serde::Deserialize`] out of +/// the box. Other traits can be implemented by the caller. +/// +/// For more information, see the module-level documentation. +/// +/// # Example +/// +/// Using `YokeTraitHack` as a type bound in a function comparing two `Yoke`s: +/// +/// ``` +/// use yoke::trait_hack::YokeTraitHack; +/// use yoke::*; +/// +/// fn compare_yokes(y1: Yoke, y2: Yoke) -> bool +/// where +/// Y: for<'a> Yokeable<'a>, +/// for<'a> YokeTraitHack<>::Output>: PartialEq, +/// { +/// YokeTraitHack(y1.get()).into_ref() == YokeTraitHack(y2.get()).into_ref() +/// } +/// ``` +#[repr(transparent)] +#[derive(Clone, PartialEq, Eq)] +#[allow(clippy::exhaustive_structs)] // newtype +pub struct YokeTraitHack(pub T); + +impl<'a, T> YokeTraitHack<&'a T> { + /// Converts from `YokeTraitHack<&T>` to `&YokeTraitHack`. + /// + /// This is safe because `YokeTraitHack` is `repr(transparent)`. + /// + /// This method is required to implement `Clone` on `Yoke`. + pub fn into_ref(self) -> &'a YokeTraitHack { + // YokeTraitHack is repr(transparent) so it's always safe + // to transmute YTH<&T> to &YTH + unsafe { mem::transmute::, &YokeTraitHack>(self) } + } +} + +// This is implemented manually to avoid the serde derive dependency. +#[cfg(feature = "serde")] +impl<'de, T> serde::de::Deserialize<'de> for YokeTraitHack +where + T: serde::de::Deserialize<'de>, +{ + #[inline] + fn deserialize(deserializer: D) -> Result + where + D: serde::de::Deserializer<'de>, + { + T::deserialize(deserializer).map(YokeTraitHack) + } +} diff --git a/vendor/yoke/src/yoke.rs b/vendor/yoke/src/yoke.rs new file mode 100644 index 000000000..c3d8c37d9 --- /dev/null +++ b/vendor/yoke/src/yoke.rs @@ -0,0 +1,1142 @@ +// 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 ). + +use crate::either::EitherCart; +#[cfg(feature = "alloc")] +use crate::erased::{ErasedArcCart, ErasedBoxCart, ErasedRcCart}; +use crate::trait_hack::YokeTraitHack; +use crate::IsCovariant; +use crate::Yokeable; +use core::marker::PhantomData; +use core::ops::Deref; +use stable_deref_trait::StableDeref; + +#[cfg(feature = "alloc")] +use alloc::boxed::Box; +#[cfg(feature = "alloc")] +use alloc::rc::Rc; +#[cfg(feature = "alloc")] +use alloc::sync::Arc; + +/// A Cow-like borrowed object "yoked" to its backing data. +/// +/// This allows things like zero copy deserialized data to carry around +/// shared references to their backing buffer, by "erasing" their static lifetime +/// and turning it into a dynamically managed one. +/// +/// `Y` (the [`Yokeable`]) is the object containing the references, +/// and will typically be of the form `Foo<'static>`. The `'static` is +/// not the actual lifetime of the data, rather it is a convenient way to mark the +/// erased lifetime and make it dynamic. +/// +/// `C` is the "cart", which `Y` may contain references to. After the yoke is constructed, +/// the cart serves little purpose except to guarantee that `Y`'s references remain valid +/// for as long as the yoke remains in memory (by calling the destructor at the appropriate moment). +/// +/// The primary constructor for [`Yoke`] is [`Yoke::attach_to_cart()`]. Several variants of that +/// constructor are provided to serve numerous types of call sites and `Yoke` signatures. +/// +/// The key behind this type 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()`. 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. +/// +/// Furthermore, there are various [`.map_project()`][Yoke::map_project] methods that allow turning a `Yoke` +/// into another `Yoke` containing a different type that may contain elements of the original yoked +/// value. See the [`Yoke::map_project()`] docs for more details. +/// +/// In general, `C` is a concrete type, but it is also possible for it to be a trait object; +/// for more information, see [`IsCovariant`]. +/// +/// # Example +/// +/// For example, we can use this to store zero-copy deserialized data in a cache: +/// +/// ```rust +/// # use yoke::{Yoke, Yokeable}; +/// # use std::rc::Rc; +/// # use std::borrow::Cow; +/// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { +/// # // dummy implementation +/// # Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) +/// # } +/// +/// fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { +/// let rc: Rc<[u8]> = load_from_cache(filename); +/// Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { +/// // essentially forcing a #[serde(borrow)] +/// Cow::Borrowed(bincode::deserialize(data).unwrap()) +/// }) +/// } +/// +/// let yoke = load_object("filename.bincode"); +/// assert_eq!(&**yoke.get(), "hello"); +/// assert!(matches!(yoke.get(), &Cow::Borrowed(_))); +/// ``` +pub struct Yoke Yokeable<'a>, C> { + // must be the first field for drop order + // this will have a 'static lifetime parameter, that parameter is a lie + yokeable: Y, + cart: C, +} + +impl Yokeable<'a>, C: StableDeref> Yoke { + /// Construct a [`Yoke`] by yokeing an object to a cart in a closure. + /// + /// See also [`Yoke::try_attach_to_cart()`] to return a `Result` from the closure. + /// + /// Call sites for this function may not compile pre-1.61; if this still happens, use + /// [`Yoke::attach_to_cart_badly()`] and file a bug. + /// + /// # Examples + /// + /// ``` + /// # use yoke::{Yoke, Yokeable}; + /// # use std::rc::Rc; + /// # use std::borrow::Cow; + /// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { + /// # // dummy implementation + /// # Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) + /// # } + /// + /// fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { + /// let rc: Rc<[u8]> = load_from_cache(filename); + /// Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { + /// // essentially forcing a #[serde(borrow)] + /// Cow::Borrowed(bincode::deserialize(data).unwrap()) + /// }) + /// } + /// + /// let yoke: Yoke, _> = load_object("filename.bincode"); + /// assert_eq!(&**yoke.get(), "hello"); + /// assert!(matches!(yoke.get(), &Cow::Borrowed(_))); + /// ``` + pub fn attach_to_cart(cart: C, f: F) -> Self + where + F: for<'de> FnOnce(&'de ::Target) -> >::Output, + { + let deserialized = f(cart.deref()); + Self { + yokeable: unsafe { Y::make(deserialized) }, + cart, + } + } + + /// Construct a [`Yoke`] by yokeing an object to a cart. If an error occurs in the + /// deserializer function, the error is passed up to the caller. + /// + /// Call sites for this function may not compile pre-1.61; if this still happens, use + /// [`Yoke::try_attach_to_cart_badly()`] and file a bug. + pub fn try_attach_to_cart(cart: C, f: F) -> Result + where + F: for<'de> FnOnce(&'de ::Target) -> Result<>::Output, E>, + { + let deserialized = f(cart.deref())?; + Ok(Self { + yokeable: unsafe { Y::make(deserialized) }, + cart, + }) + } + + /// Use [`Yoke::attach_to_cart()`]. + /// + /// This was needed because the pre-1.61 compiler couldn't always handle the FnOnce trait bound. + #[deprecated] + pub fn attach_to_cart_badly( + cart: C, + f: for<'de> fn(&'de ::Target) -> >::Output, + ) -> Self { + Self::attach_to_cart(cart, f) + } + + /// Use [`Yoke::try_attach_to_cart()`]. + /// + /// This was needed because the pre-1.61 compiler couldn't always handle the FnOnce trait bound. + #[deprecated] + pub fn try_attach_to_cart_badly( + cart: C, + f: for<'de> fn(&'de ::Target) -> Result<>::Output, E>, + ) -> Result { + Self::try_attach_to_cart(cart, f) + } +} + +impl Yokeable<'a>, C> Yoke { + /// Obtain a valid reference to the yokeable data + /// + /// This essentially transforms the lifetime of the internal yokeable data to + /// be valid. + /// For example, if you're working with a `Yoke, C>`, this + /// will return an `&'a Cow<'a, T>` + /// + /// # Example + /// + /// ```rust + /// # use yoke::{Yoke, Yokeable}; + /// # use std::rc::Rc; + /// # use std::borrow::Cow; + /// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { + /// # // dummy implementation + /// # Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) + /// # } + /// # + /// # fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { + /// # let rc: Rc<[u8]> = load_from_cache(filename); + /// # Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { + /// # Cow::Borrowed(bincode::deserialize(data).unwrap()) + /// # }) + /// # } + /// + /// // load_object() defined in the example at the top of this page + /// let yoke: Yoke, _> = load_object("filename.bincode"); + /// assert_eq!(yoke.get(), "hello"); + /// ``` + #[inline] + pub fn get<'a>(&'a self) -> &'a >::Output { + self.yokeable.transform() + } + + /// Get a reference to the backing cart. + /// + /// This can be useful when building caches, etc. However, if you plan to store the cart + /// separately from the yoke, read the note of caution below in [`Yoke::into_backing_cart`]. + pub fn backing_cart(&self) -> &C { + &self.cart + } + + /// Get the backing cart by value, dropping the yokeable object. + /// + /// **Caution:** Calling this method could cause information saved in the yokeable object but + /// not the cart to be lost. Use this method only if the yokeable object cannot contain its + /// own information. + /// + /// # Example + /// + /// Good example: the yokeable object is only a reference, so no information can be lost. + /// + /// ``` + /// use yoke::Yoke; + /// + /// let local_data = "foo".to_string(); + /// let yoke = Yoke::<&'static str, Box>::attach_to_zero_copy_cart(Box::new(local_data)); + /// assert_eq!(*yoke.get(), "foo"); + /// + /// // Get back the cart + /// let cart = yoke.into_backing_cart(); + /// assert_eq!(&*cart, "foo"); + /// ``` + /// + /// Bad example: information specified in `.with_mut()` is lost. + /// + /// ``` + /// use std::borrow::Cow; + /// use yoke::Yoke; + /// + /// let local_data = "foo".to_string(); + /// let mut yoke = + /// Yoke::, Box>::attach_to_zero_copy_cart(Box::new(local_data)); + /// assert_eq!(yoke.get(), "foo"); + /// + /// // Override data in the cart + /// yoke.with_mut(|cow| { + /// let mut_str = cow.to_mut(); + /// mut_str.clear(); + /// mut_str.push_str("bar"); + /// }); + /// assert_eq!(yoke.get(), "bar"); + /// + /// // Get back the cart + /// let cart = yoke.into_backing_cart(); + /// assert_eq!(&*cart, "foo"); // WHOOPS! + /// ``` + pub fn into_backing_cart(self) -> C { + self.cart + } + + /// Unsafe function for replacing the cart with another + /// + /// This can be used for type-erasing the cart, for example. + /// + /// # Safety + /// + /// - `f()` must not panic + /// - References from the yokeable `Y` should still be valid for the lifetime of the + /// returned cart type `C`. + /// + /// Typically, this means implementing `f` as something which _wraps_ the inner cart type `C`. + /// `Yoke` only really cares about destructors for its carts so it's fine to erase other + /// information about the cart, as long as the backing data will still be destroyed at the + /// same time. + #[inline] + pub unsafe fn replace_cart(self, f: impl FnOnce(C) -> C2) -> Yoke { + Yoke { + yokeable: self.yokeable, + cart: f(self.cart), + } + } + + /// Mutate the stored [`Yokeable`] data. + /// + /// See [`Yokeable::transform_mut()`] for why this operation is safe. + /// + /// # Example + /// + /// This can be used to partially mutate the stored data, provided + /// no _new_ borrowed data is introduced. + /// + /// ```rust + /// # use yoke::{Yoke, Yokeable}; + /// # use std::rc::Rc; + /// # use std::borrow::Cow; + /// # use std::mem; + /// # fn load_from_cache(_filename: &str) -> Rc<[u8]> { + /// # // dummy implementation + /// # Rc::new([0x5, 0, 0, 0, 0, 0, 0, 0, 0x68, 0x65, 0x6c, 0x6c, 0x6f]) + /// # } + /// # + /// # fn load_object(filename: &str) -> Yoke, Rc<[u8]>> { + /// # let rc: Rc<[u8]> = load_from_cache(filename); + /// # Yoke::, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| { + /// # // A real implementation would properly deserialize `Bar` as a whole + /// # Bar { + /// # numbers: Cow::Borrowed(bincode::deserialize(data).unwrap()), + /// # string: Cow::Borrowed(bincode::deserialize(data).unwrap()), + /// # owned: Vec::new(), + /// # } + /// # }) + /// # } + /// + /// // also implements Yokeable + /// struct Bar<'a> { + /// numbers: Cow<'a, [u8]>, + /// string: Cow<'a, str>, + /// owned: Vec, + /// } + /// + /// // `load_object()` deserializes an object from a file + /// let mut bar: Yoke = load_object("filename.bincode"); + /// assert_eq!(bar.get().string, "hello"); + /// assert!(matches!(bar.get().string, Cow::Borrowed(_))); + /// assert_eq!(&*bar.get().numbers, &[0x68, 0x65, 0x6c, 0x6c, 0x6f]); + /// assert!(matches!(bar.get().numbers, Cow::Borrowed(_))); + /// assert_eq!(&*bar.get().owned, &[]); + /// + /// bar.with_mut(|bar| { + /// bar.string.to_mut().push_str(" world"); + /// bar.owned.extend_from_slice(&[1, 4, 1, 5, 9]); + /// }); + /// + /// assert_eq!(bar.get().string, "hello world"); + /// assert!(matches!(bar.get().string, Cow::Owned(_))); + /// assert_eq!(&*bar.get().owned, &[1, 4, 1, 5, 9]); + /// // Unchanged and still Cow::Borrowed + /// assert_eq!(&*bar.get().numbers, &[0x68, 0x65, 0x6c, 0x6c, 0x6f]); + /// assert!(matches!(bar.get().numbers, Cow::Borrowed(_))); + /// + /// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { + /// # type Output = Bar<'a>; + /// # fn transform(&'a self) -> &'a Bar<'a> { + /// # self + /// # } + /// # + /// # fn transform_owned(self) -> Bar<'a> { + /// # // covariant lifetime cast, can be done safely + /// # self + /// # } + /// # + /// # unsafe fn make(from: Bar<'a>) -> Self { + /// # let ret = mem::transmute_copy(&from); + /// # mem::forget(from); + /// # ret + /// # } + /// # + /// # fn transform_mut(&'a mut self, f: F) + /// # where + /// # F: 'static + FnOnce(&'a mut Self::Output), + /// # { + /// # unsafe { f(mem::transmute(self)) } + /// # } + /// # } + /// ``` + pub fn with_mut<'a, F>(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut >::Output), + { + self.yokeable.transform_mut(f) + } + + /// Helper function allowing one to wrap the cart type `C` in an `Option`. + #[inline] + pub fn wrap_cart_in_option(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(Some) + } + } +} + +impl Yokeable<'a>> Yoke { + /// Construct a new [`Yoke`] from static data. There will be no + /// references to `cart` here since [`Yokeable`]s are `'static`, + /// this is good for e.g. constructing fully owned + /// [`Yoke`]s with no internal borrowing. + /// + /// This is similar to [`Yoke::new_owned()`] but it does not allow you to + /// mix the [`Yoke`] with borrowed data. This is primarily useful + /// for using [`Yoke`] in generic scenarios. + /// + /// # Example + /// + /// ```rust + /// # use yoke::Yoke; + /// # use std::borrow::Cow; + /// # use std::rc::Rc; + /// + /// let owned: Cow = "hello".to_owned().into(); + /// // this yoke can be intermingled with actually-borrowed Yokes + /// let yoke: Yoke, ()> = Yoke::new_always_owned(owned); + /// + /// assert_eq!(yoke.get(), "hello"); + /// ``` + pub fn new_always_owned(yokeable: Y) -> Self { + Self { yokeable, cart: () } + } + + /// Obtain the yokeable out of a `Yoke` + /// + /// For most `Yoke` types this would be unsafe but it's + /// fine for `Yoke` since there are no actual internal + /// references + pub fn into_yokeable(self) -> Y { + self.yokeable + } +} + +impl Yokeable<'a>, C: StableDeref> Yoke> { + /// Construct a new [`Yoke`] from static data. There will be no + /// references to `cart` here since [`Yokeable`]s are `'static`, + /// this is good for e.g. constructing fully owned + /// [`Yoke`]s with no internal borrowing. + /// + /// This can be paired with [`Yoke:: wrap_cart_in_option()`] to mix owned + /// and borrowed data. + /// + /// If you do not wish to pair this with borrowed data, [`Yoke::new_always_owned()`] can + /// be used to get a [`Yoke`] API on always-owned data. + /// + /// # Example + /// + /// ```rust + /// # use yoke::Yoke; + /// # use std::borrow::Cow; + /// # use std::rc::Rc; + /// + /// let owned: Cow = "hello".to_owned().into(); + /// // this yoke can be intermingled with actually-borrowed Yokes + /// let yoke: Yoke, Option>> = Yoke::new_owned(owned); + /// + /// assert_eq!(yoke.get(), "hello"); + /// ``` + pub fn new_owned(yokeable: Y) -> Self { + Self { + yokeable, + cart: None, + } + } + + /// Obtain the yokeable out of a `Yoke>` if possible. + /// + /// If the cart is `None`, this returns `Some`, but if the cart is `Some`, + /// this returns `self` as an error. + pub fn try_into_yokeable(self) -> Result { + match self.cart { + Some(_) => Err(self), + None => Ok(self.yokeable), + } + } +} + +/// This trait marks cart types that do not change source on cloning +/// +/// This is conceptually similar to [`stable_deref_trait::CloneStableDeref`], +/// however [`stable_deref_trait::CloneStableDeref`] is not (and should not) be +/// implemented on [`Option`] (since it's not [`Deref`]). [`CloneableCart`] essentially is +/// "if there _is_ data to borrow from here, cloning the cart gives you an additional +/// handle to the same data". +/// +/// # Safety +/// This trait is safe to implement `StableDeref` types which, once `Clone`d, point to the same underlying data. +/// +/// (This trait is also implemented on `Option` and `()`, which are the two non-`StableDeref` cart types that +/// Yokes can be constructed for) +pub unsafe trait CloneableCart: Clone {} + +#[cfg(feature = "alloc")] +unsafe impl CloneableCart for Rc {} +#[cfg(feature = "alloc")] +unsafe impl CloneableCart for Arc {} +unsafe impl CloneableCart for Option {} +unsafe impl<'a, T: ?Sized> CloneableCart for &'a T {} +unsafe impl CloneableCart for () {} + +/// Clone requires that the cart type `C` derefs to the same address after it is cloned. This works for +/// Rc, Arc, and &'a T. +/// +/// For other cart types, clone `.backing_cart()` and re-use `.attach_to_cart()`; however, doing +/// so may lose mutations performed via `.with_mut()`. +/// +/// Cloning a `Yoke` is often a cheap operation requiring no heap allocations, in much the same +/// way that cloning an `Rc` is a cheap operation. However, if the `yokeable` contains owned data +/// (e.g., from `.with_mut()`), that data will need to be cloned. +impl Yokeable<'a>, C: CloneableCart> Clone for Yoke +where + for<'a> YokeTraitHack<>::Output>: Clone, +{ + fn clone(&self) -> Self { + let this: &Y::Output = self.get(); + // We have an &T not a T, and we can clone YokeTraitHack + let this_hack = YokeTraitHack(this).into_ref(); + Yoke { + yokeable: unsafe { Y::make(this_hack.clone().0) }, + cart: self.cart.clone(), + } + } +} + +// This is safe because Y is 'static and C has a covariant lifetime +unsafe impl<'b, Y: for<'a> Yokeable<'a>, C: IsCovariant<'b>> IsCovariant<'b> for Yoke {} + +#[test] +fn test_clone() { + let local_data = "foo".to_string(); + let y1 = Yoke::, Rc>::attach_to_zero_copy_cart( + Rc::new(local_data), + ); + + // Test basic clone + let y2 = y1.clone(); + assert_eq!(y1.get(), "foo"); + assert_eq!(y2.get(), "foo"); + + // Test clone with mutation on target + let mut y3 = y1.clone(); + y3.with_mut(|y| { + y.to_mut().push_str("bar"); + }); + assert_eq!(y1.get(), "foo"); + assert_eq!(y2.get(), "foo"); + assert_eq!(y3.get(), "foobar"); + + // Test that mutations on source do not affect target + let y4 = y3.clone(); + y3.with_mut(|y| { + y.to_mut().push_str("baz"); + }); + assert_eq!(y1.get(), "foo"); + assert_eq!(y2.get(), "foo"); + assert_eq!(y3.get(), "foobarbaz"); + assert_eq!(y4.get(), "foobar"); +} + +impl Yokeable<'a>, C> Yoke { + /// Allows one to "project" a yoke to perform a transformation on the data, potentially + /// looking at a subfield, and producing a new yoke. This will move cart, and the provided + /// transformation is only allowed to use data known to be borrowed from the cart. + /// + /// The callback takes an additional `PhantomData<&()>` parameter to anchor lifetimes + /// (see [#86702](https://github.com/rust-lang/rust/issues/86702)) This parameter + /// should just be ignored in the callback. + /// + /// This can be used, for example, to transform data from one format to another: + /// + /// ``` + /// # use std::rc::Rc; + /// # use yoke::Yoke; + /// # + /// fn slice(y: Yoke<&'static str, Rc<[u8]>>) -> Yoke<&'static [u8], Rc<[u8]>> { + /// y.map_project(move |yk, _| yk.as_bytes()) + /// } + /// ``` + /// + /// This can also be used to create a yoke for a subfield + /// + /// ``` + /// # use std::borrow::Cow; + /// # use yoke::{Yoke, Yokeable}; + /// # use std::mem; + /// # use std::rc::Rc; + /// # + /// // also safely implements Yokeable<'a> + /// struct Bar<'a> { + /// string_1: &'a str, + /// string_2: &'a str, + /// } + /// + /// fn map_project_string_1(bar: Yoke, Rc<[u8]>>) -> Yoke<&'static str, Rc<[u8]>> { + /// bar.map_project(|bar, _| bar.string_1) + /// } + /// + /// # + /// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { + /// # type Output = Bar<'a>; + /// # fn transform(&'a self) -> &'a Bar<'a> { + /// # self + /// # } + /// # + /// # fn transform_owned(self) -> Bar<'a> { + /// # // covariant lifetime cast, can be done safely + /// # self + /// # } + /// # + /// # unsafe fn make(from: Bar<'a>) -> Self { + /// # let ret = mem::transmute_copy(&from); + /// # mem::forget(from); + /// # ret + /// # } + /// # + /// # fn transform_mut(&'a mut self, f: F) + /// # where + /// # F: 'static + FnOnce(&'a mut Self::Output), + /// # { + /// # unsafe { f(mem::transmute(self)) } + /// # } + /// # } + /// ``` + // + // Safety docs can be found below on `__project_safety_docs()` + pub fn map_project(self, f: F) -> Yoke + where + P: for<'a> Yokeable<'a>, + F: for<'a> FnOnce( + >::Output, + PhantomData<&'a ()>, + ) ->

>::Output, + { + let p = f(self.yokeable.transform_owned(), PhantomData); + Yoke { + yokeable: unsafe { P::make(p) }, + cart: self.cart, + } + } + + /// This is similar to [`Yoke::map_project`], however it does not move + /// [`Self`] and instead clones the cart (only if the cart is a [`CloneableCart`]) + /// + /// This is a bit more efficient than cloning the [`Yoke`] and then calling [`Yoke::map_project`] + /// because then it will not clone fields that are going to be discarded. + pub fn map_project_cloned<'this, P, F>(&'this self, f: F) -> Yoke + where + P: for<'a> Yokeable<'a>, + C: CloneableCart, + F: for<'a> FnOnce( + &'this >::Output, + PhantomData<&'a ()>, + ) ->

>::Output, + { + let p = f(self.get(), PhantomData); + Yoke { + yokeable: unsafe { P::make(p) }, + cart: self.cart.clone(), + } + } + + /// This is similar to [`Yoke::map_project`], however it can also bubble up an error + /// from the callback. + /// + /// ``` + /// # use std::rc::Rc; + /// # use yoke::Yoke; + /// # use std::str::{self, Utf8Error}; + /// # + /// fn slice(y: Yoke<&'static [u8], Rc<[u8]>>) -> Result>, Utf8Error> { + /// y.try_map_project(move |bytes, _| str::from_utf8(bytes)) + /// } + /// ``` + /// + /// This can also be used to create a yoke for a subfield + /// + /// ``` + /// # use std::borrow::Cow; + /// # use yoke::{Yoke, Yokeable}; + /// # use std::mem; + /// # use std::rc::Rc; + /// # use std::str::{self, Utf8Error}; + /// # + /// // also safely implements Yokeable<'a> + /// struct Bar<'a> { + /// bytes_1: &'a [u8], + /// string_2: &'a str, + /// } + /// + /// fn map_project_string_1(bar: Yoke, Rc<[u8]>>) -> Result>, Utf8Error> { + /// bar.try_map_project(|bar, _| str::from_utf8(bar.bytes_1)) + /// } + /// + /// # + /// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { + /// # type Output = Bar<'a>; + /// # fn transform(&'a self) -> &'a Bar<'a> { + /// # self + /// # } + /// # + /// # fn transform_owned(self) -> Bar<'a> { + /// # // covariant lifetime cast, can be done safely + /// # self + /// # } + /// # + /// # unsafe fn make(from: Bar<'a>) -> Self { + /// # let ret = mem::transmute_copy(&from); + /// # mem::forget(from); + /// # ret + /// # } + /// # + /// # fn transform_mut(&'a mut self, f: F) + /// # where + /// # F: 'static + FnOnce(&'a mut Self::Output), + /// # { + /// # unsafe { f(mem::transmute(self)) } + /// # } + /// # } + /// ``` + pub fn try_map_project(self, f: F) -> Result, E> + where + P: for<'a> Yokeable<'a>, + F: for<'a> FnOnce( + >::Output, + PhantomData<&'a ()>, + ) -> Result<

>::Output, E>, + { + let p = f(self.yokeable.transform_owned(), PhantomData)?; + Ok(Yoke { + yokeable: unsafe { P::make(p) }, + cart: self.cart, + }) + } + + /// This is similar to [`Yoke::try_map_project`], however it does not move + /// [`Self`] and instead clones the cart (only if the cart is a [`CloneableCart`]) + /// + /// This is a bit more efficient than cloning the [`Yoke`] and then calling [`Yoke::map_project`] + /// because then it will not clone fields that are going to be discarded. + pub fn try_map_project_cloned<'this, P, F, E>(&'this self, f: F) -> Result, E> + where + P: for<'a> Yokeable<'a>, + C: CloneableCart, + F: for<'a> FnOnce( + &'this >::Output, + PhantomData<&'a ()>, + ) -> Result<

>::Output, E>, + { + let p = f(self.get(), PhantomData)?; + Ok(Yoke { + yokeable: unsafe { P::make(p) }, + cart: self.cart.clone(), + }) + } + /// This is similar to [`Yoke::map_project`], but it works around older versions + /// of Rust not being able to use `FnOnce` by using an explicit capture input. + /// See [#1061](https://github.com/unicode-org/icu4x/issues/1061). + /// + /// See the docs of [`Yoke::map_project`] for how this works. + pub fn map_project_with_explicit_capture( + self, + capture: T, + f: for<'a> fn( + >::Output, + capture: T, + PhantomData<&'a ()>, + ) ->

>::Output, + ) -> Yoke + where + P: for<'a> Yokeable<'a>, + { + let p = f(self.yokeable.transform_owned(), capture, PhantomData); + Yoke { + yokeable: unsafe { P::make(p) }, + cart: self.cart, + } + } + + /// This is similar to [`Yoke::map_project_cloned`], but it works around older versions + /// of Rust not being able to use `FnOnce` by using an explicit capture input. + /// See [#1061](https://github.com/unicode-org/icu4x/issues/1061). + /// + /// See the docs of [`Yoke::map_project_cloned`] for how this works. + pub fn map_project_cloned_with_explicit_capture<'this, P, T>( + &'this self, + capture: T, + f: for<'a> fn( + &'this >::Output, + capture: T, + PhantomData<&'a ()>, + ) ->

>::Output, + ) -> Yoke + where + P: for<'a> Yokeable<'a>, + C: CloneableCart, + { + let p = f(self.get(), capture, PhantomData); + Yoke { + yokeable: unsafe { P::make(p) }, + cart: self.cart.clone(), + } + } + + /// This is similar to [`Yoke::try_map_project`], but it works around older versions + /// of Rust not being able to use `FnOnce` by using an explicit capture input. + /// See [#1061](https://github.com/unicode-org/icu4x/issues/1061). + /// + /// See the docs of [`Yoke::try_map_project`] for how this works. + #[allow(clippy::type_complexity)] + pub fn try_map_project_with_explicit_capture( + self, + capture: T, + f: for<'a> fn( + >::Output, + capture: T, + PhantomData<&'a ()>, + ) -> Result<

>::Output, E>, + ) -> Result, E> + where + P: for<'a> Yokeable<'a>, + { + let p = f(self.yokeable.transform_owned(), capture, PhantomData)?; + Ok(Yoke { + yokeable: unsafe { P::make(p) }, + cart: self.cart, + }) + } + + /// This is similar to [`Yoke::try_map_project_cloned`], but it works around older versions + /// of Rust not being able to use `FnOnce` by using an explicit capture input. + /// See [#1061](https://github.com/unicode-org/icu4x/issues/1061). + /// + /// See the docs of [`Yoke::try_map_project_cloned`] for how this works. + #[allow(clippy::type_complexity)] + pub fn try_map_project_cloned_with_explicit_capture<'this, P, T, E>( + &'this self, + capture: T, + f: for<'a> fn( + &'this >::Output, + capture: T, + PhantomData<&'a ()>, + ) -> Result<

>::Output, E>, + ) -> Result, E> + where + P: for<'a> Yokeable<'a>, + C: CloneableCart, + { + let p = f(self.get(), capture, PhantomData)?; + Ok(Yoke { + yokeable: unsafe { P::make(p) }, + cart: self.cart.clone(), + }) + } +} + +#[cfg(feature = "alloc")] +impl Yokeable<'a>, C: 'static + Sized> Yoke> { + /// Allows type-erasing the cart in a `Yoke>`. + /// + /// The yoke only carries around a cart type `C` for its destructor, + /// since it needs to be able to guarantee that its internal references + /// are valid for the lifetime of the Yoke. As such, the actual type of the + /// Cart is not very useful unless you wish to extract data out of it + /// via [`Yoke::backing_cart()`]. Erasing the cart allows for one to mix + /// [`Yoke`]s obtained from different sources. + /// + /// In case the cart type `C` is not already an `Rc`, you can use + /// [`Yoke::wrap_cart_in_rc()`] to wrap it. + /// + /// # Example + /// + /// ```rust + /// use std::rc::Rc; + /// use yoke::erased::ErasedRcCart; + /// use yoke::Yoke; + /// + /// let buffer1: Rc = Rc::new(" foo bar baz ".into()); + /// let buffer2: Box = Box::new(" baz quux ".into()); + /// + /// let yoke1 = Yoke::<&'static str, _>::attach_to_cart(buffer1, |rc| rc.trim()); + /// let yoke2 = Yoke::<&'static str, _>::attach_to_cart(buffer2, |b| b.trim()); + /// + /// let erased1: Yoke<_, ErasedRcCart> = yoke1.erase_rc_cart(); + /// // Wrap the Box in an Rc to make it compatible + /// let erased2: Yoke<_, ErasedRcCart> = yoke2.wrap_cart_in_rc().erase_rc_cart(); + /// + /// // Now erased1 and erased2 have the same type! + /// ``` + /// + /// Available with the `"alloc"` feature enabled. + pub fn erase_rc_cart(self) -> Yoke { + unsafe { + // safe because the cart is preserved, just + // type-erased + self.replace_cart(|c| c as ErasedRcCart) + } + } +} + +#[cfg(feature = "alloc")] +impl Yokeable<'a>, C: 'static + Sized + Send + Sync> Yoke> { + /// Allows type-erasing the cart in a `Yoke>`. + /// + /// The yoke only carries around a cart type `C` for its destructor, + /// since it needs to be able to guarantee that its internal references + /// are valid for the lifetime of the Yoke. As such, the actual type of the + /// Cart is not very useful unless you wish to extract data out of it + /// via [`Yoke::backing_cart()`]. Erasing the cart allows for one to mix + /// [`Yoke`]s obtained from different sources. + /// + /// In case the cart type `C` is not already an `Arc`, you can use + /// [`Yoke::wrap_cart_in_arc()`] to wrap it. + /// + /// # Example + /// + /// ```rust + /// use std::sync::Arc; + /// use yoke::erased::ErasedArcCart; + /// use yoke::Yoke; + /// + /// let buffer1: Arc = Arc::new(" foo bar baz ".into()); + /// let buffer2: Box = Box::new(" baz quux ".into()); + /// + /// let yoke1 = Yoke::<&'static str, _>::attach_to_cart(buffer1, |arc| arc.trim()); + /// let yoke2 = Yoke::<&'static str, _>::attach_to_cart(buffer2, |b| b.trim()); + /// + /// let erased1: Yoke<_, ErasedArcCart> = yoke1.erase_arc_cart(); + /// // Wrap the Box in an Rc to make it compatible + /// let erased2: Yoke<_, ErasedArcCart> = yoke2.wrap_cart_in_arc().erase_arc_cart(); + /// + /// // Now erased1 and erased2 have the same type! + /// ``` + /// + /// Available with the `"alloc"` feature enabled. + pub fn erase_arc_cart(self) -> Yoke { + unsafe { + // safe because the cart is preserved, just + // type-erased + self.replace_cart(|c| c as ErasedArcCart) + } + } +} + +#[cfg(feature = "alloc")] +impl Yokeable<'a>, C: 'static + Sized> Yoke> { + /// Allows type-erasing the cart in a `Yoke>`. + /// + /// The yoke only carries around a cart type `C` for its destructor, + /// since it needs to be able to guarantee that its internal references + /// are valid for the lifetime of the Yoke. As such, the actual type of the + /// Cart is not very useful unless you wish to extract data out of it + /// via [`Yoke::backing_cart()`]. Erasing the cart allows for one to mix + /// [`Yoke`]s obtained from different sources. + /// + /// In case the cart type `C` is not already `Box`, you can use + /// [`Yoke::wrap_cart_in_box()`] to wrap it. + /// + /// # Example + /// + /// ```rust + /// use std::rc::Rc; + /// use yoke::erased::ErasedBoxCart; + /// use yoke::Yoke; + /// + /// let buffer1: Rc = Rc::new(" foo bar baz ".into()); + /// let buffer2: Box = Box::new(" baz quux ".into()); + /// + /// let yoke1 = Yoke::<&'static str, _>::attach_to_cart(buffer1, |rc| rc.trim()); + /// let yoke2 = Yoke::<&'static str, _>::attach_to_cart(buffer2, |b| b.trim()); + /// + /// // Wrap the Rc in an Box to make it compatible + /// let erased1: Yoke<_, ErasedBoxCart> = yoke1.wrap_cart_in_box().erase_box_cart(); + /// let erased2: Yoke<_, ErasedBoxCart> = yoke2.erase_box_cart(); + /// + /// // Now erased1 and erased2 have the same type! + /// ``` + /// + /// Available with the `"alloc"` feature enabled. + pub fn erase_box_cart(self) -> Yoke { + unsafe { + // safe because the cart is preserved, just + // type-erased + self.replace_cart(|c| c as ErasedBoxCart) + } + } +} + +#[cfg(feature = "alloc")] +impl Yokeable<'a>, C> Yoke { + /// Helper function allowing one to wrap the cart type `C` in a `Box`. + /// Can be paired with [`Yoke::erase_box_cart()`] + /// + /// Available with the `"alloc"` feature enabled. + #[inline] + pub fn wrap_cart_in_box(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(Box::new) + } + } + /// Helper function allowing one to wrap the cart type `C` in an `Rc`. + /// Can be paired with [`Yoke::erase_rc_cart()`], or generally used + /// to make the [`Yoke`] cloneable. + /// + /// Available with the `"alloc"` feature enabled. + #[inline] + pub fn wrap_cart_in_rc(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(Rc::new) + } + } + /// Helper function allowing one to wrap the cart type `C` in an `Rc`. + /// Can be paired with [`Yoke::erase_arc_cart()`], or generally used + /// to make the [`Yoke`] cloneable. + /// + /// Available with the `"alloc"` feature enabled. + #[inline] + pub fn wrap_cart_in_arc(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(Arc::new) + } + } +} + +impl Yokeable<'a>, C> Yoke { + /// Helper function allowing one to wrap the cart type `C` in an [`EitherCart`]. + /// + /// This function wraps the cart into the `A` variant. To wrap it into the + /// `B` variant, use [`Self::wrap_cart_in_either_b()`]. + /// + /// For an example, see [`EitherCart`]. + #[inline] + pub fn wrap_cart_in_either_a(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(EitherCart::A) + } + } + /// Helper function allowing one to wrap the cart type `C` in an [`EitherCart`]. + /// + /// This function wraps the cart into the `B` variant. To wrap it into the + /// `A` variant, use [`Self::wrap_cart_in_either_a()`]. + /// + /// For an example, see [`EitherCart`]. + #[inline] + pub fn wrap_cart_in_either_b(self) -> Yoke> { + unsafe { + // safe because the cart is preserved, just wrapped + self.replace_cart(EitherCart::B) + } + } +} + +/// Safety docs for project() +/// +/// (Docs are on a private const to allow the use of compile_fail doctests) +/// +/// This is safe to perform because of the choice of lifetimes on `f`, that is, +/// `for fn(>::Output, &'a ()) ->

>::Output`. +/// +/// What we want this function to do is take a Yokeable (`Y`) that is borrowing from the cart, and +/// produce another Yokeable (`P`) that also borrows from the same cart. There are a couple potential +/// hazards here: +/// +/// - `P` ends up borrowing data from `Y` (or elsewhere) that did _not_ come from the cart, +/// for example `P` could borrow owned data from a `Cow`. This would make the `Yoke

` dependent +/// on data owned only by the `Yoke`. +/// - Borrowed data from `Y` escapes with the wrong lifetime +/// +/// Let's walk through these and see how they're prevented. +/// +/// ```rust, compile_fail +/// # use std::rc::Rc; +/// # use yoke::Yoke; +/// # use std::borrow::Cow; +/// fn borrow_potentially_owned(y: &Yoke, Rc<[u8]>>) -> Yoke<&'static str, Rc<[u8]>> { +/// y.map_project_cloned(|cow, _| &*cow) +/// } +/// ``` +/// +/// In this case, the lifetime of `&*cow` is `&'this str`, however the function needs to be able to return +/// `&'a str` _for all `'a`_, which isn't possible. +/// +/// +/// ```rust, compile_fail +/// # use std::rc::Rc; +/// # use yoke::Yoke; +/// # use std::borrow::Cow; +/// fn borrow_potentially_owned(y: Yoke, Rc<[u8]>>) -> Yoke<&'static str, Rc<[u8]>> { +/// y.map_project(|cow, _| &*cow) +/// } +/// ``` +/// +/// This has the same issue, `&*cow` is borrowing for a local lifetime. +/// +/// Similarly, trying to project an owned field of a struct will produce similar errors: +/// +/// ```rust,compile_fail +/// # use std::borrow::Cow; +/// # use yoke::{Yoke, Yokeable}; +/// # use std::mem; +/// # use std::rc::Rc; +/// # +/// // also safely implements Yokeable<'a> +/// struct Bar<'a> { +/// owned: String, +/// string_2: &'a str, +/// } +/// +/// fn map_project_owned(bar: &Yoke, Rc<[u8]>>) -> Yoke<&'static str, Rc<[u8]>> { +/// // ERROR (but works if you replace owned with string_2) +/// bar.map_project_cloned(|bar, _| &*bar.owned) +/// } +/// +/// # +/// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { +/// # type Output = Bar<'a>; +/// # fn transform(&'a self) -> &'a Bar<'a> { +/// # self +/// # } +/// # +/// # fn transform_owned(self) -> Bar<'a> { +/// # // covariant lifetime cast, can be done safely +/// # self +/// # } +/// # +/// # unsafe fn make(from: Bar<'a>) -> Self { +/// # let ret = mem::transmute_copy(&from); +/// # mem::forget(from); +/// # ret +/// # } +/// # +/// # fn transform_mut(&'a mut self, f: F) +/// # where +/// # F: 'static + FnOnce(&'a mut Self::Output), +/// # { +/// # unsafe { f(mem::transmute(self)) } +/// # } +/// # } +/// ``` +/// +/// Borrowed data from `Y` similarly cannot escape with the wrong lifetime because of the `for<'a>`, since +/// it will never be valid for the borrowed data to escape for all lifetimes of 'a. Internally, `.project()` +/// uses `.get()`, however the signature forces the callers to be able to handle every lifetime. +/// +/// `'a` is the only lifetime that matters here; `Yokeable`s must be `'static` and since +/// `Output` is an associated type it can only have one lifetime, `'a` (there's nowhere for it to get another from). +/// `Yoke`s can get additional lifetimes via the cart, and indeed, `project()` can operate on `Yoke<_, &'b [u8]>`, +/// however this lifetime is inaccessible to the closure, and even if it were accessible the `for<'a>` would force +/// it out of the output. All external lifetimes (from other found outside the yoke/closures +/// are similarly constrained here. +/// +/// Essentially, safety is achieved by using `for<'a> fn(...)` with `'a` used in both `Yokeable`s to ensure that +/// the output yokeable can _only_ have borrowed data flow in to it from the input. All paths of unsoundness require the +/// unification of an existential and universal lifetime, which isn't possible. +const _: () = (); diff --git a/vendor/yoke/src/yokeable.rs b/vendor/yoke/src/yokeable.rs new file mode 100644 index 000000000..73e81aa7b --- /dev/null +++ b/vendor/yoke/src/yokeable.rs @@ -0,0 +1,325 @@ +// 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 ). + +#[cfg(feature = "alloc")] +use alloc::borrow::{Cow, ToOwned}; +use core::mem; + +/// 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. ` as Yokeable<'a>'>::Output` is `Cow<'a, T>`. +/// +/// A [`Yokeable`] type is essentially one with a covariant lifetime parameter, +/// matched to the parameter in the trait definition. The trait allows one to cast +/// the covariant lifetime to and from `'static`. +/// +/// **Most of the time, if you need to implement [`Yokeable`], you should be able to use the safe +/// [`#[derive(Yokeable)]`](yoke_derive::Yokeable) custom derive.** +/// +/// While Rust does not yet have GAT syntax, for the purpose of this documentation +/// we shall refer to "`Self` with a lifetime `'a`" with the syntax `Self<'a>`. +/// Self<'static> is a stand-in for the HKT Self<'_>: lifetime -> type. +/// +/// With this terminology, [`Yokeable`] exposes ways to cast between `Self<'static>` and `Self<'a>` generically. +/// This is useful for turning covariant lifetimes to _dynamic_ lifetimes, where `'static` is +/// used as a way to "erase" the lifetime. +/// +/// # Safety +/// +/// This trait is safe to implement on types with a _covariant_ lifetime parameter, i.e. one where +/// [`Self::transform()`]'s body can simply be `{ self }`. This will occur when the lifetime +/// parameter is used within references, but not in the arguments of function pointers or in mutable +/// positions (either in `&mut` or via interior mutability) +/// +/// This trait must be implemented on the `'static` version of such a type, e.g. one should +/// implement `Yokeable<'a>` (for all `'a`) on `Cow<'static, T>`. +/// +/// There are further constraints on implementation safety on individual methods. +/// +/// # Trait bounds +/// +/// [Compiler bug #85636](https://github.com/rust-lang/rust/issues/85636) makes it tricky to add +/// trait bounds on `Yokeable::Output`. For more information and for workarounds, see +/// [`crate::trait_hack`]. +/// +/// # Implementation example +/// +/// Implementing this trait manually is unsafe. Where possible, you should use the safe +/// [`#[derive(Yokeable)]`](yoke_derive::Yokeable) custom derive instead. We include an example +/// in case you have your own zero-copy abstractions you wish to make yokeable. +/// +/// ```rust +/// # use yoke::Yokeable; +/// # use std::borrow::Cow; +/// # use std::{mem, ptr}; +/// struct Bar<'a> { +/// numbers: Cow<'a, [u8]>, +/// string: Cow<'a, str>, +/// owned: Vec, +/// } +/// +/// unsafe impl<'a> Yokeable<'a> for Bar<'static> { +/// type Output = Bar<'a>; +/// fn transform(&'a self) -> &'a Bar<'a> { +/// // covariant lifetime cast, can be done safely +/// self +/// } +/// +/// fn transform_owned(self) -> Bar<'a> { +/// // covariant lifetime cast, can be done safely +/// self +/// } +/// +/// unsafe fn make(from: Bar<'a>) -> Self { +/// // We're just doing mem::transmute() here, however Rust is +/// // not smart enough to realize that Bar<'a> and Bar<'static> are of +/// // the same size, so instead we use transmute_copy +/// +/// // This assert will be optimized out, but is included for additional +/// // peace of mind as we are using transmute_copy +/// debug_assert!(mem::size_of::>() == mem::size_of::()); +/// let ptr: *const Self = (&from as *const Self::Output).cast(); +/// mem::forget(from); +/// ptr::read(ptr) +/// } +/// +/// fn transform_mut(&'a mut self, f: F) +/// where +/// F: 'static + FnOnce(&'a mut Self::Output), +/// { +/// unsafe { f(mem::transmute::<&mut Self, &mut Self::Output>(self)) } +/// } +/// } +/// ``` +pub unsafe trait Yokeable<'a>: 'static { + /// This type MUST be `Self` with the `'static` replaced with `'a`, i.e. `Self<'a>` + type Output: 'a; + + /// This method must cast `self` between `&'a Self<'static>` and `&'a Self<'a>`. + /// + /// # Implementation safety + /// + /// If the invariants of [`Yokeable`] are being satisfied, the body of this method + /// should simply be `{ self }`, though it's acceptable to include additional assertions + /// if desired. + fn transform(&'a self) -> &'a Self::Output; + + /// This method must cast `self` between `Self<'static>` and `Self<'a>`. + /// + /// # Implementation safety + /// + /// If the invariants of [`Yokeable`] are being satisfied, the body of this method + /// should simply be `{ self }`, though it's acceptable to include additional assertions + /// if desired. + fn transform_owned(self) -> Self::Output; + + /// This method can be used to cast away `Self<'a>`'s lifetime. + /// + /// # Safety + /// + /// The returned value must be destroyed before the data `from` was borrowing from is. + /// + /// # Implementation safety + /// + /// A safe implementation of this method must be equivalent to a transmute between + /// `Self<'a>` and `Self<'static>` + unsafe fn make(from: Self::Output) -> Self; + + /// This method must cast `self` between `&'a mut Self<'static>` and `&'a mut Self<'a>`, + /// and pass it to `f`. + /// + /// # Implementation safety + /// + /// A safe implementation of this method must be equivalent to a pointer cast/transmute between + /// `&mut Self<'a>` and `&mut Self<'static>` being passed to `f` + /// + /// # Why is this safe? + /// + /// Typically covariant lifetimes become invariant when hidden behind an `&mut`, + /// which is why the implementation of this method cannot just be `f(self)`. + /// The reason behind this is that while _reading_ a covariant lifetime that has been cast to a shorter + /// one is always safe (this is roughly the definition of a covariant lifetime), writing + /// may not necessarily be safe since you could write a smaller reference to it. For example, + /// the following code is unsound because it manages to stuff a `'a` lifetime into a `Cow<'static>` + /// + /// ```rust,compile_fail + /// # use std::borrow::Cow; + /// # use yoke::Yokeable; + /// struct Foo { + /// str: String, + /// cow: Cow<'static, str>, + /// } + /// + /// fn unsound<'a>(foo: &'a mut Foo) { + /// let a: &str = &foo.str; + /// foo.cow.transform_mut(|cow| *cow = Cow::Borrowed(a)); + /// } + /// ``` + /// + /// However, this code will not compile because [`Yokeable::transform_mut()`] requires `F: 'static`. + /// This enforces that while `F` may mutate `Self<'a>`, it can only mutate it in a way that does + /// not insert additional references. For example, `F` may call `to_owned()` on a `Cow` and mutate it, + /// but it cannot insert a new _borrowed_ reference because it has nowhere to borrow _from_ -- + /// `f` does not contain any borrowed references, and while we give it `Self<'a>` (which contains borrowed + /// data), that borrowed data is known to be valid + /// + /// Note that the `for<'b>` is also necessary, otherwise the following code would compile: + /// + /// ```rust,compile_fail + /// # use std::borrow::Cow; + /// # use yoke::Yokeable; + /// # use std::mem; + /// # + /// // also safely implements Yokeable<'a> + /// struct Bar<'a> { + /// num: u8, + /// cow: Cow<'a, u8>, + /// } + /// + /// fn unsound<'a>(bar: &'a mut Bar<'static>) { + /// bar.transform_mut(move |bar| bar.cow = Cow::Borrowed(&bar.num)); + /// } + /// # + /// # unsafe impl<'a> Yokeable<'a> for Bar<'static> { + /// # type Output = Bar<'a>; + /// # fn transform(&'a self) -> &'a Bar<'a> { + /// # self + /// # } + /// # + /// # fn transform_owned(self) -> Bar<'a> { + /// # // covariant lifetime cast, can be done safely + /// # self + /// # } + /// # + /// # unsafe fn make(from: Bar<'a>) -> Self { + /// # let ret = mem::transmute_copy(&from); + /// # mem::forget(from); + /// # ret + /// # } + /// # + /// # fn transform_mut(&'a mut self, f: F) + /// # where + /// # F: 'static + FnOnce(&'a mut Self::Output), + /// # { + /// # unsafe { f(mem::transmute(self)) } + /// # } + /// # } + /// ``` + /// + /// which is unsound because `bar` could be moved later, and we do not want to be able to + /// self-insert references to it. + /// + /// The `for<'b>` enforces this by stopping the author of the closure from matching up the input + /// `&'b Self::Output` lifetime with `'a` and borrowing directly from it. + /// + /// Thus the only types of mutations allowed are ones that move around already-borrowed data, or + /// introduce new owned data: + /// + /// ```rust + /// # use std::borrow::Cow; + /// # use yoke::Yokeable; + /// struct Foo { + /// str: String, + /// cow: Cow<'static, str>, + /// } + /// + /// fn sound<'a>(foo: &'a mut Foo) { + /// foo.cow.transform_mut(move |cow| cow.to_mut().push('a')); + /// } + /// ``` + fn transform_mut(&'a mut self, f: F) + where + // be VERY CAREFUL changing this signature, it is very nuanced (see above) + F: 'static + for<'b> FnOnce(&'b mut Self::Output); +} + +#[cfg(feature = "alloc")] +unsafe impl<'a, T: 'static + ToOwned + ?Sized> Yokeable<'a> for Cow<'static, T> +where + ::Owned: Sized, +{ + type Output = Cow<'a, T>; + #[inline] + fn transform(&'a self) -> &'a Cow<'a, T> { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + fn transform_owned(self) -> Cow<'a, T> { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + unsafe fn make(from: Cow<'a, T>) -> Self { + // i hate this + // unfortunately Rust doesn't think `mem::transmute` is possible since it's not sure the sizes + // are the same + debug_assert!(mem::size_of::>() == mem::size_of::()); + let ptr: *const Self = (&from as *const Self::Output).cast(); + mem::forget(from); + core::ptr::read(ptr) + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + // Cast away the lifetime of Self + unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } + } +} + +unsafe impl<'a, T: 'static + ?Sized> Yokeable<'a> for &'static T { + type Output = &'a T; + #[inline] + fn transform(&'a self) -> &'a &'a T { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + fn transform_owned(self) -> &'a T { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + unsafe fn make(from: &'a T) -> Self { + mem::transmute(from) + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + // Cast away the lifetime of Self + unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) } + } +} + +#[cfg(feature = "alloc")] +unsafe impl<'a, T: 'static> Yokeable<'a> for alloc::vec::Vec { + type Output = alloc::vec::Vec; + #[inline] + fn transform(&'a self) -> &'a alloc::vec::Vec { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + fn transform_owned(self) -> alloc::vec::Vec { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + self + } + #[inline] + unsafe fn make(from: alloc::vec::Vec) -> Self { + from + } + #[inline] + fn transform_mut(&'a mut self, f: F) + where + F: 'static + for<'b> FnOnce(&'b mut Self::Output), + { + // Doesn't need unsafe: `'a` is covariant so this lifetime cast is always safe + f(self) + } +} diff --git a/vendor/yoke/src/zero_from.rs b/vendor/yoke/src/zero_from.rs new file mode 100644 index 000000000..679a28d59 --- /dev/null +++ b/vendor/yoke/src/zero_from.rs @@ -0,0 +1,54 @@ +// 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 ). + +use crate::trait_hack::YokeTraitHack; +use crate::Yoke; +use crate::Yokeable; + +use core::ops::Deref; +use stable_deref_trait::StableDeref; + +use crate::ZeroFrom; + +impl<'zf, C: ?Sized, T> ZeroFrom<'zf, C> for YokeTraitHack +where + T: ZeroFrom<'zf, C>, +{ + #[inline] + fn zero_from(cart: &'zf C) -> Self { + YokeTraitHack(T::zero_from(cart)) + } +} + +impl Yoke +where + Y: for<'a> Yokeable<'a>, + for<'a> YokeTraitHack<>::Output>: ZeroFrom<'a, ::Target>, + C: StableDeref + Deref, +{ + /// Construct a [`Yoke`]`` from a cart implementing `StableDeref` by zero-copy cloning + /// the cart to `Y` and then yokeing that object to the cart. + /// + /// The type `Y` must implement [`ZeroFrom`]``. This trait is auto-implemented + /// on many common types and can be custom implemented or derived in order to make it easier + /// to construct a `Yoke`. + /// + /// # Example + /// + /// Attach to a cart: + /// + /// ``` + /// use std::borrow::Cow; + /// use yoke::Yoke; + /// + /// let yoke = Yoke::, String>::attach_to_zero_copy_cart("demo".to_string()); + /// + /// assert_eq!("demo", yoke.get()); + /// ``` + pub fn attach_to_zero_copy_cart(cart: C) -> Self { + Yoke::::attach_to_cart(cart, |c| { + YokeTraitHack::<::Output>::zero_from(c).0 + }) + } +} -- cgit v1.2.3