Import 'yoke' crate
Request Document: go/android-rust-importing-crates
For CL Reviewers: go/android3p#cl-review
Bug: 391960687
Test: m yoke
Change-Id: Ia8ab6d65911abe702f737ee81a4f8e0731e7fbe6
diff --git a/crates/yoke/.android-checksum.json b/crates/yoke/.android-checksum.json
new file mode 100644
index 0000000..faed540
--- /dev/null
+++ b/crates/yoke/.android-checksum.json
@@ -0,0 +1 @@
+{"package":null,"files":{".cargo-checksum.json":"dfcbeb1a7eed0ff6f6e9edf6ec0f4eefb9467d64c239e5eb9a0ba96cda87c753","Android.bp":"a3d6e557197675e83dd4764d2ee1c56b20b5e1636987adffd85a68813dd373f1","Cargo.toml":"ab4c8cb44220d0a526478d73837eb9426c3c3a768e42decda730f859c3add4db","LICENSE":"dc5bf54a256c44c7030f620e2b6abca67aa66635f54789432989d96836c552b9","METADATA":"25fe4b6e9c0c93bb86ce15107245fb326f410c262d77c93e2f854055aafd2a5c","README.md":"d77955268c53928a7c925b4b8696be251fb74fd75784af1deb2ab43c64e28992","cargo_embargo.json":"3f3fff68ba3c3779fc27c4aa4fd830e3ec2ac27391279c1c46daab73031fe751","src/cartable_ptr.rs":"1e0b10bcaa77ced90e199abc1d731274f6dd1dfa85e6987f40a9ccfe63f69130","src/either.rs":"fdb8a686a37ebc4c3a3f4fd6a3b7e1ed61da01f97fd77fc3efe056fbc089f128","src/erased.rs":"610e62f5e995ffc6defa8f7c8e314b6b1d10b41234ad4b3eb2fb6c3ad83fef27","src/kinda_sorta_dangling.rs":"0aeb77cbb0e712a1d27a14d64bbd5d9925d60661e79706315e5181e4297b248d","src/lib.rs":"ee09d0de88bd096b37c9028f646738949a78e05ec263209091d897a6b744f0d3","src/macro_impls.rs":"8268c82be4efb49bf3757b0071bb081d59f2bad1a518524e2775776911b49f87","src/trait_hack.rs":"bee6cf50ea7be58fa9e7ccddb49ee75c318c36faf0e836a96d9394f371a7f3fb","src/yoke.rs":"36255a55be687ac2f6062d6f2fbb91ed45491785541e36c18ae6ffb52645a9fe","src/yokeable.rs":"dae3013154f6d067c751cbe43fa086e459faea0a269080f5f6c3245ef94f5305","src/zero_from.rs":"349964ad6c4b7f9454578e8ffcf1e568d21215d9433f1c1e55c19eac76446dae","tests/bincode.rs":"580acf567817c8c856bd54c13ae1eb5517f2bde0a8eb10de632df458a4efbcd0","tests/miri.rs":"220f60903e466ff5d1c8bb3977e05aa35c005f8ae0903d7b543cb58b90fd6aaf"}}
\ No newline at end of file
diff --git a/crates/yoke/.cargo-checksum.json b/crates/yoke/.cargo-checksum.json
new file mode 100644
index 0000000..2ecb6fe
--- /dev/null
+++ b/crates/yoke/.cargo-checksum.json
@@ -0,0 +1 @@
+{"files":{"Cargo.toml":"5fe994dba8c562338478434041520cd9fd15f538641c50701f781a4f9577a38c","LICENSE":"f367c1b8e1aa262435251e442901da4607b4650e0e63a026f5044473ecfb90f2","README.md":"7caeea392483abdb034071f43cd056c7a69940b77a0e65ad7f37f4657107d4a3","src/cartable_ptr.rs":"04082c417fe8a4a92e25f975d25155d18723991e01a5fd4afcbd60a0dcf60743","src/either.rs":"cd08d6b6583a843ea8df5221f673dd0b2e3bb7925ab881eed257be13c64e51aa","src/erased.rs":"ebd156e832b5e67c599c6938cfbe85cd11a6088818a6981f56911cffb49e0a5f","src/kinda_sorta_dangling.rs":"caff4ee5ef690e6f6c4101d7b6c7005ce8a10e6e0c13b07914e937801d5e9ab3","src/lib.rs":"6bd3e6dad6d1bc689fdf72f097cf5b7c055833876b5a4de768d9470b9387795d","src/macro_impls.rs":"e116abc4eed9a6ddfe0c553f5d83de3382de954b21ef1c35020f0a40bc012a31","src/trait_hack.rs":"41a13aedf403cec70c0daefc2487ca9f60bd7f04b17e9d9be5fcfb6838123a25","src/yoke.rs":"19bab08779b2d2e7b44b23113cf09835f7e96712f2fed545617d14c85325c9f0","src/yokeable.rs":"01ed31e194d2dd3cca4216cdee8b601edcdf7ce78f528b760ffb682c379e1c19","src/zero_from.rs":"71d97f87e003db0eb0e97064509bdf9355622ccd655549f926b6a0d9119db3ee","tests/bincode.rs":"869d4601d829c64d2dcd046134455a72be448de639d0b2e61baa9cfc4e114050","tests/miri.rs":"fd119cfbf1abc39463e3be5145966962853d1f6771826c003449a06b3e8acbea"},"package":"120e6aef9aa629e3d4f52dc8cc43a015c7724194c97dfaf45180d2daf2b77f40"}
\ No newline at end of file
diff --git a/crates/yoke/Android.bp b/crates/yoke/Android.bp
new file mode 100644
index 0000000..7ce8ba6
--- /dev/null
+++ b/crates/yoke/Android.bp
@@ -0,0 +1,35 @@
+// This file is generated by cargo_embargo.
+// Do not modify this file because the changes will be overridden on upgrade.
+
+package {
+ default_applicable_licenses: ["external_rust_crates_yoke_license"],
+ default_team: "trendy_team_android_rust",
+}
+
+license {
+ name: "external_rust_crates_yoke_license",
+ visibility: [":__subpackages__"],
+ license_kinds: ["SPDX-license-identifier-Unicode-3.0"],
+ license_text: ["LICENSE"],
+}
+
+rust_library {
+ name: "libyoke",
+ host_supported: true,
+ crate_name: "yoke",
+ cargo_env_compat: true,
+ cargo_pkg_version: "0.7.5",
+ crate_root: "src/lib.rs",
+ edition: "2021",
+ features: ["serde"],
+ rustlibs: [
+ "libserde",
+ "libstable_deref_trait",
+ ],
+ apex_available: [
+ "//apex_available:platform",
+ "//apex_available:anyapex",
+ ],
+ product_available: true,
+ vendor_available: true,
+}
diff --git a/crates/yoke/Cargo.toml b/crates/yoke/Cargo.toml
new file mode 100644
index 0000000..011f630
--- /dev/null
+++ b/crates/yoke/Cargo.toml
@@ -0,0 +1,117 @@
+# 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 = "2021"
+rust-version = "1.71.1"
+name = "yoke"
+version = "0.7.5"
+authors = ["Manish Goregaokar <manishsmail@gmail.com>"]
+build = false
+include = [
+ "data/**/*",
+ "src/**/*",
+ "examples/**/*",
+ "benches/**/*",
+ "tests/**/*",
+ "Cargo.toml",
+ "LICENSE",
+ "README.md",
+]
+autobins = false
+autoexamples = false
+autotests = false
+autobenches = false
+description = "Abstraction allowing borrowed data to be carried along with the backing data it borrows from"
+readme = "README.md"
+keywords = [
+ "zerocopy",
+ "serialization",
+ "lifetime",
+ "borrow",
+ "self-referential",
+]
+categories = [
+ "data-structures",
+ "memory-management",
+ "caching",
+ "no-std",
+]
+license = "Unicode-3.0"
+repository = "https://github.com/unicode-org/icu4x"
+
+[package.metadata.cargo-all-features]
+max_combination_size = 3
+
+[package.metadata.docs.rs]
+all-features = true
+
+[package.metadata.workspaces]
+independent = true
+
+[lib]
+name = "yoke"
+path = "src/lib.rs"
+
+[[test]]
+name = "bincode"
+path = "tests/bincode.rs"
+
+[[test]]
+name = "miri"
+path = "tests/miri.rs"
+
+[dependencies.serde]
+version = "1.0.110"
+optional = true
+default-features = false
+
+[dependencies.stable_deref_trait]
+version = "1.2.0"
+default-features = false
+
+[dependencies.yoke-derive]
+version = "0.7.5"
+optional = true
+default-features = false
+
+[dependencies.zerofrom]
+version = "0.1.3"
+optional = true
+default-features = false
+
+[dev-dependencies.bincode]
+version = "1.3.1"
+
+[dev-dependencies.postcard]
+version = "1.0.1"
+default-features = false
+
+[dev-dependencies.serde]
+version = "1.0.110"
+default-features = false
+
+[features]
+alloc = [
+ "stable_deref_trait/alloc",
+ "serde?/alloc",
+ "zerofrom/alloc",
+]
+default = [
+ "alloc",
+ "zerofrom",
+]
+derive = [
+ "dep:yoke-derive",
+ "zerofrom/derive",
+]
+serde = ["dep:serde"]
+zerofrom = ["dep:zerofrom"]
diff --git a/crates/yoke/LICENSE b/crates/yoke/LICENSE
new file mode 100644
index 0000000..c9be601
--- /dev/null
+++ b/crates/yoke/LICENSE
@@ -0,0 +1,46 @@
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 2020-2024 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+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.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+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.
+
+SPDX-License-Identifier: Unicode-3.0
+
+—
+
+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/crates/yoke/METADATA b/crates/yoke/METADATA
new file mode 100644
index 0000000..3737476
--- /dev/null
+++ b/crates/yoke/METADATA
@@ -0,0 +1,17 @@
+name: "yoke"
+description: "Abstraction allowing borrowed data to be carried along with the backing data it borrows from"
+third_party {
+ version: "0.7.5"
+ license_type: NOTICE
+ last_upgrade_date {
+ year: 2025
+ month: 1
+ day: 24
+ }
+ homepage: "https://crates.io/crates/yoke"
+ identifier {
+ type: "Archive"
+ value: "https://static.crates.io/crates/yoke/yoke-0.7.5.crate"
+ version: "0.7.5"
+ }
+}
diff --git a/crates/yoke/README.md b/crates/yoke/README.md
new file mode 100644
index 0000000..23c1ac8
--- /dev/null
+++ b/crates/yoke/README.md
@@ -0,0 +1,31 @@
+# yoke [](https://crates.io/crates/yoke)
+
+<!-- cargo-rdme start -->
+
+This crate provides [`Yoke<Y, C>`][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<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`](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<T>`](alloc::boxed::Box), [`Rc<T>`](alloc::rc::Rc), or [`Arc<T>`](std::sync::Arc), potentially wrapped in an [`Option<T>`](Option).
+
+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()`](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.
+
+<!-- cargo-rdme end -->
+
+## More Information
+
+For more information on development, authorship, contributing etc. please visit [`ICU4X home page`](https://github.com/unicode-org/icu4x).
diff --git a/crates/yoke/cargo_embargo.json b/crates/yoke/cargo_embargo.json
new file mode 100644
index 0000000..e94ded6
--- /dev/null
+++ b/crates/yoke/cargo_embargo.json
@@ -0,0 +1,3 @@
+{
+ "features": ["serde"]
+}
\ No newline at end of file
diff --git a/crates/yoke/src/cartable_ptr.rs b/crates/yoke/src/cartable_ptr.rs
new file mode 100644
index 0000000..24bf6d3
--- /dev/null
+++ b/crates/yoke/src/cartable_ptr.rs
@@ -0,0 +1,445 @@
+// 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 for optional pointers with niche optimization.
+//!
+//! The main type is [`CartableOptionPointer`], which is like `Option<Rc>` but
+//! with a niche so that the resulting `Yoke` has a niche. The following four
+//! types can be stored in the `CartableOptionPointer`:
+//!
+//! 1. `&T`
+//! 2. `Box<T>`
+//! 3. `Rc<T>`
+//! 4. `Arc<T>`
+//!
+//! These four types implement the sealed unsafe trait [`CartablePointerLike`].
+//! In addition, all except `Box<T>` impl [`CloneableCartablePointerLike`],
+//! which allows [`CartableOptionPointer`] to implement `Clone`.
+
+use crate::CloneableCart;
+#[cfg(feature = "alloc")]
+use alloc::boxed::Box;
+#[cfg(feature = "alloc")]
+use alloc::rc::Rc;
+#[cfg(feature = "alloc")]
+use alloc::sync::Arc;
+#[cfg(test)]
+use core::cell::Cell;
+use core::marker::PhantomData;
+use core::ptr::NonNull;
+use stable_deref_trait::StableDeref;
+
+// Safety note: this method MUST return the same value for the same T, even if i.e. the method gets
+// instantiated in different crates. This can be untrue in surprising ways! For example, just
+// returning a const-ref-to-const would not guarantee that.
+// The current implementation always returns the same address for any T, see
+// [the reference](https://doc.rust-lang.org/reference/items/static-items.html#statics--generics):
+// there is exactly one `SENTINEL` item for any T.
+#[inline]
+fn sentinel_for<T>() -> NonNull<T> {
+ static SENTINEL: &u8 = &0x1a; // SUB
+
+ // Safety: SENTINEL is indeed not a null pointer, even after the casts.
+ unsafe { NonNull::new_unchecked(SENTINEL as *const u8 as *mut T) }
+}
+
+#[cfg(test)]
+thread_local! {
+ static DROP_INVOCATIONS: Cell<usize> = const { Cell::new(0) };
+}
+
+mod private {
+ pub trait Sealed {}
+}
+
+use private::Sealed;
+
+/// An object fully representable by a non-null pointer.
+///
+/// # Safety
+///
+/// Implementer safety:
+///
+/// 1. `into_raw` transfers ownership of the values referenced by StableDeref to the caller,
+/// if there is ownership to transfer
+/// 2. `drop_raw` returns ownership back to the impl, if there is ownership to transfer
+///
+/// Note: if `into_raw` returns the sentinel pointer, memory leaks may occur, but this will not
+/// lead to undefined behaviour.
+///
+/// Note: the pointer `NonNull<Self::Raw>` may or may not be aligned and it should never
+/// be dereferenced. Rust allows unaligned pointers; see [`std::ptr::read_unaligned`].
+pub unsafe trait CartablePointerLike: StableDeref + Sealed {
+ /// The raw type used for [`Self::into_raw`] and [`Self::drop_raw`].
+ #[doc(hidden)]
+ type Raw;
+
+ /// Converts this pointer-like into a pointer.
+ #[doc(hidden)]
+ fn into_raw(self) -> NonNull<Self::Raw>;
+
+ /// Drops any memory associated with this pointer-like.
+ ///
+ /// # Safety
+ ///
+ /// Caller safety:
+ ///
+ /// 1. The pointer MUST have been returned by this impl's `into_raw`.
+ /// 2. The pointer MUST NOT be dangling.
+ #[doc(hidden)]
+ unsafe fn drop_raw(pointer: NonNull<Self::Raw>);
+}
+
+/// An object that implements [`CartablePointerLike`] that also
+/// supports cloning without changing the address of referenced data.
+///
+/// # Safety
+///
+/// Implementer safety:
+///
+/// 1. `addref_raw` must create a new owner such that an additional call to
+/// `drop_raw` does not create a dangling pointer
+/// 2. `addref_raw` must not change the address of any referenced data.
+pub unsafe trait CloneableCartablePointerLike: CartablePointerLike {
+ /// Clones this pointer-like.
+ ///
+ /// # Safety
+ ///
+ /// Caller safety:
+ ///
+ /// 1. The pointer MUST have been returned by this impl's `into_raw`.
+ /// 2. The pointer MUST NOT be dangling.
+ #[doc(hidden)]
+ unsafe fn addref_raw(pointer: NonNull<Self::Raw>);
+}
+
+impl<'a, T> Sealed for &'a T {}
+
+// Safety:
+// 1. There is no ownership to transfer
+// 2. There is no ownership to transfer
+unsafe impl<'a, T> CartablePointerLike for &'a T {
+ type Raw = T;
+
+ #[inline]
+ fn into_raw(self) -> NonNull<T> {
+ self.into()
+ }
+ #[inline]
+ unsafe fn drop_raw(_pointer: NonNull<T>) {
+ // No-op: references are borrowed from elsewhere
+ }
+}
+
+// Safety:
+// 1. There is no ownership
+// 2. The impl is a no-op so no addresses are changed.
+unsafe impl<'a, T> CloneableCartablePointerLike for &'a T {
+ #[inline]
+ unsafe fn addref_raw(_pointer: NonNull<T>) {
+ // No-op: references are borrowed from elsewhere
+ }
+}
+
+#[cfg(feature = "alloc")]
+impl<T> Sealed for Box<T> {}
+
+#[cfg(feature = "alloc")]
+// Safety:
+// 1. `Box::into_raw` says: "After calling this function, the caller is responsible for the
+// memory previously managed by the Box."
+// 2. `Box::from_raw` says: "After calling this function, the raw pointer is owned by the
+// resulting Box."
+unsafe impl<T> CartablePointerLike for Box<T> {
+ type Raw = T;
+
+ #[inline]
+ fn into_raw(self) -> NonNull<T> {
+ // Safety: `Box::into_raw` says: "The pointer will be properly aligned and non-null."
+ unsafe { NonNull::new_unchecked(Box::into_raw(self)) }
+ }
+ #[inline]
+ unsafe fn drop_raw(pointer: NonNull<T>) {
+ // Safety: per the method's precondition, `pointer` is dereferenceable and was returned by
+ // `Self::into_raw`, i.e. by `Box::into_raw`. In this circumstances, calling
+ // `Box::from_raw` is safe.
+ let _box = unsafe { Box::from_raw(pointer.as_ptr()) };
+
+ // Boxes are always dropped
+ #[cfg(test)]
+ DROP_INVOCATIONS.with(|x| x.set(x.get() + 1))
+ }
+}
+
+#[cfg(feature = "alloc")]
+impl<T> Sealed for Rc<T> {}
+
+#[cfg(feature = "alloc")]
+// Safety:
+// 1. `Rc::into_raw` says: "Consumes the Rc, returning the wrapped pointer. To avoid a memory
+// leak the pointer must be converted back to an Rc using Rc::from_raw."
+// 2. See 1.
+unsafe impl<T> CartablePointerLike for Rc<T> {
+ type Raw = T;
+
+ #[inline]
+ fn into_raw(self) -> NonNull<T> {
+ // Safety: Rcs must contain data (and not be null)
+ unsafe { NonNull::new_unchecked(Rc::into_raw(self) as *mut T) }
+ }
+
+ #[inline]
+ unsafe fn drop_raw(pointer: NonNull<T>) {
+ // Safety: per the method's precondition, `pointer` is dereferenceable and was returned by
+ // `Self::into_raw`, i.e. by `Rc::into_raw`. In this circumstances, calling
+ // `Rc::from_raw` is safe.
+ let _rc = unsafe { Rc::from_raw(pointer.as_ptr()) };
+
+ // Rc is dropped if refcount is 1
+ #[cfg(test)]
+ if Rc::strong_count(&_rc) == 1 {
+ DROP_INVOCATIONS.with(|x| x.set(x.get() + 1))
+ }
+ }
+}
+
+#[cfg(feature = "alloc")]
+// Safety:
+// 1. The impl increases the refcount such that `Drop` will decrease it.
+// 2. The impl increases refcount without changing the address of data.
+unsafe impl<T> CloneableCartablePointerLike for Rc<T> {
+ #[inline]
+ unsafe fn addref_raw(pointer: NonNull<T>) {
+ // Safety: The caller safety of this function says that:
+ // 1. The pointer was obtained through Rc::into_raw
+ // 2. The associated Rc instance is valid
+ // Further, this impl is not defined for anything but the global allocator.
+ unsafe {
+ Rc::increment_strong_count(pointer.as_ptr());
+ }
+ }
+}
+
+#[cfg(feature = "alloc")]
+impl<T> Sealed for Arc<T> {}
+
+#[cfg(feature = "alloc")]
+// Safety:
+// 1. `Rc::into_raw` says: "Consumes the Arc, returning the wrapped pointer. To avoid a memory
+// leak the pointer must be converted back to an Arc using Arc::from_raw."
+// 2. See 1.
+unsafe impl<T> CartablePointerLike for Arc<T> {
+ type Raw = T;
+
+ #[inline]
+ fn into_raw(self) -> NonNull<T> {
+ // Safety: Arcs must contain data (and not be null)
+ unsafe { NonNull::new_unchecked(Arc::into_raw(self) as *mut T) }
+ }
+ #[inline]
+ unsafe fn drop_raw(pointer: NonNull<T>) {
+ // Safety: per the method's precondition, `pointer` is dereferenceable and was returned by
+ // `Self::into_raw`, i.e. by `Rc::into_raw`. In this circumstances, calling
+ // `Rc::from_raw` is safe.
+ let _arc = unsafe { Arc::from_raw(pointer.as_ptr()) };
+
+ // Arc is dropped if refcount is 1
+ #[cfg(test)]
+ if Arc::strong_count(&_arc) == 1 {
+ DROP_INVOCATIONS.with(|x| x.set(x.get() + 1))
+ }
+ }
+}
+
+#[cfg(feature = "alloc")]
+// Safety:
+// 1. The impl increases the refcount such that `Drop` will decrease it.
+// 2. The impl increases refcount without changing the address of data.
+unsafe impl<T> CloneableCartablePointerLike for Arc<T> {
+ #[inline]
+ unsafe fn addref_raw(pointer: NonNull<T>) {
+ // Safety: The caller safety of this function says that:
+ // 1. The pointer was obtained through Arc::into_raw
+ // 2. The associated Arc instance is valid
+ // Further, this impl is not defined for anything but the global allocator.
+ unsafe {
+ Arc::increment_strong_count(pointer.as_ptr());
+ }
+ }
+}
+
+/// A type with similar semantics as `Option<C<T>>` but with a niche.
+///
+/// This type cannot be publicly constructed. To use this in a `Yoke`, see
+/// [`Yoke::convert_cart_into_option_pointer`].
+///
+/// [`Yoke::convert_cart_into_option_pointer`]: crate::Yoke::convert_cart_into_option_pointer
+#[derive(Debug)]
+pub struct CartableOptionPointer<C>
+where
+ C: CartablePointerLike,
+{
+ /// The inner pointer.
+ ///
+ /// # Invariants
+ ///
+ /// 1. Must be either `SENTINEL_PTR` or created from `CartablePointerLike::into_raw`
+ /// 2. If non-sentinel, must _always_ be for a valid SelectedRc
+ inner: NonNull<C::Raw>,
+ _cartable: PhantomData<C>,
+}
+
+impl<C> CartableOptionPointer<C>
+where
+ C: CartablePointerLike,
+{
+ /// Creates a new instance corresponding to a `None` value.
+ #[inline]
+ pub(crate) fn none() -> Self {
+ Self {
+ inner: sentinel_for::<C::Raw>(),
+ _cartable: PhantomData,
+ }
+ }
+
+ /// Creates a new instance corresponding to a `Some` value.
+ #[inline]
+ pub(crate) fn from_cartable(cartable: C) -> Self {
+ let inner = cartable.into_raw();
+ debug_assert_ne!(inner, sentinel_for::<C::Raw>());
+ Self {
+ inner,
+ _cartable: PhantomData,
+ }
+ }
+
+ /// Returns whether this instance is `None`. From the return value:
+ ///
+ /// - If `true`, the instance is `None`
+ /// - If `false`, the instance is a valid `SelectedRc`
+ #[inline]
+ pub fn is_none(&self) -> bool {
+ self.inner == sentinel_for::<C::Raw>()
+ }
+}
+
+impl<C> Drop for CartableOptionPointer<C>
+where
+ C: CartablePointerLike,
+{
+ #[inline]
+ fn drop(&mut self) {
+ let ptr = self.inner;
+ if ptr != sentinel_for::<C::Raw>() {
+ // By the invariants, `ptr` is a valid raw value since it's
+ // either that or sentinel, and we just checked for sentinel.
+ // We will replace it with the sentinel and then drop `ptr`.
+ self.inner = sentinel_for::<C::Raw>();
+ // Safety: by the invariants, `ptr` is a valid raw value.
+ unsafe { C::drop_raw(ptr) }
+ }
+ }
+}
+
+impl<C> Clone for CartableOptionPointer<C>
+where
+ C: CloneableCartablePointerLike,
+{
+ #[inline]
+ fn clone(&self) -> Self {
+ let ptr = self.inner;
+ if ptr != sentinel_for::<C::Raw>() {
+ // By the invariants, `ptr` is a valid raw value since it's
+ // either that or sentinel, and we just checked for sentinel.
+ // Safety: by the invariants, `ptr` is a valid raw value.
+ unsafe { C::addref_raw(ptr) }
+ }
+ Self {
+ inner: self.inner,
+ _cartable: PhantomData,
+ }
+ }
+}
+
+// Safety: logically an Option<C>. Has same bounds as Option<C>.
+// The `StableDeref` parts of `C` continue to be `StableDeref`.
+unsafe impl<C> CloneableCart for CartableOptionPointer<C> where
+ C: CloneableCartablePointerLike + CloneableCart
+{
+}
+
+// Safety: logically an Option<C>. Has same bounds as Option<C>
+unsafe impl<C> Send for CartableOptionPointer<C> where C: Sync + CartablePointerLike {}
+
+// Safety: logically an Option<C>. Has same bounds as Option<C>
+unsafe impl<C> Sync for CartableOptionPointer<C> where C: Send + CartablePointerLike {}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use crate::Yoke;
+ use core::mem::size_of;
+
+ const SAMPLE_BYTES: &[u8] = b"abCDEfg";
+ const W: usize = size_of::<usize>();
+
+ #[test]
+ fn test_sizes() {
+ assert_eq!(W * 4, size_of::<Yoke<[usize; 3], &&[u8]>>());
+ assert_eq!(W * 4, size_of::<Yoke<[usize; 3], Option<&&[u8]>>>());
+ assert_eq!(
+ W * 4,
+ size_of::<Yoke<[usize; 3], CartableOptionPointer<&&[u8]>>>()
+ );
+
+ assert_eq!(W * 4, size_of::<Option<Yoke<[usize; 3], &&[u8]>>>());
+ assert_eq!(W * 5, size_of::<Option<Yoke<[usize; 3], Option<&&[u8]>>>>());
+ assert_eq!(
+ W * 4,
+ size_of::<Option<Yoke<[usize; 3], CartableOptionPointer<&&[u8]>>>>()
+ );
+ }
+
+ #[test]
+ fn test_new_sentinel() {
+ let start = DROP_INVOCATIONS.with(Cell::get);
+ {
+ let _ = CartableOptionPointer::<Rc<&[u8]>>::none();
+ }
+ assert_eq!(start, DROP_INVOCATIONS.with(Cell::get));
+ {
+ let _ = CartableOptionPointer::<Rc<&[u8]>>::none();
+ }
+ assert_eq!(start, DROP_INVOCATIONS.with(Cell::get));
+ }
+
+ #[test]
+ fn test_new_rc() {
+ let start = DROP_INVOCATIONS.with(Cell::get);
+ {
+ let _ = CartableOptionPointer::<Rc<&[u8]>>::from_cartable(SAMPLE_BYTES.into());
+ }
+ assert_eq!(start + 1, DROP_INVOCATIONS.with(Cell::get));
+ }
+
+ #[test]
+ fn test_rc_clone() {
+ let start = DROP_INVOCATIONS.with(Cell::get);
+ {
+ let x = CartableOptionPointer::<Rc<&[u8]>>::from_cartable(SAMPLE_BYTES.into());
+ assert_eq!(start, DROP_INVOCATIONS.with(Cell::get));
+ {
+ let _ = x.clone();
+ }
+ assert_eq!(start, DROP_INVOCATIONS.with(Cell::get));
+ {
+ let _ = x.clone();
+ let _ = x.clone();
+ let _ = x.clone();
+ }
+ assert_eq!(start, DROP_INVOCATIONS.with(Cell::get));
+ }
+ assert_eq!(start + 1, DROP_INVOCATIONS.with(Cell::get));
+ }
+}
diff --git a/crates/yoke/src/either.rs b/crates/yoke/src/either.rs
new file mode 100644
index 0000000..3749e7d
--- /dev/null
+++ b/crates/yoke/src/either.rs
@@ -0,0 +1,86 @@
+// 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::rc::Rc;
+/// use yoke::either::EitherCart;
+/// use yoke::Yoke;
+///
+/// let y1: Yoke<&'static str, Rc<str>> =
+/// 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<Rc<str>, &'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, Debug)]
+#[allow(clippy::exhaustive_enums)] // stable
+pub enum EitherCart<C0, C1> {
+ A(C0),
+ B(C1),
+}
+
+impl<C0, C1, T> Deref for EitherCart<C0, C1>
+where
+ C0: Deref<Target = T>,
+ C1: Deref<Target = T>,
+{
+ type Target = T;
+ fn deref(&self) -> &T {
+ use EitherCart::*;
+ match self {
+ A(a) => a.deref(),
+ B(b) => b.deref(),
+ }
+ }
+}
+
+// Safety: Safe because both sub-types implement the trait.
+unsafe impl<C0, C1, T> StableDeref for EitherCart<C0, C1>
+where
+ C0: StableDeref,
+ C1: StableDeref,
+ C0: Deref<Target = T>,
+ C1: Deref<Target = T>,
+{
+}
+
+// Safety: Safe because both sub-types implement the trait.
+unsafe impl<C0, C1> CloneableCart for EitherCart<C0, C1>
+where
+ C0: CloneableCart,
+ C1: CloneableCart,
+{
+}
diff --git a/crates/yoke/src/erased.rs b/crates/yoke/src/erased.rs
new file mode 100644
index 0000000..4395404
--- /dev/null
+++ b/crates/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.
+//!
+//! ✨ *Enabled with the `alloc` Cargo feature.*
+
+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<T: 'static> 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.
+///
+/// ✨ *Enabled with the `alloc` Cargo feature.*
+pub type ErasedArcCart = Arc<dyn ErasedDestructor + Send + Sync>;
+/// A type-erased Cart that has `Rc` semantics
+///
+/// See the docs of [`Yoke::erase_rc_cart()`](crate::Yoke::erase_rc_cart) for more info.
+///
+/// ✨ *Enabled with the `alloc` Cargo feature.*
+pub type ErasedRcCart = Rc<dyn ErasedDestructor>;
+/// A type-erased Cart that has `Box` semantics
+///
+/// See the docs of [`Yoke::erase_box_cart()`](crate::Yoke::erase_box_cart) for more info.
+///
+/// ✨ *Enabled with the `alloc` Cargo feature.*
+pub type ErasedBoxCart = Box<dyn ErasedDestructor>;
diff --git a/crates/yoke/src/kinda_sorta_dangling.rs b/crates/yoke/src/kinda_sorta_dangling.rs
new file mode 100644
index 0000000..1f099f7
--- /dev/null
+++ b/crates/yoke/src/kinda_sorta_dangling.rs
@@ -0,0 +1,95 @@
+// 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 core::mem::{ManuallyDrop, MaybeUninit};
+use core::ops::{Deref, DerefMut};
+
+/// This type is intended to be similar to the type `MaybeDangling<T>`
+/// proposed in [RFC 3336].
+///
+/// The effect of this is that in Rust's safety model, types inside here are not
+/// expected to have any memory dependent validity properties (`dereferenceable`, `noalias`).
+///
+/// See [#3696] for a testcase where `Yoke` fails under miri's field-retagging mode if not using
+/// KindaSortaDangling.
+///
+/// This has `T: 'static` since we don't need anything
+/// else and we don't want to have to think (more) about variance over lifetimes or dropck.
+///
+/// After [RFC 3336] lands we can use `MaybeDangling` instead.
+///
+/// Note that a version of this type also exists publicly as the [`maybe_dangling`]
+/// crate; which also exports a patched `ManuallyDrop` with similar semantics and
+/// does not require `T: 'static`. Consider using this if you need something more general
+/// and are okay with adding dependencies.
+///
+/// [RFC 3336]: https://github.com/rust-lang/rfcs/pull/3336
+/// [#3696]: https://github.com/unicode-org/icu4x/issues/3696
+/// [`maybe_dangling`](https://docs.rs/maybe-dangling/0.1.0/maybe_dangling/struct.MaybeDangling.html)
+#[repr(transparent)]
+pub(crate) struct KindaSortaDangling<T: 'static> {
+ /// Safety invariant: This is always an initialized T, never uninit or other
+ /// invalid bit patterns. Its drop glue will execute during Drop::drop rather than
+ /// during the drop glue for KindaSortaDangling, which means that we have to be careful about
+ /// not touching the values as initialized during `drop` after that, but that's a short period of time.
+ dangle: MaybeUninit<T>,
+}
+
+impl<T: 'static> KindaSortaDangling<T> {
+ #[inline]
+ pub(crate) const fn new(dangle: T) -> Self {
+ KindaSortaDangling {
+ dangle: MaybeUninit::new(dangle),
+ }
+ }
+ #[inline]
+ pub(crate) fn into_inner(self) -> T {
+ // Self has a destructor, we want to avoid having it be called
+ let manual = ManuallyDrop::new(self);
+ // Safety:
+ // We can call assume_init_read() due to the library invariant on this type,
+ // however since it is a read() we must be careful about data duplication.
+ // The only code using `self` after this is the drop glue, which we have disabled via
+ // the ManuallyDrop.
+ unsafe { manual.dangle.assume_init_read() }
+ }
+}
+
+impl<T: 'static> Deref for KindaSortaDangling<T> {
+ type Target = T;
+ #[inline]
+ fn deref(&self) -> &T {
+ // Safety: Due to the safety invariant on `dangle`, it is guaranteed to be always
+ // initialized as deref is never called during drop.
+ unsafe { self.dangle.assume_init_ref() }
+ }
+}
+
+impl<T: 'static> DerefMut for KindaSortaDangling<T> {
+ #[inline]
+ fn deref_mut(&mut self) -> &mut T {
+ // Safety: Due to the safety invariant on `dangle`, it is guaranteed to be always
+ // initialized as deref_mut is never called during drop.
+ unsafe { self.dangle.assume_init_mut() }
+ }
+}
+
+impl<T: 'static> Drop for KindaSortaDangling<T> {
+ #[inline]
+ fn drop(&mut self) {
+ // Safety: We are reading and dropping a valid initialized T.
+ //
+ // As `drop_in_place()` is a `read()`-like duplication operation we must be careful that the original value isn't
+ // used afterwards. It won't be because this is drop and the only
+ // code that will run after this is `self`'s drop glue, and that drop glue is empty
+ // because MaybeUninit has no drop.
+ //
+ // We use `drop_in_place()` instead of `let _ = ... .assume_init_read()` to avoid creating a move
+ // of the inner `T` (without `KindaSortaDangling` protection!) type into a local -- we don't want to
+ // assert any of `T`'s memory-related validity properties here.
+ unsafe {
+ self.dangle.as_mut_ptr().drop_in_place();
+ }
+ }
+}
diff --git a/crates/yoke/src/lib.rs b/crates/yoke/src/lib.rs
new file mode 100644
index 0000000..26fe961
--- /dev/null
+++ b/crates/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<Y, C>`][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<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`](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<T>`](alloc::boxed::Box), [`Rc<T>`](alloc::rc::Rc), or [`Arc<T>`](std::sync::Arc), potentially wrapped in an [`Option<T>`](Option).
+//!
+//! 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()`](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/documents/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 cartable_ptr;
+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;
diff --git a/crates/yoke/src/macro_impls.rs b/crates/yoke/src/macro_impls.rs
new file mode 100644
index 0000000..4e17db9
--- /dev/null
+++ b/crates/yoke/src/macro_impls.rs
@@ -0,0 +1,128 @@
+// 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::Yokeable;
+use core::{
+ mem::{self, ManuallyDrop},
+ 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<F>(&'a mut self, f: F)
+ where
+ F: 'static + for<'b> FnOnce(&'b mut Self::Output),
+ {
+ f(self)
+ }
+ };
+}
+macro_rules! impl_copy_type {
+ ($ty:ty) => {
+ // Safety: all the types that this macro is used to generate impls of Yokeable for do not
+ // borrow any memory.
+ unsafe impl<'a> Yokeable<'a> for $ty {
+ type Output = Self;
+ copy_yoke_impl!();
+ }
+ };
+}
+
+impl_copy_type!(());
+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
+//
+// Safety: the caller of this macro must ensure that `Self` is indeed covariant in 'a.
+macro_rules! unsafe_complex_yoke_impl {
+ () => {
+ fn transform(&'a self) -> &'a Self::Output {
+ // Safety: equivalent to casting the lifetime. Macro caller ensures covariance.
+ unsafe { mem::transmute(self) }
+ }
+
+ fn transform_owned(self) -> Self::Output {
+ debug_assert!(mem::size_of::<Self::Output>() == mem::size_of::<Self>());
+ // Safety: equivalent to casting the lifetime. Macro caller ensures covariance.
+ unsafe {
+ let ptr: *const Self::Output = (&self as *const Self).cast();
+ let _ = ManuallyDrop::new(self);
+ ptr::read(ptr)
+ }
+ }
+
+ unsafe fn make(from: Self::Output) -> Self {
+ debug_assert!(mem::size_of::<Self::Output>() == mem::size_of::<Self>());
+ let ptr: *const Self = (&from as *const Self::Output).cast();
+ let _ = ManuallyDrop::new(from);
+ // Safety: `ptr` is certainly valid, aligned and points to a properly initialized value, as
+ // it comes from a value that was moved into a ManuallyDrop.
+ unsafe { ptr::read(ptr) }
+ }
+
+ fn transform_mut<F>(&'a mut self, f: F)
+ where
+ F: 'static + for<'b> FnOnce(&'b mut Self::Output),
+ {
+ // Cast away the lifetime of Self
+ // Safety: this is equivalent to f(transmute(self)), and the documentation of the trait
+ // method explains why doing so is sound.
+ unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) }
+ }
+ };
+}
+
+// Safety: since T implements Yokeable<'a>, Option<T<'b>> must be covariant on 'b or the Yokeable
+// implementation on T would be unsound.
+unsafe impl<'a, T: 'static + for<'b> Yokeable<'b>> Yokeable<'a> for Option<T> {
+ type Output = Option<<T as Yokeable<'a>>::Output>;
+ unsafe_complex_yoke_impl!();
+}
+
+// Safety: since T1, T2 implement Yokeable<'a>, (T1<'b>, T2<'b>) must be covariant on 'b or the Yokeable
+// implementation on T would be unsound.
+unsafe impl<'a, T1: 'static + for<'b> Yokeable<'b>, T2: 'static + for<'b> Yokeable<'b>> Yokeable<'a>
+ for (T1, T2)
+{
+ type Output = (<T1 as Yokeable<'a>>::Output, <T2 as Yokeable<'a>>::Output);
+ unsafe_complex_yoke_impl!();
+}
+
+// Safety: since T implements Yokeable<'a>, [T<'b>; N] must be covariant on 'b or the Yokeable
+// implementation on T would be unsound.
+unsafe impl<'a, T: 'static + for<'b> Yokeable<'b>, const N: usize> Yokeable<'a> for [T; N] {
+ type Output = [<T as Yokeable<'a>>::Output; N];
+ unsafe_complex_yoke_impl!();
+}
diff --git a/crates/yoke/src/trait_hack.rs b/crates/yoke/src/trait_hack.rs
new file mode 100644
index 0000000..109e3a7
--- /dev/null
+++ b/crates/yoke/src/trait_hack.rs
@@ -0,0 +1,319 @@
+// 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> <Y as Yokeable<'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 `<Y as Yokeable<'de>>::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 <Y as Yokeable<'a>>::Output: MyTrait`
+//! 2. If the trait involves `Self`, like `Clone`, use [`YokeTraitHack`]:
+//! `where for<'a> YokeTraitHack<<Y as Yokeable<'a>>::Output>: MyTrait`
+//!
+//! # Examples
+//!
+//! Code that does not compile ([playground](https://play.rust-lang.org/?version=beta&mode=debug&edition=2018&gist=ebbda5b15a398d648bdff9e439b27dc0)):
+//!
+//! ```compile_fail
+//! # this compiles in 1.78+, so this text will make it fail
+//! use yoke::*;
+//!
+//! trait MiniDataMarker {
+//! type Yokeable: for<'a> Yokeable<'a>;
+//! }
+//!
+//! struct MiniDataPayload<M>
+//! where
+//! M: MiniDataMarker
+//! {
+//! pub yoke: Yoke<M::Yokeable, ()>,
+//! }
+//!
+//! impl<M> Clone for MiniDataPayload<M>
+//! where
+//! M: MiniDataMarker,
+//! for<'a> <M::Yokeable as Yokeable<'a>>::Output: Clone,
+//! {
+//! fn clone(&self) -> Self {
+//! unimplemented!()
+//! }
+//! }
+//!
+//! trait MiniDataProvider<M>
+//! where
+//! M: MiniDataMarker
+//! {
+//! fn mini_load_data(&self) -> MiniDataPayload<M>;
+//! }
+//!
+//! struct MiniStructProvider<M>
+//! where
+//! M: MiniDataMarker,
+//! {
+//! pub payload: MiniDataPayload<M>,
+//! }
+//!
+//! impl<M> MiniDataProvider<M> for MiniStructProvider<M>
+//! where
+//! M: MiniDataMarker,
+//! for<'a> <M::Yokeable as Yokeable<'a>>::Output: Clone,
+//! {
+//! fn mini_load_data(&self) -> MiniDataPayload<M> {
+//! 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<F>(&'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 DataStruct = 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<SimpleStruct> = provider.mini_load_data();
+//!
+//! // Working:
+//! let payload = MiniDataProvider::<SimpleStruct>::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<F>(&'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<Y, C> MyTrait for Yoke<Y, C>
+//! where
+//! Y: for<'a> Yokeable<'a>,
+//! for<'a> &'a <Y as Yokeable<'a>>::Output: MyTrait,
+//! {
+//! fn demo(&self) -> u32 {
+//! self.get().demo()
+//! }
+//! }
+//!
+//! fn example() {
+//! let y = Yoke::<MyStruct, ()>::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<F>(&'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<T>
+//! where
+//! T: MyTrait,
+//! {
+//! fn demo(data: u32) -> Self {
+//! YokeTraitHack(T::demo(data))
+//! }
+//! }
+//!
+//! impl<Y> MyTrait for Yoke<Y, Rc<u32>>
+//! where
+//! Y: for<'a> Yokeable<'a>,
+//! for<'a> YokeTraitHack<<Y as Yokeable<'a>>::Output>: MyTrait,
+//! {
+//! fn demo(data: u32) -> Self {
+//! let rc_u32: Rc<u32> = Rc::new(data);
+//! Yoke::attach_to_cart(rc_u32, |u| {
+//! YokeTraitHack::<<Y as Yokeable>::Output>::demo(*u).0
+//! })
+//! }
+//! }
+//!
+//! fn example() {
+//! let _ = Yoke::<MyStruct, Rc<u32>>::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<Y, C1, C2>(y1: Yoke<Y, C1>, y2: Yoke<Y, C2>) -> bool
+/// where
+/// Y: for<'a> Yokeable<'a>,
+/// for<'a> YokeTraitHack<<Y as Yokeable<'a>>::Output>: PartialEq,
+/// {
+/// YokeTraitHack(y1.get()).into_ref() == YokeTraitHack(y2.get()).into_ref()
+/// }
+/// ```
+#[repr(transparent)]
+#[derive(Clone, PartialEq, Eq, Debug)]
+#[allow(clippy::exhaustive_structs)] // newtype
+pub struct YokeTraitHack<T>(pub T);
+
+impl<'a, T> YokeTraitHack<&'a T> {
+ /// Converts from `YokeTraitHack<&T>` to `&YokeTraitHack<T>`.
+ ///
+ /// This is safe because `YokeTraitHack` is `repr(transparent)`.
+ ///
+ /// This method is required to implement `Clone` on `Yoke`.
+ pub fn into_ref(self) -> &'a YokeTraitHack<T> {
+ // Safety: YokeTraitHack is repr(transparent) so it's always safe
+ // to transmute YTH<&T> to &YTH<T>
+ unsafe { mem::transmute::<YokeTraitHack<&T>, &YokeTraitHack<T>>(self) }
+ }
+}
+
+// This is implemented manually to avoid the serde derive dependency.
+#[cfg(feature = "serde")]
+impl<'de, T> serde::de::Deserialize<'de> for YokeTraitHack<T>
+where
+ T: serde::de::Deserialize<'de>,
+{
+ #[inline]
+ fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+ where
+ D: serde::de::Deserializer<'de>,
+ {
+ T::deserialize(deserializer).map(YokeTraitHack)
+ }
+}
diff --git a/crates/yoke/src/yoke.rs b/crates/yoke/src/yoke.rs
new file mode 100644
index 0000000..eaad9e0
--- /dev/null
+++ b/crates/yoke/src/yoke.rs
@@ -0,0 +1,1542 @@
+// 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::cartable_ptr::{CartableOptionPointer, CartablePointerLike};
+use crate::either::EitherCart;
+#[cfg(feature = "alloc")]
+use crate::erased::{ErasedArcCart, ErasedBoxCart, ErasedRcCart};
+use crate::kinda_sorta_dangling::KindaSortaDangling;
+use crate::trait_hack::YokeTraitHack;
+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<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.
+///
+/// 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.
+///
+/// # Example
+///
+/// For example, we can use this to store zero-copy deserialized data in a cache:
+///
+/// ```rust
+/// # use yoke::Yoke;
+/// # 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<Cow<'static, str>, Rc<[u8]>> {
+/// let rc: Rc<[u8]> = load_from_cache(filename);
+/// Yoke::<Cow<'static, str>, 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<Y: for<'a> Yokeable<'a>, C> {
+ // must be the first field for drop order
+ // this will have a 'static lifetime parameter, that parameter is a lie
+ yokeable: KindaSortaDangling<Y>,
+ // Safety invariant: this type can be anything, but `yokeable` may only contain references to
+ // StableDeref parts of this cart, and the targets of those references must be valid for the
+ // lifetime of this cart (it must own or borrow them). It's ok for this cart to contain stack
+ // data as long as it is not referenced by `yokeable` during construction. `attach_to_cart`,
+ // the typical constructor of this type, upholds this invariant, but other constructors like
+ // `replace_cart` need to uphold it.
+ // The implementation guarantees that there are no live `yokeable`s that reference data
+ // in a `cart` when the `cart` is dropped; this is guaranteed in the drop glue through field
+ // order.
+ cart: C,
+}
+
+// Manual `Debug` implementation, since the derived one would be unsound.
+// See https://github.com/unicode-org/icu4x/issues/3685
+impl<Y: for<'a> Yokeable<'a>, C: core::fmt::Debug> core::fmt::Debug for Yoke<Y, C>
+where
+ for<'a> <Y as Yokeable<'a>>::Output: core::fmt::Debug,
+{
+ fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+ f.debug_struct("Yoke")
+ .field("yokeable", self.get())
+ .field("cart", self.backing_cart())
+ .finish()
+ }
+}
+
+#[test]
+fn test_debug() {
+ let local_data = "foo".to_owned();
+ let y1 = Yoke::<alloc::borrow::Cow<'static, str>, Rc<String>>::attach_to_zero_copy_cart(
+ Rc::new(local_data),
+ );
+ assert_eq!(
+ format!("{y1:?}"),
+ r#"Yoke { yokeable: "foo", cart: "foo" }"#,
+ );
+}
+
+impl<Y: for<'a> Yokeable<'a>, C: StableDeref> Yoke<Y, C>
+where
+ <C as Deref>::Target: 'static,
+{
+ /// Construct a [`Yoke`] by yokeing an object to a cart in a closure.
+ ///
+ /// The closure can read and write data outside of its scope, but data it returns
+ /// may borrow only from the argument passed to the 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;
+ /// # 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<Cow<'static, str>, Rc<[u8]>> {
+ /// let rc: Rc<[u8]> = load_from_cache(filename);
+ /// Yoke::<Cow<'static, str>, Rc<[u8]>>::attach_to_cart(rc, |data: &[u8]| {
+ /// // essentially forcing a #[serde(borrow)]
+ /// Cow::Borrowed(bincode::deserialize(data).unwrap())
+ /// })
+ /// }
+ ///
+ /// let yoke: Yoke<Cow<str>, _> = load_object("filename.bincode");
+ /// assert_eq!(&**yoke.get(), "hello");
+ /// assert!(matches!(yoke.get(), &Cow::Borrowed(_)));
+ /// ```
+ ///
+ /// Write the number of consumed bytes to a local variable:
+ ///
+ /// ```
+ /// # use yoke::Yoke;
+ /// # use std::rc::Rc;
+ /// # use std::borrow::Cow;
+ /// # fn load_from_cache(_filename: &str) -> Rc<[u8]> {
+ /// # // dummy implementation
+ /// # Rc::new([0x5, 0x68, 0x65, 0x6c, 0x6c, 0x6f, 0, 0, 0])
+ /// # }
+ ///
+ /// fn load_object(
+ /// filename: &str,
+ /// ) -> (Yoke<Cow<'static, str>, Rc<[u8]>>, usize) {
+ /// let rc: Rc<[u8]> = load_from_cache(filename);
+ /// let mut bytes_remaining = 0;
+ /// let bytes_remaining = &mut bytes_remaining;
+ /// let yoke = Yoke::<Cow<'static, str>, Rc<[u8]>>::attach_to_cart(
+ /// rc,
+ /// |data: &[u8]| {
+ /// let mut d = postcard::Deserializer::from_bytes(data);
+ /// let output = serde::Deserialize::deserialize(&mut d);
+ /// *bytes_remaining = d.finalize().unwrap().len();
+ /// Cow::Borrowed(output.unwrap())
+ /// },
+ /// );
+ /// (yoke, *bytes_remaining)
+ /// }
+ ///
+ /// let (yoke, bytes_remaining) = load_object("filename.postcard");
+ /// assert_eq!(&**yoke.get(), "hello");
+ /// assert!(matches!(yoke.get(), &Cow::Borrowed(_)));
+ /// assert_eq!(bytes_remaining, 3);
+ /// ```
+ pub fn attach_to_cart<F>(cart: C, f: F) -> Self
+ where
+ // safety note: This works by enforcing that the *only* place the return value of F
+ // can borrow from is the cart, since `F` must be valid for all lifetimes `'de`
+ //
+ // The <C as Deref>::Target: 'static on the impl is crucial for safety as well
+ //
+ // See safety docs at the bottom of this file for more information
+ F: for<'de> FnOnce(&'de <C as Deref>::Target) -> <Y as Yokeable<'de>>::Output,
+ <C as Deref>::Target: 'static,
+ {
+ let deserialized = f(cart.deref());
+ Self {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs at the bottom of this file
+ // for the justification of why yokeable could only borrow from the Cart.
+ 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<E, F>(cart: C, f: F) -> Result<Self, E>
+ where
+ F: for<'de> FnOnce(&'de <C as Deref>::Target) -> Result<<Y as Yokeable<'de>>::Output, E>,
+ <C as Deref>::Target: 'static,
+ {
+ let deserialized = f(cart.deref())?;
+ Ok(Self {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs at the bottom of this file
+ // for the justification of why yokeable could only borrow from the Cart.
+ 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 <C as Deref>::Target) -> <Y as Yokeable<'de>>::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<E>(
+ cart: C,
+ f: for<'de> fn(&'de <C as Deref>::Target) -> Result<<Y as Yokeable<'de>>::Output, E>,
+ ) -> Result<Self, E> {
+ Self::try_attach_to_cart(cart, f)
+ }
+}
+
+impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, C> {
+ /// 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<Cow<'static, T>, C>`, this
+ /// will return an `&'a Cow<'a, T>`
+ ///
+ /// # Example
+ ///
+ /// ```rust
+ /// # use yoke::Yoke;
+ /// # 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<Cow<'static, str>, Rc<[u8]>> {
+ /// # let rc: Rc<[u8]> = load_from_cache(filename);
+ /// # Yoke::<Cow<'static, str>, 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<Cow<str>, _> = load_object("filename.bincode");
+ /// assert_eq!(yoke.get(), "hello");
+ /// ```
+ #[inline]
+ pub fn get<'a>(&'a self) -> &'a <Y as Yokeable<'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_owned();
+ /// let yoke = Yoke::<&'static str, Box<String>>::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_owned();
+ /// let mut yoke =
+ /// Yoke::<Cow<'static, str>, Box<String>>::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`.
+ ///
+ /// For the purpose of determining this, `Yoke` guarantees that references from the Yokeable
+ /// `Y` into the cart `C` will never be references into its stack data, only heap data protected
+ /// by `StableDeref`. This does not necessarily mean that `C` implements `StableDeref`, rather that
+ /// any data referenced by `Y` must be accessed through a `StableDeref` impl on something `C` owns.
+ ///
+ /// Concretely, this means that if `C = Option<Rc<T>>`, `Y` may contain references to the `T` but not
+ /// anything else.
+ /// - Lifetimes inside C must not be lengthened, even if they are themselves contravariant.
+ /// I.e., if C contains an `fn(&'a u8)`, it cannot be replaced with `fn(&'static u8),
+ /// even though that is typically safe.
+ ///
+ /// 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<C2>(self, f: impl FnOnce(C) -> C2) -> Yoke<Y, C2> {
+ Yoke {
+ // Safety note: the safety invariant of this function guarantees that
+ // the data that the yokeable references has its ownership (if any)
+ // transferred to the new cart before self.cart is dropped.
+ 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<Bar<'static>, Rc<[u8]>> {
+ /// # let rc: Rc<[u8]> = load_from_cache(filename);
+ /// # Yoke::<Bar<'static>, 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<u8>,
+ /// }
+ ///
+ /// // `load_object()` deserializes an object from a file
+ /// let mut bar: Yoke<Bar, _> = 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<F>(&'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 <Y as Yokeable<'a>>::Output),
+ {
+ self.yokeable.transform_mut(f)
+ }
+
+ /// Helper function allowing one to wrap the cart type `C` in an `Option<T>`.
+ #[inline]
+ pub fn wrap_cart_in_option(self) -> Yoke<Y, Option<C>> {
+ // Safety: the cart is preserved (since it is just wrapped into a Some),
+ // so any data it owns is too.
+ unsafe { self.replace_cart(Some) }
+ }
+}
+
+impl<Y: for<'a> Yokeable<'a>> Yoke<Y, ()> {
+ /// 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;
+ ///
+ /// let owned: Cow<str> = "hello".to_owned().into();
+ /// // this yoke can be intermingled with actually-borrowed Yokes
+ /// let yoke: Yoke<Cow<str>, ()> = Yoke::new_always_owned(owned);
+ ///
+ /// assert_eq!(yoke.get(), "hello");
+ /// ```
+ pub fn new_always_owned(yokeable: Y) -> Self {
+ Self {
+ // Safety note: this `yokeable` certainly does not reference data owned by (), so we do
+ // not have to worry about when the `yokeable` is dropped.
+ yokeable: KindaSortaDangling::new(yokeable),
+ cart: (),
+ }
+ }
+
+ /// Obtain the yokeable out of a `Yoke<Y, ()>`
+ ///
+ /// For most `Yoke` types this would be unsafe but it's
+ /// fine for `Yoke<Y, ()>` since there are no actual internal
+ /// references
+ pub fn into_yokeable(self) -> Y {
+ // Safety note: since `yokeable` cannot reference data owned by `()`, this is certainly
+ // safe.
+ self.yokeable.into_inner()
+ }
+}
+
+// C does not need to be StableDeref here, if the yoke was constructed it's valid,
+// and new_owned() doesn't construct a yokeable that uses references,
+impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, Option<C>> {
+ /// 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<str> = "hello".to_owned().into();
+ /// // this yoke can be intermingled with actually-borrowed Yokes
+ /// let yoke: Yoke<Cow<str>, Option<Rc<[u8]>>> = Yoke::new_owned(owned);
+ ///
+ /// assert_eq!(yoke.get(), "hello");
+ /// ```
+ pub const fn new_owned(yokeable: Y) -> Self {
+ Self {
+ // Safety note: this `yokeable` is known not to borrow from the cart.
+ yokeable: KindaSortaDangling::new(yokeable),
+ cart: None,
+ }
+ }
+
+ /// Obtain the yokeable out of a `Yoke<Y, Option<C>>` if possible.
+ ///
+ /// If the cart is `None`, this returns `Ok`, but if the cart is `Some`,
+ /// this returns `self` as an error.
+ pub fn try_into_yokeable(self) -> Result<Y, Self> {
+ // Safety: if the cart is None there is no way for the yokeable to
+ // have references into it because of the cart invariant.
+ match self.cart {
+ Some(_) => Err(self),
+ None => Ok(self.yokeable.into_inner()),
+ }
+ }
+}
+
+impl<Y: for<'a> Yokeable<'a>, C: CartablePointerLike> Yoke<Y, Option<C>> {
+ /// Converts a `Yoke<Y, Option<C>>` to `Yoke<Y, CartableOptionPointer<C>>`
+ /// for better niche optimization when stored as a field.
+ ///
+ /// # Examples
+ ///
+ /// ```
+ /// use std::borrow::Cow;
+ /// use yoke::Yoke;
+ ///
+ /// let yoke: Yoke<Cow<[u8]>, Box<Vec<u8>>> =
+ /// Yoke::attach_to_cart(vec![10, 20, 30].into(), |c| c.into());
+ ///
+ /// let yoke_option = yoke.wrap_cart_in_option();
+ /// let yoke_option_pointer = yoke_option.convert_cart_into_option_pointer();
+ /// ```
+ ///
+ /// The niche improves stack sizes:
+ ///
+ /// ```
+ /// use yoke::Yoke;
+ /// use yoke::cartable_ptr::CartableOptionPointer;
+ /// use std::mem::size_of;
+ /// use std::rc::Rc;
+ ///
+ /// // The data struct is 6 words:
+ /// # #[derive(yoke::Yokeable)]
+ /// # struct MyDataStruct<'a> {
+ /// # _s: (usize, usize, usize, usize),
+ /// # _p: &'a str,
+ /// # }
+ /// const W: usize = core::mem::size_of::<usize>();
+ /// assert_eq!(W * 6, size_of::<MyDataStruct>());
+ ///
+ /// // An enum containing the data struct with an `Option<Rc>` cart is 8 words:
+ /// enum StaticOrYoke1 {
+ /// Static(&'static MyDataStruct<'static>),
+ /// Yoke(Yoke<MyDataStruct<'static>, Option<Rc<String>>>),
+ /// }
+ /// assert_eq!(W * 8, size_of::<StaticOrYoke1>());
+ ///
+ /// // When using `CartableOptionPointer``, we need only 7 words for the same behavior:
+ /// enum StaticOrYoke2 {
+ /// Static(&'static MyDataStruct<'static>),
+ /// Yoke(Yoke<MyDataStruct<'static>, CartableOptionPointer<Rc<String>>>),
+ /// }
+ /// assert_eq!(W * 7, size_of::<StaticOrYoke2>());
+ /// ```
+ #[inline]
+ pub fn convert_cart_into_option_pointer(self) -> Yoke<Y, CartableOptionPointer<C>> {
+ match self.cart {
+ Some(cart) => Yoke {
+ // Safety note: CartableOptionPointer::from_cartable only wraps the `cart`,
+ // so the data referenced by the yokeable is still live.
+ yokeable: self.yokeable,
+ cart: CartableOptionPointer::from_cartable(cart),
+ },
+ None => Yoke {
+ // Safety note: this Yokeable cannot refer to any data since self.cart is None.
+ yokeable: self.yokeable,
+ cart: CartableOptionPointer::none(),
+ },
+ }
+ }
+}
+
+impl<Y: for<'a> Yokeable<'a>, C: CartablePointerLike> Yoke<Y, CartableOptionPointer<C>> {
+ /// Obtain the yokeable out of a `Yoke<Y, CartableOptionPointer<C>>` if possible.
+ ///
+ /// If the cart is `None`, this returns `Ok`, but if the cart is `Some`,
+ /// this returns `self` as an error.
+ #[inline]
+ pub fn try_into_yokeable(self) -> Result<Y, Self> {
+ if self.cart.is_none() {
+ Ok(self.yokeable.into_inner())
+ } else {
+ Err(self)
+ }
+ }
+}
+
+/// 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 on `StableDeref` types which, once `Clone`d, point to the same underlying data and retain ownership.
+///
+/// This trait can also be implemented on aggregates of such types like `Option<T: CloneableCart>` and `(T: CloneableCart, U: CloneableCart)`.
+///
+/// Essentially, all data that could be referenced by a Yokeable (i.e. data that is referenced via a StableDeref) must retain the same
+/// pointer and ownership semantics once cloned.
+pub unsafe trait CloneableCart: Clone {}
+
+#[cfg(feature = "alloc")]
+// Safety: Rc<T> implements CloneStableDeref.
+unsafe impl<T: ?Sized> CloneableCart for Rc<T> {}
+#[cfg(feature = "alloc")]
+// Safety: Arc<T> implements CloneStableDeref.
+unsafe impl<T: ?Sized> CloneableCart for Arc<T> {}
+// Safety: Option<T> cannot deref to anything that T doesn't already deref to.
+unsafe impl<T: CloneableCart> CloneableCart for Option<T> {}
+// Safety: &'a T is indeed StableDeref, and cloning it refers to the same data.
+// &'a T does not own in the first place, so ownership is preserved.
+unsafe impl<'a, T: ?Sized> CloneableCart for &'a T {}
+// Safety: () cannot deref to anything.
+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<Y: for<'a> Yokeable<'a>, C: CloneableCart> Clone for Yoke<Y, C>
+where
+ for<'a> YokeTraitHack<<Y as Yokeable<'a>>::Output>: Clone,
+{
+ fn clone(&self) -> Self {
+ let this: &Y::Output = self.get();
+ // We have an &T not a T, and we can clone YokeTraitHack<T>
+ let this_hack = YokeTraitHack(this).into_ref();
+ Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: C being a CloneableCart guarantees that the data referenced by the
+ // `yokeable` is kept alive by the clone of the cart.
+ unsafe { Y::make(this_hack.clone().0) },
+ ),
+ cart: self.cart.clone(),
+ }
+ }
+}
+
+#[test]
+fn test_clone() {
+ let local_data = "foo".to_owned();
+ let y1 = Yoke::<alloc::borrow::Cow<'static, str>, Rc<String>>::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<Y: for<'a> Yokeable<'a>, C> Yoke<Y, C> {
+ /// 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 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<Bar<'static>, 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<F>(&'a mut self, f: F)
+ /// # where
+ /// # F: 'static + FnOnce(&'a mut Self::Output),
+ /// # {
+ /// # unsafe { f(mem::transmute(self)) }
+ /// # }
+ /// # }
+ /// ```
+ //
+ // Safety docs can be found at the end of the file.
+ pub fn map_project<P, F>(self, f: F) -> Yoke<P, C>
+ where
+ P: for<'a> Yokeable<'a>,
+ F: for<'a> FnOnce(
+ <Y as Yokeable<'a>>::Output,
+ PhantomData<&'a ()>,
+ ) -> <P as Yokeable<'a>>::Output,
+ {
+ let p = f(self.yokeable.into_inner().transform_owned(), PhantomData);
+ Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs below for the justification of why
+ // yokeable could only borrow from the Cart.
+ 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<P, C>
+ where
+ P: for<'a> Yokeable<'a>,
+ C: CloneableCart,
+ F: for<'a> FnOnce(
+ &'this <Y as Yokeable<'a>>::Output,
+ PhantomData<&'a ()>,
+ ) -> <P as Yokeable<'a>>::Output,
+ {
+ let p = f(self.get(), PhantomData);
+ Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs below for the justification of why
+ // yokeable could only borrow from the Cart.
+ 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<Yoke<&'static str, Rc<[u8]>>, Utf8Error> {
+ /// y.try_map_project(move |bytes, _| str::from_utf8(bytes))
+ /// }
+ /// ```
+ ///
+ /// This can also be used to create a yoke for a subfield
+ ///
+ /// ```
+ /// # 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<Bar<'static>, Rc<[u8]>>,
+ /// ) -> Result<Yoke<&'static str, Rc<[u8]>>, 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<F>(&'a mut self, f: F)
+ /// # where
+ /// # F: 'static + FnOnce(&'a mut Self::Output),
+ /// # {
+ /// # unsafe { f(mem::transmute(self)) }
+ /// # }
+ /// # }
+ /// ```
+ pub fn try_map_project<P, F, E>(self, f: F) -> Result<Yoke<P, C>, E>
+ where
+ P: for<'a> Yokeable<'a>,
+ F: for<'a> FnOnce(
+ <Y as Yokeable<'a>>::Output,
+ PhantomData<&'a ()>,
+ ) -> Result<<P as Yokeable<'a>>::Output, E>,
+ {
+ let p = f(self.yokeable.into_inner().transform_owned(), PhantomData)?;
+ Ok(Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs below for the justification of why
+ // yokeable could only borrow from the Cart.
+ 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<Yoke<P, C>, E>
+ where
+ P: for<'a> Yokeable<'a>,
+ C: CloneableCart,
+ F: for<'a> FnOnce(
+ &'this <Y as Yokeable<'a>>::Output,
+ PhantomData<&'a ()>,
+ ) -> Result<<P as Yokeable<'a>>::Output, E>,
+ {
+ let p = f(self.get(), PhantomData)?;
+ Ok(Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs below for the justification of why
+ // yokeable could only borrow from the Cart.
+ 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<P, T>(
+ self,
+ capture: T,
+ f: for<'a> fn(
+ <Y as Yokeable<'a>>::Output,
+ capture: T,
+ PhantomData<&'a ()>,
+ ) -> <P as Yokeable<'a>>::Output,
+ ) -> Yoke<P, C>
+ where
+ P: for<'a> Yokeable<'a>,
+ {
+ let p = f(
+ self.yokeable.into_inner().transform_owned(),
+ capture,
+ PhantomData,
+ );
+ Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs below for the justification of why
+ // yokeable could only borrow from the Cart.
+ 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 <Y as Yokeable<'a>>::Output,
+ capture: T,
+ PhantomData<&'a ()>,
+ ) -> <P as Yokeable<'a>>::Output,
+ ) -> Yoke<P, C>
+ where
+ P: for<'a> Yokeable<'a>,
+ C: CloneableCart,
+ {
+ let p = f(self.get(), capture, PhantomData);
+ Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs below for the justification of why
+ // yokeable could only borrow from the Cart.
+ 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<P, T, E>(
+ self,
+ capture: T,
+ f: for<'a> fn(
+ <Y as Yokeable<'a>>::Output,
+ capture: T,
+ PhantomData<&'a ()>,
+ ) -> Result<<P as Yokeable<'a>>::Output, E>,
+ ) -> Result<Yoke<P, C>, E>
+ where
+ P: for<'a> Yokeable<'a>,
+ {
+ let p = f(
+ self.yokeable.into_inner().transform_owned(),
+ capture,
+ PhantomData,
+ )?;
+ Ok(Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs below for the justification of why
+ // yokeable could only borrow from the Cart.
+ 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 <Y as Yokeable<'a>>::Output,
+ capture: T,
+ PhantomData<&'a ()>,
+ ) -> Result<<P as Yokeable<'a>>::Output, E>,
+ ) -> Result<Yoke<P, C>, E>
+ where
+ P: for<'a> Yokeable<'a>,
+ C: CloneableCart,
+ {
+ let p = f(self.get(), capture, PhantomData)?;
+ Ok(Yoke {
+ yokeable: KindaSortaDangling::new(
+ // Safety: the resulting `yokeable` is dropped before the `cart` because
+ // of the Yoke invariant. See the safety docs below for the justification of why
+ // yokeable could only borrow from the Cart.
+ unsafe { P::make(p) },
+ ),
+ cart: self.cart.clone(),
+ })
+ }
+}
+
+#[cfg(feature = "alloc")]
+impl<Y: for<'a> Yokeable<'a>, C: 'static + Sized> Yoke<Y, Rc<C>> {
+ /// Allows type-erasing the cart in a `Yoke<Y, Rc<C>>`.
+ ///
+ /// 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<T>`, you can use
+ /// [`Yoke::wrap_cart_in_rc()`] to wrap it.
+ ///
+ /// ✨ *Enabled with the `alloc` Cargo feature.*
+ ///
+ /// # Example
+ ///
+ /// ```rust
+ /// use std::rc::Rc;
+ /// use yoke::erased::ErasedRcCart;
+ /// use yoke::Yoke;
+ ///
+ /// let buffer1: Rc<String> = Rc::new(" foo bar baz ".into());
+ /// let buffer2: Box<String> = 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!
+ /// ```
+ pub fn erase_rc_cart(self) -> Yoke<Y, ErasedRcCart> {
+ // Safety: safe because the cart is preserved, as it is just type-erased
+ unsafe { self.replace_cart(|c| c as ErasedRcCart) }
+ }
+}
+
+#[cfg(feature = "alloc")]
+impl<Y: for<'a> Yokeable<'a>, C: 'static + Sized + Send + Sync> Yoke<Y, Arc<C>> {
+ /// Allows type-erasing the cart in a `Yoke<Y, Arc<C>>`.
+ ///
+ /// 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<T>`, you can use
+ /// [`Yoke::wrap_cart_in_arc()`] to wrap it.
+ ///
+ /// ✨ *Enabled with the `alloc` Cargo feature.*
+ ///
+ /// # Example
+ ///
+ /// ```rust
+ /// use std::sync::Arc;
+ /// use yoke::erased::ErasedArcCart;
+ /// use yoke::Yoke;
+ ///
+ /// let buffer1: Arc<String> = Arc::new(" foo bar baz ".into());
+ /// let buffer2: Box<String> = 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!
+ /// ```
+ pub fn erase_arc_cart(self) -> Yoke<Y, ErasedArcCart> {
+ // Safety: safe because the cart is preserved, as it is just type-erased
+ unsafe { self.replace_cart(|c| c as ErasedArcCart) }
+ }
+}
+
+#[cfg(feature = "alloc")]
+impl<Y: for<'a> Yokeable<'a>, C: 'static + Sized> Yoke<Y, Box<C>> {
+ /// Allows type-erasing the cart in a `Yoke<Y, Box<C>>`.
+ ///
+ /// 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<T>`, you can use
+ /// [`Yoke::wrap_cart_in_box()`] to wrap it.
+ ///
+ /// ✨ *Enabled with the `alloc` Cargo feature.*
+ ///
+ /// # Example
+ ///
+ /// ```rust
+ /// use std::rc::Rc;
+ /// use yoke::erased::ErasedBoxCart;
+ /// use yoke::Yoke;
+ ///
+ /// let buffer1: Rc<String> = Rc::new(" foo bar baz ".into());
+ /// let buffer2: Box<String> = 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!
+ /// ```
+ pub fn erase_box_cart(self) -> Yoke<Y, ErasedBoxCart> {
+ // Safety: safe because the cart is preserved, as it is just type-erased
+ unsafe { self.replace_cart(|c| c as ErasedBoxCart) }
+ }
+}
+
+#[cfg(feature = "alloc")]
+impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, C> {
+ /// Helper function allowing one to wrap the cart type `C` in a `Box<T>`.
+ /// Can be paired with [`Yoke::erase_box_cart()`]
+ ///
+ /// ✨ *Enabled with the `alloc` Cargo feature.*
+ #[inline]
+ pub fn wrap_cart_in_box(self) -> Yoke<Y, Box<C>> {
+ // Safety: safe because the cart is preserved, as it is just wrapped.
+ unsafe { self.replace_cart(Box::new) }
+ }
+ /// Helper function allowing one to wrap the cart type `C` in an `Rc<T>`.
+ /// Can be paired with [`Yoke::erase_rc_cart()`], or generally used
+ /// to make the [`Yoke`] cloneable.
+ ///
+ /// ✨ *Enabled with the `alloc` Cargo feature.*
+ #[inline]
+ pub fn wrap_cart_in_rc(self) -> Yoke<Y, Rc<C>> {
+ // Safety: safe because the cart is preserved, as it is just wrapped
+ unsafe { self.replace_cart(Rc::new) }
+ }
+ /// Helper function allowing one to wrap the cart type `C` in an `Rc<T>`.
+ /// Can be paired with [`Yoke::erase_arc_cart()`], or generally used
+ /// to make the [`Yoke`] cloneable.
+ ///
+ /// ✨ *Enabled with the `alloc` Cargo feature.*
+ #[inline]
+ pub fn wrap_cart_in_arc(self) -> Yoke<Y, Arc<C>> {
+ // Safety: safe because the cart is preserved, as it is just wrapped
+ unsafe { self.replace_cart(Arc::new) }
+ }
+}
+
+impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, C> {
+ /// 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<B>(self) -> Yoke<Y, EitherCart<C, B>> {
+ // Safety: safe because the cart is preserved, as it is just wrapped.
+ unsafe { 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<A>(self) -> Yoke<Y, EitherCart<A, C>> {
+ // Safety: safe because the cart is preserved, as it is just wrapped.
+ unsafe { 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<a> fn(<Y as Yokeable<'a>>::Output, &'a ()) -> <P as Yokeable<'a>>::Output`.
+///
+/// Note that correctness arguments are similar if you replace `fn` with `FnOnce`.
+///
+/// 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<P>` dependent
+/// on data owned only by the `Yoke<Y>`.
+/// - 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<Cow<'static, str>, 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<Cow<'static, str>, 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<Bar<'static>, 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<F>(&'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 _: () = ();
+
+/// # Safety docs for attach_to_cart()'s signature
+///
+/// The `attach_to_cart()` family of methods get by by using the following bound:
+///
+/// ```rust,ignore
+/// F: for<'de> FnOnce(&'de <C as Deref>::Target) -> <Y as Yokeable<'de>>::Output,
+/// C::Target: 'static
+/// ```
+///
+/// to enforce that the yoking closure produces a yokeable that is *only* allowed to borrow from the cart.
+/// A way to be sure of this is as follows: imagine if `F` *did* borrow data of lifetime `'a` and stuff it in
+/// its output. Then that lifetime `'a` would have to live at least as long as `'de` *for all `'de`*.
+/// The only lifetime that satisfies that is `'static` (since at least one of the potential `'de`s is `'static`),
+/// and we're fine with that.
+///
+/// ## Implied bounds and variance
+///
+/// The `C::Target: 'static` bound is tricky, however. Let's imagine a situation where we *didn't* have that bound.
+///
+/// One thing to remember is that we are okay with the cart itself borrowing from places,
+/// e.g. `&[u8]` is a valid cart, as is `Box<&[u8]>`. `C` is not `'static`.
+///
+/// (I'm going to use `CT` in prose to refer to `C::Target` here, since almost everything here has to do
+/// with C::Target and not C itself.)
+///
+/// Unfortunately, there's a sneaky additional bound inside `F`. The signature of `F` is *actually*
+///
+/// ```rust,ignore
+/// F: for<'de> where<C::Target: 'de> FnOnce(&'de C::Target) -> <Y as Yokeable<'de>>::Output
+/// ```
+///
+/// using made-up "where clause inside HRTB" syntax to represent a type that can be represented inside the compiler
+/// and type system but not in Rust code. The `CT: 'de` bond comes from the `&'de C::Target`: any time you
+/// write `&'a T`, an implied bound of `T: 'a` materializes and is stored alongside it, since references cannot refer
+/// to data that itself refers to data of shorter lifetimes. If a reference is valid, its referent must be valid for
+/// the duration of the reference's lifetime, so every reference *inside* its referent must also be valid, giving us `T: 'a`.
+/// This kind of constraint is often called a "well formedness" constraint: `&'a T` is not "well formed" without that
+/// bound, and rustc is being helpful by giving it to us for free.
+///
+/// Unfortunately, this messes with our universal quantification. The `for<'de>` is no longer "For all lifetimes `'de`",
+/// it is "for all lifetimes `'de` *where `CT: 'de`*". And if `CT` borrows from somewhere (with lifetime `'ct`), then we get a
+/// `'ct: 'de` bound, and `'de` candidates that live longer than `'ct` won't actually be considered.
+/// The neat little logic at the beginning stops working.
+///
+/// `attach_to_cart()` will instead enforce that the produced yokeable *either* borrows from the cart (fine), or from
+/// data that has a lifetime that is at least `'ct`. Which means that `attach_to_cart()` will allow us to borrow locals
+/// provided they live at least as long as `'ct`.
+///
+/// Is this a problem?
+///
+/// This is totally fine if CT's lifetime is covariant: if C is something like `Box<&'ct [u8]>`, even if our
+/// yoked object borrows from locals outliving `'ct`, our Yoke can't outlive that
+/// lifetime `'ct` anyway (since it's a part of the cart type), so we're fine.
+///
+/// However it's completely broken for contravariant carts (e.g. `Box<fn(&'ct u8)>`). In that case
+/// we still get `'ct: 'de`, and we still end up being able to
+/// borrow from locals that outlive `'ct`. However, our Yoke _can_ outlive
+/// that lifetime, because Yoke shares its variance over `'ct`
+/// with the cart type, and the cart type is contravariant over `'ct`.
+/// So the Yoke can be upcast to having a longer lifetime than `'ct`, and *that* Yoke
+/// can outlive `'ct`.
+///
+/// We fix this by forcing `C::Target: 'static` in `attach_to_cart()`, which would make it work
+/// for fewer types, but would also allow Yoke to continue to be covariant over cart lifetimes if necessary.
+///
+/// An alternate fix would be to not allowing yoke to ever be upcast over lifetimes contained in the cart
+/// by forcing them to be invariant. This is a bit more restrictive and affects *all* `Yoke` users, not just
+/// those using `attach_to_cart()`.
+///
+/// See https://github.com/unicode-org/icu4x/issues/2926
+/// See also https://github.com/rust-lang/rust/issues/106431 for potentially fixing this upstream by
+/// changing how the bound works.
+///
+/// # Tests
+///
+/// Here's a broken `attach_to_cart()` that attempts to borrow from a local:
+///
+/// ```rust,compile_fail
+/// use yoke::Yoke;
+///
+/// let cart = vec![1, 2, 3, 4].into_boxed_slice();
+/// let local = vec![4, 5, 6, 7];
+/// let yoke: Yoke<&[u8], Box<[u8]>> = Yoke::attach_to_cart(cart, |_| &*local);
+/// ```
+///
+/// Fails as expected.
+///
+/// And here's a working one with a local borrowed cart that does not do any sneaky borrows whilst attaching.
+///
+/// ```rust
+/// use yoke::Yoke;
+///
+/// let cart = vec![1, 2, 3, 4].into_boxed_slice();
+/// let local = vec![4, 5, 6, 7];
+/// let yoke: Yoke<&[u8], &[u8]> = Yoke::attach_to_cart(&cart, |c| &*c);
+/// ```
+///
+/// Here's an `attach_to_cart()` that attempts to borrow from a longer-lived local due to
+/// the cart being covariant. It fails, but would not if the alternate fix of forcing Yoke to be invariant
+/// were implemented. It is technically a safe operation:
+///
+/// ```rust,compile_fail
+/// use yoke::Yoke;
+/// // longer lived
+/// let local = vec![4, 5, 6, 7];
+///
+/// let backing = vec![1, 2, 3, 4];
+/// let cart = Box::new(&*backing);
+///
+/// let yoke: Yoke<&[u8], Box<&[u8]>> = Yoke::attach_to_cart(cart, |_| &*local);
+/// println!("{:?}", yoke.get());
+/// ```
+///
+/// Finally, here's an `attach_to_cart()` that attempts to borrow from a longer lived local
+/// in the case of a contravariant lifetime. It does not compile, but in and of itself is not dangerous:
+///
+/// ```rust,compile_fail
+/// use yoke::Yoke;
+///
+/// type Contra<'a> = fn(&'a ());
+///
+/// let local = String::from("Hello World!");
+/// let yoke: Yoke<&'static str, Box<Contra<'_>>> = Yoke::attach_to_cart(Box::new((|_| {}) as _), |_| &local[..]);
+/// println!("{:?}", yoke.get());
+/// ```
+///
+/// It is dangerous if allowed to transform (testcase from #2926)
+///
+/// ```rust,compile_fail
+/// use yoke::Yoke;
+///
+/// type Contra<'a> = fn(&'a ());
+///
+///
+/// let local = String::from("Hello World!");
+/// let yoke: Yoke<&'static str, Box<Contra<'_>>> = Yoke::attach_to_cart(Box::new((|_| {}) as _), |_| &local[..]);
+/// println!("{:?}", yoke.get());
+/// let yoke_longer: Yoke<&'static str, Box<Contra<'static>>> = yoke;
+/// let leaked: &'static Yoke<&'static str, Box<Contra<'static>>> = Box::leak(Box::new(yoke_longer));
+/// let reference: &'static str = leaked.get();
+///
+/// println!("pre-drop: {reference}");
+/// drop(local);
+/// println!("post-drop: {reference}");
+/// ```
+const _: () = ();
diff --git a/crates/yoke/src/yokeable.rs b/crates/yoke/src/yokeable.rs
new file mode 100644
index 0000000..7295544
--- /dev/null
+++ b/crates/yoke/src/yokeable.rs
@@ -0,0 +1,375 @@
+// 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::{marker::PhantomData, 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. `<Cow<'static, T> 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>`.
+///
+/// This trait is also safe to implement on types that do not borrow memory.
+///
+/// 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<u8>,
+/// }
+///
+/// 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::<Bar<'a>>() == mem::size_of::<Self>());
+/// let ptr: *const Self = (&from as *const Self::Output).cast();
+/// mem::forget(from);
+/// ptr::read(ptr)
+/// }
+///
+/// fn transform_mut<F>(&'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<F>(&'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'));
+ /// }
+ /// ```
+ ///
+ /// More formally, a reference to an object that `f` assigns to a reference
+ /// in Self<'a> could be obtained from:
+ /// - a local variable: the compiler rejects the assignment because 'a certainly
+ /// outlives local variables in f.
+ /// - a field in its argument: because of the for<'b> bound, the call to `f`
+ /// must be valid for a particular 'b that is strictly shorter than 'a. Thus,
+ /// the compiler rejects the assignment.
+ /// - a reference field in Self<'a>: this does not extend the set of
+ /// non-static lifetimes reachable from Self<'a>, so this is fine.
+ /// - one of f's captures: since F: 'static, the resulting reference must refer
+ /// to 'static data.
+ /// - a static or thread_local variable: ditto.
+ fn transform_mut<F>(&'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")]
+// Safety: Cow<'a, _> is covariant in 'a.
+unsafe impl<'a, T: 'static + ToOwned + ?Sized> Yokeable<'a> for Cow<'static, T>
+where
+ <T as ToOwned>::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::<Cow<'a, T>>() == mem::size_of::<Self>());
+ let ptr: *const Self = (&from as *const Self::Output).cast();
+ let _ = core::mem::ManuallyDrop::new(from);
+ // Safety: `ptr` is certainly valid, aligned and points to a properly initialized value, as
+ // it comes from a value that was moved into a ManuallyDrop.
+ unsafe { core::ptr::read(ptr) }
+ }
+ #[inline]
+ fn transform_mut<F>(&'a mut self, f: F)
+ where
+ F: 'static + for<'b> FnOnce(&'b mut Self::Output),
+ {
+ // Cast away the lifetime of Self
+ // Safety: this is equivalent to f(transmute(self)), and the documentation of the trait
+ // method explains why doing so is sound.
+ unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) }
+ }
+}
+
+// Safety: &'a T is covariant in 'a.
+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 {
+ // Safety: function safety invariant guarantees that the returned reference
+ // will never be used beyond its original lifetime.
+ unsafe { mem::transmute(from) }
+ }
+ #[inline]
+ fn transform_mut<F>(&'a mut self, f: F)
+ where
+ F: 'static + for<'b> FnOnce(&'b mut Self::Output),
+ {
+ // Cast away the lifetime of Self
+ // Safety: this is equivalent to f(transmute(self)), and the documentation of the trait
+ // method explains why doing so is sound.
+ unsafe { f(mem::transmute::<&'a mut Self, &'a mut Self::Output>(self)) }
+ }
+}
+
+#[cfg(feature = "alloc")]
+// Safety: Vec<T: 'static> never borrows.
+unsafe impl<'a, T: 'static> Yokeable<'a> for alloc::vec::Vec<T> {
+ type Output = alloc::vec::Vec<T>;
+ #[inline]
+ fn transform(&'a self) -> &'a alloc::vec::Vec<T> {
+ self
+ }
+ #[inline]
+ fn transform_owned(self) -> alloc::vec::Vec<T> {
+ self
+ }
+ #[inline]
+ unsafe fn make(from: alloc::vec::Vec<T>) -> Self {
+ from
+ }
+ #[inline]
+ fn transform_mut<F>(&'a mut self, f: F)
+ where
+ F: 'static + for<'b> FnOnce(&'b mut Self::Output),
+ {
+ f(self)
+ }
+}
+
+// Safety: PhantomData is a ZST.
+unsafe impl<'a, T: ?Sized + 'static> Yokeable<'a> for PhantomData<T> {
+ type Output = PhantomData<T>;
+
+ fn transform(&'a self) -> &'a Self::Output {
+ self
+ }
+
+ fn transform_owned(self) -> Self::Output {
+ self
+ }
+
+ unsafe fn make(from: Self::Output) -> Self {
+ from
+ }
+
+ fn transform_mut<F>(&'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),
+ {
+ f(self)
+ }
+}
diff --git a/crates/yoke/src/zero_from.rs b/crates/yoke/src/zero_from.rs
new file mode 100644
index 0000000..d876d9c
--- /dev/null
+++ b/crates/yoke/src/zero_from.rs
@@ -0,0 +1,57 @@
+// 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<T>
+where
+ T: ZeroFrom<'zf, C>,
+{
+ #[inline]
+ fn zero_from(cart: &'zf C) -> Self {
+ YokeTraitHack(T::zero_from(cart))
+ }
+}
+
+impl<Y, C> Yoke<Y, C>
+where
+ Y: for<'a> Yokeable<'a>,
+ for<'a> YokeTraitHack<<Y as Yokeable<'a>>::Output>: ZeroFrom<'a, <C as Deref>::Target>,
+ C: StableDeref + Deref,
+ <C as Deref>::Target: 'static,
+{
+ /// Construct a [`Yoke`]`<Y, C>` 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`]`<C::Target>`. 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::<Cow<'static, str>, String>::attach_to_zero_copy_cart(
+ /// "demo".to_owned(),
+ /// );
+ ///
+ /// assert_eq!("demo", yoke.get());
+ /// ```
+ pub fn attach_to_zero_copy_cart(cart: C) -> Self {
+ Yoke::<Y, C>::attach_to_cart(cart, |c| {
+ YokeTraitHack::<<Y as Yokeable>::Output>::zero_from(c).0
+ })
+ }
+}
diff --git a/crates/yoke/tests/bincode.rs b/crates/yoke/tests/bincode.rs
new file mode 100644
index 0000000..653865e
--- /dev/null
+++ b/crates/yoke/tests/bincode.rs
@@ -0,0 +1,83 @@
+// 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 test is a duplicate of one of the doctests, but is written separately
+// since `cargo miri test` doesn't work on doctests yet
+
+use std::borrow::Cow;
+use std::mem;
+use std::rc::Rc;
+use yoke::{Yoke, Yokeable};
+
+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<Bar<'static>, Rc<[u8]>> {
+ let rc: Rc<[u8]> = load_from_cache(filename);
+ Yoke::<Bar<'static>, 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<u8>,
+}
+
+unsafe impl<'a> Yokeable<'a> for Bar<'static> {
+ type Output = Bar<'a>;
+ #[inline]
+ fn transform(&'a self) -> &'a Bar<'a> {
+ self
+ }
+ #[inline]
+ fn transform_owned(self) -> Bar<'a> {
+ self
+ }
+ #[inline]
+ unsafe fn make(from: Bar<'a>) -> Self {
+ let ret = mem::transmute_copy(&from);
+ mem::forget(from);
+ ret
+ }
+ #[inline]
+ fn transform_mut<F>(&'a mut self, f: F)
+ where
+ F: 'static + FnOnce(&'a mut Self::Output),
+ {
+ unsafe { f(mem::transmute::<&mut Bar<'_>, &mut Bar<'a>>(self)) }
+ }
+}
+
+#[test]
+fn test_load() {
+ // `load_object()` deserializes an object from a file
+ let mut bar = 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(_)));
+}
diff --git a/crates/yoke/tests/miri.rs b/crates/yoke/tests/miri.rs
new file mode 100644
index 0000000..0b92af2
--- /dev/null
+++ b/crates/yoke/tests/miri.rs
@@ -0,0 +1,15 @@
+// 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 yoke::Yoke;
+
+// Test for strong protection, should pass under miri with -Zmiri-retag-fields
+// See https://github.com/unicode-org/icu4x/issues/3696
+
+fn example(_: Yoke<&'static [u8], Vec<u8>>) {}
+
+#[test]
+fn run_test() {
+ example(Yoke::attach_to_cart(vec![0, 1, 2], |data| data));
+}
diff --git a/pseudo_crate/Cargo.lock b/pseudo_crate/Cargo.lock
index d090cc4..bdef323 100644
--- a/pseudo_crate/Cargo.lock
+++ b/pseudo_crate/Cargo.lock
@@ -496,6 +496,7 @@
"x509-cert",
"xml-rs",
"yaml-rust",
+ "yoke",
"yoke-derive",
"zerocopy 0.8.14",
"zerocopy-derive 0.8.14",
@@ -6695,6 +6696,17 @@
]
[[package]]
+name = "yoke"
+version = "0.7.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "120e6aef9aa629e3d4f52dc8cc43a015c7724194c97dfaf45180d2daf2b77f40"
+dependencies = [
+ "serde",
+ "stable_deref_trait",
+ "zerofrom",
+]
+
+[[package]]
name = "yoke-derive"
version = "0.7.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
diff --git a/pseudo_crate/Cargo.toml b/pseudo_crate/Cargo.toml
index 93784e6..611bc5a 100644
--- a/pseudo_crate/Cargo.toml
+++ b/pseudo_crate/Cargo.toml
@@ -405,6 +405,7 @@
x509-cert = "=0.2.5"
xml-rs = "=0.8.19"
yaml-rust = "=0.4.5"
+yoke = "=0.7.5"
yoke-derive = "=0.7.5"
zerocopy = "=0.8.14"
zerocopy-derive = "=0.8.14"
diff --git a/pseudo_crate/crate-list.txt b/pseudo_crate/crate-list.txt
index 0c2556c..31f0c6e 100644
--- a/pseudo_crate/crate-list.txt
+++ b/pseudo_crate/crate-list.txt
@@ -404,6 +404,7 @@
x509-cert
xml-rs
yaml-rust
+yoke
yoke-derive
zerocopy
zerocopy-derive
