impl<Y, C> Yoke<Y, C>

fn attach_to_zero_copy_cart(cart: C) -> Self

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());

impl<Y: for<'a> Yokeable<'a>> Yoke<Y, ()>

fn new_always_owned(yokeable: Y) -> Self

Construct a new Yoke from static data. There will be no references to cart here since Yokeables are 'static, this is good for e.g. constructing fully owned Yokes 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

# 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");

fn into_yokeable(self: Self) -> Y

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

impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, Option<C>>

const fn new_owned(yokeable: Y) -> Self

Construct a new Yoke from static data. There will be no references to cart here since Yokeables are 'static, this is good for e.g. constructing fully owned Yokes 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

# 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");

fn try_into_yokeable(self: Self) -> Result<Y, Self>

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.

impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, C>

fn map_project<P, F>(self: 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

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) 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)) }
#     }
# }

fn map_project_cloned<'this, P, F>(self: &'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

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.

fn try_map_project<P, F, E>(self: 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>

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)) }
#     }
# }

fn try_map_project_cloned<'this, P, F, E>(self: &'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>

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.

fn map_project_with_explicit_capture<P, T>(self: 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>

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.

See the docs of Yoke::map_project for how this works.

fn map_project_cloned_with_explicit_capture<'this, P, T>(self: &'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

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.

See the docs of Yoke::map_project_cloned for how this works.

fn try_map_project_with_explicit_capture<P, T, E>(self: 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>

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.

See the docs of Yoke::try_map_project for how this works.

fn try_map_project_cloned_with_explicit_capture<'this, P, T, E>(self: &'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

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.

See the docs of Yoke::try_map_project_cloned for how this works.

impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, C>

fn wrap_cart_in_either_a<B>(self: Self) -> Yoke<Y, EitherCart<C, B>>

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.

fn wrap_cart_in_either_b<A>(self: Self) -> Yoke<Y, EitherCart<A, C>>

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.

impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, C>

fn wrap_cart_in_box(self: Self) -> Yoke<Y, Box<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.

fn wrap_cart_in_rc(self: Self) -> Yoke<Y, Rc<C>>

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.

fn wrap_cart_in_arc(self: Self) -> Yoke<Y, Arc<C>>

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.

impl<Y: for<'a> Yokeable<'a>, C> Yoke<Y, C>

fn get<'a>(self: &'a Self) -> &'a <Y as Yokeable<'a>>::Output

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

# 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");

fn backing_cart(self: &Self) -> &C

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.

fn into_backing_cart(self: Self) -> C

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!

unsafe fn replace_cart<C2, impl FnOnce(C) -> C2: FnOnce(C) -> C2>(self: Self, f: impl FnOnce(C) -> C2) -> Yoke<Y, C2>

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.

fn with_mut<'a, F>(self: &'a mut Self, f: F)
where
    F: 'static + for<'b> FnOnce(&'b mut <Y as Yokeable<'a>>::Output)

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.

# 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)) }
#     }
# }

fn wrap_cart_in_option(self: Self) -> Yoke<Y, Option<C>>

Helper function allowing one to wrap the cart type C in an Option<T>.

impl<Y: for<'a> Yokeable<'a>, C: 'static + Sized + Send + Sync> Yoke<Y, Arc<C>>

fn erase_arc_cart(self: Self) -> Yoke<Y, ErasedArcCart>

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 Yokes 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

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!

impl<Y: for<'a> Yokeable<'a>, C: 'static + Sized> Yoke<Y, Box<C>>

fn erase_box_cart(self: Self) -> Yoke<Y, ErasedBoxCart>

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 Yokes 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

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!

impl<Y: for<'a> Yokeable<'a>, C: 'static + Sized> Yoke<Y, Rc<C>>

fn erase_rc_cart(self: Self) -> Yoke<Y, ErasedRcCart>

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 Yokes 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

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!

impl<Y: for<'a> Yokeable<'a>, C: CartablePointerLike> Yoke<Y, Option<C>>

fn convert_cart_into_option_pointer(self: Self) -> Yoke<Y, CartableOptionPointer<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>());

impl<Y: for<'a> Yokeable<'a>, C: CartablePointerLike> Yoke<Y, CartableOptionPointer<C>>

fn try_into_yokeable(self: Self) -> Result<Y, Self>

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.

impl<Y: for<'a> Yokeable<'a>, C: StableDeref> Yoke<Y, C>

fn attach_to_cart<F>(cart: C, f: F) -> Self
where
    F: for<'de> FnOnce(&'de <C as Deref>::Target) -> <Y as Yokeable<'de>>::Output,
    <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);

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

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.

fn attach_to_cart_badly(cart: C, f: for<'de> fn(_: &'de <C as Deref>::Target) -> <Y as Yokeable<'de>>::Output) -> Self

Use [Yoke::attach_to_cart()].

This was needed because the pre-1.61 compiler couldn't always handle the FnOnce trait bound.

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>

Use [Yoke::try_attach_to_cart()].

This was needed because the pre-1.61 compiler couldn't always handle the FnOnce trait bound.

impl<T> Any for Yoke<Y, C>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Yoke<Y, C>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for Yoke<Y, C>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for Yoke<Y, C>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> ErasedDestructor for Yoke<Y, C>

impl<T> From for Yoke<Y, C>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T> ToOwned for Yoke<Y, C>

fn to_owned(self: &Self) -> T

fn clone_into(self: &Self, target: &mut T)

impl<T, U> Into for Yoke<Y, C>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for Yoke<Y, C>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for Yoke<Y, C>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>

impl<Y, C> Freeze for Yoke<Y, C>

impl<Y, C> RefUnwindSafe for Yoke<Y, C>

impl<Y, C> Send for Yoke<Y, C>

impl<Y, C> Sync for Yoke<Y, C>

impl<Y, C> Unpin for Yoke<Y, C>

impl<Y, C> UnsafeUnpin for Yoke<Y, C>

impl<Y, C> UnwindSafe for Yoke<Y, C>

impl<Y: for<'a> Yokeable<'a>, C: CloneableCart> Clone for Yoke<Y, C>

fn clone(self: &Self) -> Self

impl<Y: for<'a> Yokeable<'a>, C: core::fmt::Debug> Debug for Yoke<Y, C>

fn fmt(self: &Self, f: &mut Formatter<'_>) -> Result