Struct Ptr 

pub struct Ptr<T> { /* private fields */ }

A transparent wrapper around Option<NonNull<T>> returned by AtomicTaggedPtr operations.

It provides convenient helper methods to convert into raw const/mutable pointers, access the underlying Option<NonNull<T>>, and supports direct comparisons.

Implementations

impl<T> Ptr<T>

pub const fn new(ptr: Option<NonNull<T>>) -> Self

Creates a new Ptr wrapper from an Option<NonNull<T>>.

pub const fn null() -> Self

Creates a null Ptr.

Examples

use atomic_tagged_ptr::Ptr;

let p: Ptr<i32> = Ptr::null();
assert!(p.is_null());

pub const fn none() -> Self

Creates a null Ptr (alias for null).

Examples

use atomic_tagged_ptr::Ptr;

let p: Ptr<i32> = Ptr::none();
assert!(p.is_null());

pub fn cast<U>(self) -> Ptr<U>

Casts to a pointer of another type.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42u8;
let ptr = Ptr::new(NonNull::new(&val as *const u8 as *mut u8));
let casted: Ptr<i8> = ptr.cast();

pub fn as_mut_ptr(self) -> *mut T

Converts the pointer into a raw mutable pointer *mut T.

Returns a null pointer if the underlying value is None.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut val = 42;
let ptr = Ptr::new(NonNull::new(&mut val as *mut i32));
assert_eq!(unsafe { *ptr.as_mut_ptr() }, 42);

let null_ptr: Ptr<i32> = Ptr::null();
assert!(null_ptr.as_mut_ptr().is_null());

pub fn as_ptr(self) -> *const T

Converts the pointer into a raw const pointer *const T.

Returns a null pointer if the underlying value is None.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
assert_eq!(unsafe { *ptr.as_ptr() }, 42);

let null_ptr: Ptr<i32> = Ptr::null();
assert!(null_ptr.as_ptr().is_null());

pub const fn option(self) -> Option<NonNull<T>>

Obtains the underlying Option<NonNull<T>>.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let raw = NonNull::new(&val as *const i32 as *mut i32);
let ptr = Ptr::new(raw);
assert_eq!(ptr.option(), raw);

pub const fn as_option(self) -> Option<NonNull<T>>

Obtains the underlying Option<NonNull<T>> (alias for option).

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let raw = NonNull::new(&val as *const i32 as *mut i32);
let ptr = Ptr::new(raw);
assert_eq!(ptr.as_option(), raw);

pub fn is_null(self) -> bool

Returns true if the pointer is null.

Examples

use atomic_tagged_ptr::Ptr;

let p: Ptr<i32> = Ptr::null();
assert!(p.is_null());

pub fn is_some(self) -> bool

Returns true if the pointer is not null (is some).

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let p = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
assert!(p.is_some());

pub fn is_none(self) -> bool

Returns true if the pointer is null (is none).

Examples

use atomic_tagged_ptr::Ptr;

let p: Ptr<i32> = Ptr::null();
assert!(p.is_none());

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

Returns a shared reference to the value if the pointer is not null.

Safety

The caller must ensure that:

• The pointer is valid (aligned, points to a valid initialized value of type T).
• The memory is not mutated while the reference is active.
• The reference lifetime 'a is correctly bounded.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
unsafe {
    assert_eq!(ptr.as_ref(), Some(&42));
}

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

Returns a mutable reference to the value if the pointer is not null.

Safety

The caller must ensure that:

• The pointer is valid (aligned, points to a valid initialized value of type T).
• No other references (shared or mutable) to the same memory are active.
• The reference lifetime 'a is correctly bounded.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut val = 42;
let ptr = Ptr::new(NonNull::new(&mut val as *mut i32));
unsafe {
    let r = ptr.as_mut();
    assert_eq!(r, Some(&mut 42));
    *r.unwrap() = 100;
}
assert_eq!(val, 100);

pub fn expect(self, msg: &str) -> NonNull<T>

Unwraps the inner NonNull<T>, panicking with the given message if it is None.

Panics

Panics if the pointer is null.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
let non_null = ptr.expect("should not be null");
assert_eq!(unsafe { *non_null.as_ptr() }, 42);

pub fn unwrap(self) -> NonNull<T>

Unwraps the inner NonNull<T>, panicking if it is None.

Panics

Panics if the pointer is null.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
let non_null = ptr.unwrap();
assert_eq!(unsafe { *non_null.as_ptr() }, 42);

pub fn unwrap_or(self, default: NonNull<T>) -> NonNull<T>

Returns the contained NonNull<T> or a default.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val1 = 42;
let val2 = 84;
let non_null1 = NonNull::new(&val1 as *const i32 as *mut i32).unwrap();
let non_null2 = NonNull::new(&val2 as *const i32 as *mut i32).unwrap();

let ptr = Ptr::new(Some(non_null1));
assert_eq!(ptr.unwrap_or(non_null2), non_null1);

let null_ptr = Ptr::null();
assert_eq!(null_ptr.unwrap_or(non_null2), non_null2);

pub fn map<U, F>(self, f: F) -> Ptr<U>

where F: FnOnce(NonNull<T>) -> NonNull<U>,

Maps the inner NonNull<T> pointer to a new pointer of another type.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42u8;
let ptr = Ptr::new(NonNull::new(&val as *const u8 as *mut u8));
let mapped = ptr.map(|p| p.cast::<i8>());
assert_eq!(unsafe { *mapped.as_ptr() }, 42);

pub fn map_or<U, F>(self, default: U, f: F) -> U

where F: FnOnce(NonNull<T>) -> U,

Maps the inner NonNull<T> pointer to a value, or returns a default value.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
let res = ptr.map_or(0, |p| unsafe { *p.as_ptr() });
assert_eq!(res, 42);

let null_ptr = Ptr::null();
let res = null_ptr.map_or(0, |p| unsafe { *p.as_ptr() });
assert_eq!(res, 0);

pub fn map_or_else<U, D, F>(self, default: D, f: F) -> U

where D: FnOnce() -> U, F: FnOnce(NonNull<T>) -> U,

Maps the inner NonNull<T> pointer to a value, or evaluates a default closure.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
let res = ptr.map_or_else(|| 0, |p| unsafe { *p.as_ptr() });
assert_eq!(res, 42);

let null_ptr = Ptr::null();
let res = null_ptr.map_or_else(|| 0, |p| unsafe { *p.as_ptr() });
assert_eq!(res, 0);

pub unsafe fn read(self) -> T

Reads the value from self without moving it. This leaves the memory in self unchanged.

Safety

• The pointer must be non-null.
• The pointer must be valid for reads (correctly aligned, points to an initialized instance of T, etc.).
• The memory must not be mutated by another thread while being read.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
unsafe {
    assert_eq!(ptr.read(), 42);
}

pub unsafe fn read_volatile(self) -> T

Performs a volatile read of the value from self without moving it.

Volatile operations are intended for acting on I/O memory, and are never coalesced or eliminated by the compiler.

Safety

• The pointer must be non-null.
• The pointer must be valid for reads.
• The memory must not be mutated by another thread while being read.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
unsafe {
    assert_eq!(ptr.read_volatile(), 42);
}

pub unsafe fn read_unaligned(self) -> T

Reads the value from self without moving it, without requiring alignment.

Safety

• The pointer must be non-null.
• The pointer must be valid for reads.
• The memory must not be mutated by another thread while being read.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let val = 42;
let ptr = Ptr::new(NonNull::new(&val as *const i32 as *mut i32));
unsafe {
    assert_eq!(ptr.read_unaligned(), 42);
}

pub unsafe fn write(self, val: T)

Overwrites a memory location with the given value without reading or dropping the old value.

Safety

• The pointer must be non-null.
• The pointer must be valid for writes (correctly aligned, etc.).

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut val = 0;
let ptr = Ptr::new(NonNull::new(&mut val as *mut i32));
unsafe {
    ptr.write(42);
}
assert_eq!(val, 42);

pub unsafe fn write_volatile(self, val: T)

Performs a volatile write of a memory location with the given value.

Safety

• The pointer must be non-null.
• The pointer must be valid for writes.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut val = 0;
let ptr = Ptr::new(NonNull::new(&mut val as *mut i32));
unsafe {
    ptr.write_volatile(42);
}
assert_eq!(val, 42);

pub unsafe fn write_unaligned(self, val: T)

Overwrites a memory location with the given value without requiring alignment.

Safety

• The pointer must be non-null.
• The pointer must be valid for writes.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut val = 0;
let ptr = Ptr::new(NonNull::new(&mut val as *mut i32));
unsafe {
    ptr.write_unaligned(42);
}
assert_eq!(val, 42);

pub unsafe fn replace(self, val: T) -> T

Replaces the value at self with val, returning the old value.

Safety

• The pointer must be non-null.
• The pointer must be valid for reads and writes.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut val = 10;
let ptr = Ptr::new(NonNull::new(&mut val as *mut i32));
unsafe {
    let old = ptr.replace(20);
    assert_eq!(old, 10);
}
assert_eq!(val, 20);

pub unsafe fn swap(self, with: Ptr<T>)

Swaps the values at self and with.

Safety

• Both pointers must be non-null.
• Both pointers must be valid for reads and writes.
• Both pointers must be properly aligned.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut val1 = 10;
let mut val2 = 20;
let ptr1 = Ptr::new(NonNull::new(&mut val1 as *mut i32));
let ptr2 = Ptr::new(NonNull::new(&mut val2 as *mut i32));
unsafe {
    ptr1.swap(ptr2);
}
assert_eq!(val1, 20);
assert_eq!(val2, 10);

pub unsafe fn copy_to(self, dest: Ptr<T>, count: usize)

Copies count items from self to dest. The source and destination may overlap.

Safety

• Both pointers must be non-null.
• Both pointers must be valid for reads and writes.
• Both pointers must be properly aligned.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr = [1, 2, 3];
let ptr1 = Ptr::new(NonNull::new(&mut arr[0] as *mut i32));
let ptr2 = Ptr::new(NonNull::new(&mut arr[1] as *mut i32));
unsafe {
    ptr1.copy_to(ptr2, 2);
}
assert_eq!(arr, [1, 1, 2]);

pub unsafe fn copy_to_nonoverlapping(self, dest: Ptr<T>, count: usize)

Copies count items from self to dest. The source and destination must not overlap.

Safety

• Both pointers must be non-null.
• Both pointers must be valid for reads and writes.
• Both pointers must be properly aligned.
• The memory regions must not overlap.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr1 = [1, 2, 3];
let mut arr2 = [0, 0, 0];
let ptr1 = Ptr::new(NonNull::new(&mut arr1[0] as *mut i32));
let ptr2 = Ptr::new(NonNull::new(&mut arr2[0] as *mut i32));
unsafe {
    ptr1.copy_to_nonoverlapping(ptr2, 3);
}
assert_eq!(arr2, [1, 2, 3]);

pub unsafe fn copy_from(self, src: Ptr<T>, count: usize)

Copies count items from src to self. The source and destination may overlap.

Safety

• Both pointers must be non-null.
• Both pointers must be valid for reads and writes.
• Both pointers must be properly aligned.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr = [1, 2, 3];
let ptr1 = Ptr::new(NonNull::new(&mut arr[1] as *mut i32));
let ptr2 = Ptr::new(NonNull::new(&mut arr[0] as *mut i32));
unsafe {
    ptr1.copy_from(ptr2, 2);
}
assert_eq!(arr, [1, 1, 2]);

pub unsafe fn copy_from_nonoverlapping(self, src: Ptr<T>, count: usize)

Copies count items from src to self. The source and destination must not overlap.

Safety

• Both pointers must be non-null.
• Both pointers must be valid for reads and writes.
• Both pointers must be properly aligned.
• The memory regions must not overlap.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr1 = [1, 2, 3];
let mut arr2 = [0, 0, 0];
let ptr1 = Ptr::new(NonNull::new(&mut arr2[0] as *mut i32));
let ptr2 = Ptr::new(NonNull::new(&mut arr1[0] as *mut i32));
unsafe {
    ptr1.copy_from_nonoverlapping(ptr2, 3);
}
assert_eq!(arr2, [1, 2, 3]);

pub unsafe fn offset(self, count: isize) -> Self

Calculates the offset from a pointer.

If the pointer is null, this returns a null pointer.

Safety

Both the starting and resulting pointer must be either in bounds or one byte past the end of the same allocated object.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr = [10, 20, 30];
let ptr = Ptr::new(NonNull::new(&mut arr[0] as *mut i32));
unsafe {
    let offset_ptr = ptr.offset(1);
    assert_eq!(offset_ptr.read(), 20);
}

pub unsafe fn add(self, count: usize) -> Self

Calculates the offset from a pointer (positive offset).

If the pointer is null, this returns a null pointer.

Safety

Both the starting and resulting pointer must be either in bounds or one byte past the end of the same allocated object.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr = [10, 20, 30];
let ptr = Ptr::new(NonNull::new(&mut arr[0] as *mut i32));
unsafe {
    let offset_ptr = ptr.add(2);
    assert_eq!(offset_ptr.read(), 30);
}

pub unsafe fn sub(self, count: usize) -> Self

Calculates the offset from a pointer (negative offset).

If the pointer is null, this returns a null pointer.

Safety

Both the starting and resulting pointer must be either in bounds or one byte past the end of the same allocated object.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr = [10, 20, 30];
let ptr = Ptr::new(NonNull::new(&mut arr[2] as *mut i32));
unsafe {
    let offset_ptr = ptr.sub(1);
    assert_eq!(offset_ptr.read(), 20);
}

pub fn wrapping_offset(self, count: isize) -> Self

Calculates the offset from a pointer using wrapping arithmetic.

If the pointer is null, this returns a null pointer.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr = [10, 20, 30];
let ptr = Ptr::new(NonNull::new(&mut arr[0] as *mut i32));
let offset_ptr = ptr.wrapping_offset(1);
assert_eq!(unsafe { offset_ptr.read() }, 20);

pub fn wrapping_add(self, count: usize) -> Self

Calculates the offset from a pointer using wrapping arithmetic (positive offset).

If the pointer is null, this returns a null pointer.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr = [10, 20, 30];
let ptr = Ptr::new(NonNull::new(&mut arr[0] as *mut i32));
let offset_ptr = ptr.wrapping_add(2);
assert_eq!(unsafe { offset_ptr.read() }, 30);

pub fn wrapping_sub(self, count: usize) -> Self

Calculates the offset from a pointer using wrapping arithmetic (negative offset).

If the pointer is null, this returns a null pointer.

Examples

use atomic_tagged_ptr::Ptr;
use std::ptr::NonNull;

let mut arr = [10, 20, 30];
let ptr = Ptr::new(NonNull::new(&mut arr[2] as *mut i32));
let offset_ptr = ptr.wrapping_sub(1);
assert_eq!(unsafe { offset_ptr.read() }, 20);

Trait Implementations

impl<T> AsRef<Option<NonNull<T>>> for Ptr<T>

fn as_ref(&self) -> &Option<NonNull<T>>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> AsRef<Ptr<T>> for TaggedPtr<T>

fn as_ref(&self) -> &Ptr<T>

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Clone for Ptr<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Ptr<T>

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

Formats the value using the given formatter.

impl<T> Default for Ptr<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T> From<*const T> for Ptr<T>

fn from(ptr: *const T) -> Self

Converts to this type from the input type.

impl<T> From<*mut T> for Ptr<T>

fn from(ptr: *mut T) -> Self

Converts to this type from the input type.

impl<T> From<NonNull<T>> for Ptr<T>

fn from(ptr: NonNull<T>) -> Self

Converts to this type from the input type.

impl<T> From<Option<NonNull<T>>> for Ptr<T>

fn from(ptr: Option<NonNull<T>>) -> Self

Converts to this type from the input type.

impl<T> From<Ptr<T>> for *const T

fn from(ptr: Ptr<T>) -> Self

Converts to this type from the input type.

impl<T> From<Ptr<T>> for *mut T

fn from(ptr: Ptr<T>) -> Self

Converts to this type from the input type.

impl<T> From<Ptr<T>> for AtomicTaggedPtr<T>

fn from(ptr: Ptr<T>) -> Self

Converts to this type from the input type.

impl<T> From<Ptr<T>> for Option<*const T>

fn from(ptr: Ptr<T>) -> Self

Converts to this type from the input type.

impl<T> From<Ptr<T>> for Option<*mut T>

fn from(ptr: Ptr<T>) -> Self

Converts to this type from the input type.

impl<T> From<Ptr<T>> for Option<NonNull<T>>

fn from(ptr: Ptr<T>) -> Self

Converts to this type from the input type.

impl<T> From<TaggedPtr<T>> for Ptr<T>

fn from(tagged: TaggedPtr<T>) -> Self

Converts to this type from the input type.

impl<T> Hash for Ptr<T>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T> Ord for Ptr<T>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<T> PartialEq<*const T> for Ptr<T>

fn eq(&self, other: &*const T) -> 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> PartialEq<*mut T> for Ptr<T>

fn eq(&self, other: &*mut T) -> 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> PartialEq<NonNull<T>> for Ptr<T>

fn eq(&self, other: &NonNull<T>) -> 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> PartialEq<Option<NonNull<T>>> for Ptr<T>

fn eq(&self, other: &Option<NonNull<T>>) -> 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> PartialEq for Ptr<T>

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> PartialOrd for Ptr<T>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

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

Tests less than (for self and other) and is used by the < operator.

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

Tests less than or equal to (for self and other) and is used by the <= operator.

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<T> Pointer for Ptr<T>

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

Formats the value using the given formatter.

impl<T> Copy for Ptr<T>

impl<T> Eq for Ptr<T>