Struct RelPtr

pub struct RelPtr<T: ?Sized + MetaData, I: Delta = isize>(/* private fields */);

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!

Implementations

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 duplicate of the value.

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

Performs copy-assignment from source.

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: Delta> From<I> for RelPtr<T, I>

Convert an offset into a RelPtr

fn from(i: I) -> Self

Converts to this type from the input type.

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

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

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.

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

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