Struct selfie::SelfieMut

pub struct SelfieMut<'a, P, R>
where
    P: 'a,
    R: for<'this> RefType<'this>,
{ /* private fields */ }

A self-referential struct with a mutable reference (R) to an object owned by a pinned pointer (P).

If you only need a self-referential struct with an shared reference to the data behind P, see Selfie.

This struct is a simple wrapper containing both the pinned pointer P and the mutable reference to it R alongside it. It does not perform any additional kind of boxing or allocation.

A SelfieMut is constructed by using the new constructor, which requires the pinned pointer P, and a function to create the reference type R from a pinned mutable reference to the data behind P.

Because R references the data behind P for as long as this struct exists, the data behind P has to be considered to be exclusively borrowed for the lifetime of the SelfieMut.

Therefore, you cannot access the data behind P at all, until using into_owned, which drops R and returns P as it was given to the constructor.

Note that the referential type R is not accessible outside of the Selfie either, and can only be accessed by temporarily borrowing it through the with_referential and with_referential_mut methods, which hide its true lifetime.

This is done because R actually has a self-referential lifetime, which cannot be named in Rust’s current lifetime system.

Also because of the non-nameable self-referential lifetime, R is not the referential type itself, but a stand-in that implements RefType (e.g. Ref<T> instead of &T). See the refs module for some reference type stand-ins this library provides, or see the RefType trait documentation for how to implement your own.

Example

This example stores both an owned String and a str slice pointing into it.

use core::pin::Pin;
use selfie::{refs::Ref, Selfie};

let data: Pin<String> = Pin::new("Hello, world!".to_owned());
let selfie: Selfie<String, Ref<str>> = Selfie::new(data, |s| &s[0..5]);

assert_eq!("Hello", selfie.with_referential(|r| *r));
assert_eq!("Hello, world!", selfie.owned());

Implementations

impl<'a, P, R> SelfieMut<'a, P, R>

where P: StableDeref + DerefMut + 'a, R: for<'this> RefType<'this>,

pub fn new<F>(owned: Pin<P>, handler: F) -> Self

where F: for<'this> FnOnce(Pin<&'this mut P::Target>) -> <R as RefType<'this>>::Ref,

Creates a new SelfieMut from a pinned pointer P, and a closure to create the reference type R from a pinned, exclusive reference to the data behind P.

Note the closure cannot expect to be called with a specific lifetime, as it will handle the unnameable 'this lifetime instead.

Example

use std::pin::Pin;
use selfie::refs::Mut;
use selfie::SelfieMut;

let data = Pin::new("Hello, world!".to_owned());
let selfie: SelfieMut<String, Mut<str>> = SelfieMut::new(data, |s| &mut Pin::into_inner(s)[0..5]);

// The selfie now contains both the String buffer and a subslice to "Hello"
selfie.with_referential(|r| assert_eq!("Hello", *r));

pub fn try_new<E, F>( owned: Pin<P>, handler: F ) -> Result<Self, SelfieError<P, E>>

where F: for<'this> FnOnce(Pin<&'this mut P::Target>) -> Result<<R as RefType<'this>>::Ref, E>,

Creates a new SelfieMut from a pinned pointer P, and a fallible closure to create the reference type R from a pinned, exclusive reference to the data behind P.

Note the closure cannot expect to be called with a specific lifetime, as it will handle the unnameable 'this lifetime instead.

Errors

The closure can return a Result containing either the referential type, or any error type. If the closure returns an Err, it will be returned in a SelfieError alongside the original owned pointer type.

Example

use std::pin::Pin;
use selfie::refs::Mut;
use selfie::{SelfieError, SelfieMut};

let data = Pin::new("Hello, world!".to_owned());
let selfie: Result<SelfieMut<String, Mut<str>>, SelfieError<String, ()>> =
    SelfieMut::try_new(data, |s| Ok(&mut Pin::into_inner(s)[0..5]));

selfie.unwrap().with_referential(|r| assert_eq!("Hello", *r));

pub fn with_referential<'s, F, T>(&'s self, handler: F) -> T

where F: for<'this> FnOnce(&'s <R as RefType<'this>>::Ref) -> T,

Performs an operation borrowing the referential type R, and returns its result.

Example

use core::pin::Pin;
use selfie::{refs::Mut, SelfieMut};

let data: Pin<Box<u32>> = Box::pin(42);
let selfie: SelfieMut<Box<u32>, Mut<u32>> = SelfieMut::new(data, |i| Pin::into_inner(i));

assert_eq!(50, selfie.with_referential(|r| **r + 8));

pub fn with_referential_mut<'s, F, T>(&'s mut self, handler: F) -> T

where F: for<'this> FnOnce(&'s mut <R as RefType<'this>>::Ref) -> T,

Performs an operation mutably borrowing the referential type R, and returns its result.

Note that this operation can mutably access the data behind P.

Example

use core::pin::Pin;
use selfie::{refs::Mut, SelfieMut};

let data: Pin<String> = Pin::new("Hello, world!".to_owned());
let mut selfie: SelfieMut<String, Mut<str>> = SelfieMut::new(data, |s| &mut Pin::into_inner(s)[0..5]);

selfie.with_referential_mut(|s| s.make_ascii_uppercase());
selfie.with_referential(|s| assert_eq!("HELLO", *s));

let data = Pin::into_inner(selfie.into_owned());
assert_eq!("HELLO, world!", &data);

pub fn into_owned(self) -> Pin<P>

Unwraps the SelfieMut by dropping the reference type R, and returning the owned pointer type P, as it was passed to the constructor.

Example

use std::pin::Pin;
use selfie::refs::Mut;
use selfie::SelfieMut;

let data = Pin::new("Hello, world!".to_owned());
let selfie: SelfieMut<String, Mut<str>> = SelfieMut::new(data, |str| &mut Pin::into_inner(str)[0..5]);

let original_data: Pin<String> = selfie.into_owned();
assert_eq!("Hello, world!", original_data.as_ref().get_ref());

pub fn map<R2: for<'this> RefType<'this>, F>( self, mapper: F ) -> Selfie<'a, P, R2>

where F: for<'this> FnOnce(<R as RefType<'this>>::Ref, &'this ()) -> <R2 as RefType<'this>>::Ref,

Creates a new SelfieMut by consuming this SelfieMut’s reference type R and producing another (R2), using a given closure.

The owned pointer type P is left unchanged.

This method consumes the SelfieMut.

Example

use std::pin::Pin;
use selfie::refs::Mut;
use selfie::SelfieMut;

let data = Pin::new("Hello, world!".to_owned());
let selfie: SelfieMut<String, Mut<str>> = SelfieMut::new(data, |str| &mut Pin::into_inner(str)[0..5]);
selfie.with_referential(|s| assert_eq!("Hello", *s));

let selfie = selfie.map::<Mut<str>, _>(|str, _| &mut str[3..]);
selfie.with_referential(|s| assert_eq!("lo", *s));

pub fn try_map<R2: for<'this> RefType<'this>, E, F>( self, mapper: F ) -> Result<Selfie<'a, P, R2>, SelfieError<P, E>>

where F: for<'this> FnOnce(<R as RefType<'this>>::Ref, &'this ()) -> Result<<R2 as RefType<'this>>::Ref, E>,

Creates a new SelfieMut by consuming this SelfieMut’s reference type R and producing another (R2), using a given fallible closure.

The owned pointer type P is left unchanged.

This method consumes the SelfieMut.

Errors

The closure can return a Result containing either the referential type, or any error type. If the closure returns an Err, it will be returned in a SelfieError alongside the original owned pointer type.

Example

use std::pin::Pin;
use selfie::refs::Mut;
use selfie::SelfieMut;

let data = Pin::new("Hello, world!".to_owned());
let selfie: SelfieMut<String, Mut<str>> = SelfieMut::new(data, |str| &mut Pin::into_inner(str)[0..5]);
selfie.with_referential(|s| assert_eq!("Hello", *s));

let selfie = selfie.try_map::<Mut<str>, (), _>(|str, _| Ok(&mut str[3..])).unwrap();
selfie.with_referential(|s| assert_eq!("lo", *s));

Trait Implementations

impl<'a, P, R> Debug for SelfieMut<'a, P, R>

where for<'this> <R as RefType<'this>>::Ref: Debug, P: StableDeref + DerefMut + 'a, R: for<'this> RefType<'this>,

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

Formats the value using the given formatter.