Trait GenRefMethods

pub trait GenRefMethods<'s, M: Mutability, T: ?Sized>: Sealed {
    // Required methods
    fn as_ptr(&self) -> NonNull<T>;
    fn gen_into_shared_downgrading(self) -> &'s T;
    fn gen_into_mut(self, _proof: IsMutable<M>) -> &'s mut T;
    fn gen_into_shared(self, _proof: IsShared<M>) -> &'s T;
    fn reborrow(&mut self) -> GenRef<'_, M, T>;
    fn map<U: ?Sized>(
        self,
        f_mut: impl FnOnce(&mut T) -> &mut U,
        f_shared: impl FnOnce(&T) -> &U,
    ) -> GenRef<'s, M, U>;
    fn map_deref(self) -> GenRef<'s, M, T::Target>
       where T: Deref + DerefMut;
    fn deref(&self) -> &T;
}

This trait allows you to call associated functions of GenRef with method syntax.

These functions are not methods on GenRef to avoid confusion of own methods with methods of T (GenRef implements Deref). This trait lets you bypass this restriction in cases where it is not confusing. Use with care.

This trait is only implemented for GenRef<'_, M, T> and is sealed so no other types can implement it.

In theory, it is also possible to receive impl GenRefMethods<'_, M, T> instead of GenRef<'_, M, T> as an argument, which disables the Deref impl, although it is more confusing from the caller side.

Required Methods

fn as_ptr(&self) -> NonNull<T>

This is a method variant of the equivalent associated function on GenRef. Casts the reference into a NonNull pointer.

Safety

The GenRef must not be used while the pointer is active. The exact semantics of this depend on the memory model adopted by Rust.

Guarantees

The returned pointer is guaranteed to be valid for reads for 's, and also for writes if M is Mutable.

fn gen_into_shared_downgrading(self) -> &'s T

This is a method variant of the equivalent associated function on GenRef. Converts a generic GenRef<'_, M, T> into &T, downgrading the reference if M is Mutable.

If M is Shared it behaves exactly the same way as gen_into_shared without requiring a proof for sharedness. In this case, the difference between the two is purely semantic: if you have proof that M is Shared, you should use gen_into_shared.

fn gen_into_mut(self, _proof: IsMutable<M>) -> &'s mut T

This is a method variant of the equivalent associated function on GenRef. Converts a generic GenRef<'_, M, T> into &mut T. This is available in a generic context.

Once the transformations are done, the result can be converted back into a GenRef using the gen_from_mut function.

The conversion requires that M is Mutable, this must be proven by passing an IsMutable<M> value. That can be obtained by matching on M::mutability().

fn gen_into_shared(self, _proof: IsShared<M>) -> &'s T

This is a method variant of the equivalent associated function on GenRef. Converts a generic GenRef<'_, M, T> into &T. This is available in a generic context.

Once the transformations are done, the result can be converted back into a GenRef using the gen_from_shared function.

The conversion requires that M is Shared, this must be proven by passing an IsShared<M> value. That can be obtained by matching on M::mutability().

If you want to force the conversion even if M is Mutable, you can use the gen_into_shared_downgrading function.

fn reborrow(&mut self) -> GenRef<'_, M, T>

This is a method variant of the equivalent associated function on GenRef. Generically reborrows a GenRef. That is, it creates a shorter-lived owned GenRef from a &mut GenRef. This is available in a generic context.

This requires the variable to be marked mut, even if M is Shared and thus no mutation takes place.

fn map<U: ?Sized>( self, f_mut: impl FnOnce(&mut T) -> &mut U, f_shared: impl FnOnce(&T) -> &U, ) -> GenRef<'s, M, U>

This is a method variant of the equivalent associated function on GenRef. Maps a generic GenRef into another one using either f_mut or f_shared. This is available in a generic context.

Using this function is usually sufficient. For mapping over field access, you can use the field! macro instead. If you need more flexibility, you can use the gen_mut! macro or matching over M::mutability().

fn map_deref(self) -> GenRef<'s, M, T::Target>

where T: Deref + DerefMut,

This is a method variant of the equivalent associated function on GenRef. Generically dereferences the value contained in the GenRef. This is available in a generic context.

fn deref(&self) -> &T

Dereferences the GenRef. Same as Deref::deref(self). This method allows you to call methods on the referenced value explicitly.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl<'s, M: Mutability, T: ?Sized> GenRefMethods<'s, M, T> for GenRef<'s, M, T>