Struct rel_ptr::RelPtr

pub struct RelPtr<T: ?Sized + MetaData, I: Delta = isize>(_, _, _);

This represents a relative pointers

A relative pointer stores an offset, and uses its that in combination with its current position in memory to point to a value

See crate documentation for more information

Safety

When using core::num::NonZero*, it is UB to have the RelPtr point to itself, this could be achieved with

If you use RelPtr::from(offset), then you must ensure that the relative pointer is set with the given functions to avoid UB

When using RelPtr with packed structs it is important to keep in mind that packed struct move fields to align them to drop them. For example, the below example is UB

 #[repr(packed)]
 struct Base(String, UnsafeThing);
 
 struct UnsafeThing(RelPtr<String>); // points into Base
 
 impl Drop for UnsafeThing {
     fn drop(&mut self) {
         // ... accessing `RelPtr<String>` here is UB
     }
 }

This is because when Base drops, all of the fields are moved to align them. So the offset between the String in unsafe thing and the RelPtr<String> in UnsafeThing could be changed. This will result in UB if you try to access String inside of UnsafeThing even if you enforce drop order!

Methods

impl<T: ?Sized + MetaData, I: Nullable> RelPtr<T, I>

pub fn null() -> Self

A null relative pointer has an offset of 0, (points to itself)

pub fn is_null(&self) -> bool

Check if relative pointer is null

impl<T: ?Sized + MetaData, I: Delta> RelPtr<T, I>

pub fn set(&mut self, value: &mut T) -> Result<(), I::Error>

Set the offset of a relative pointer, if the offset cannot be calculated using the given Delta, then Err will be returned, and there will be no change to the offset

pub unsafe fn set_unchecked(&mut self, value: *mut T)

Set the offset of a relative pointer,

Safety

if the offset is out of bounds for the given Delta then it's value is UB

if the given pointer is null, this is UB

pub unsafe fn as_raw_unchecked(&mut self) -> *mut T

Converts the relative pointer into a normal raw pointer

Safety

You must ensure that the relative pointer was successfully set before calling this function and that the value pointed to does not change it's offset relative to RelPtr

if relative pointer was never set successfully, this function is UB

pub unsafe fn as_non_null_unchecked(&mut self) -> NonNull<T>

Converts the relative pointer into a normal raw pointer

Safety

Same as RelPtr::as_raw_unchecked

pub unsafe fn as_ref_unchecked(&self) -> &T

Gets a reference from the relative pointer

Safety

Same as RelPtr::as_raw_unchecked

pub unsafe fn as_mut_unchecked(&mut self) -> &mut T

Gets a mutable reference from the relative pointer

Safety

Same as RelPtr::as_raw_unchecked

impl<T: ?Sized + MetaData, I: Nullable> RelPtr<T, I>

pub unsafe fn as_raw(&mut self) -> *mut T

Converts the relative pointer into a normal raw pointer

Note: if self.is_null() then a null pointer will be returned

Safety

You must ensure that if the relative pointer was successfully set then the value pointed to does not change it's offset relative to RelPtr

if the relative pointer was not successfully set RelPtr::as_raw returns null, this function is safe for all types where size_of::<*mut T>() == size_of::<usize>(), otherwise this function is UB

pub unsafe fn as_non_null(&mut self) -> Ptr<T>

Converts the relative pointer into a normal raw pointer

Safety

You must ensure that if the relative pointer was successfully set then the value pointed to does not change it's offset relative to RelPtr

if the relative pointer was never successfully set RelPtr::as_non_null returns None,

pub unsafe fn as_ref(&self) -> Option<&T>

Gets a reference from the relative pointer, if the relative pointer is null, then None is returned

Safety

You are not allows to alias another mutable reference, as per the aliasing rules of references

Same as RelPtr::as_non_null

pub unsafe fn as_mut(&mut self) -> Option<&mut T>

Gets a reference from the relative pointer, if the relative pointer is null, then None is returned

Safety

You are not allows to alias this mutable reference, as per the aliasing rules of references

Same as RelPtr::as_non_null

Trait Implementations

impl<T: ?Sized + MetaData, I: Delta> Clone for RelPtr<T, I>

fn clone(&self) -> Self

Returns a copy of the value.

default fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: ?Sized + MetaData, I: Delta> Eq for RelPtr<T, I>

impl<T: ?Sized + MetaData, I: Delta> Copy for RelPtr<T, I>

impl<T: ?Sized + MetaData, I: Delta> PartialEq<RelPtr<T, I>> for RelPtr<T, I>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]

default fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<T: ?Sized + MetaData, I: Delta> From<I> for RelPtr<T, I>

Convert an offset into a RelPtr

fn from(i: I) -> Self

Performs the conversion.

impl<T: ?Sized + MetaData, I: Debug + Delta> Debug for RelPtr<T, I>

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

Formats the value using the given formatter.

impl<T: ?Sized + MetaData, I: Debug + Delta> Pointer for RelPtr<T, I>

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

Formats the value using the given formatter.