Struct NonNullExt

pub struct NonNullExt<T: ?Sized> { /* private fields */ }

A pointer that is extended with type id or name.

If ‘check’ feature is enabled, it contains type id or name. Otherwise, it’s just a NonNull. This is useful when you want to know the type of the pointer.

Implementations

impl<T: ?Sized> NonNullExt<T>

pub fn new(ptr: *mut T) -> Option<Self>

Creates a NonNullExt from the given pointer.

Returns None if the pointer is null.

Examples

use my_ecs::ds::NonNullExt;

let mut v = 0;
let ptr = NonNullExt::new(&mut v as *mut i32).unwrap();

pub unsafe fn new_unchecked(ptr: *mut T) -> Self

Creates a NonNullExt from the given pointer.

Safety

The pointer must be non-null.

Examples

use my_ecs::ds::NonNullExt;

let mut v = 0;
let ptr = unsafe { NonNullExt::new_unchecked(&mut v as *mut i32) };

pub fn from_nonnull(ptr: NonNull<T>) -> Self

Creates a NonNullExt from the given pointer.

Examples

use my_ecs::ds::NonNullExt;
use std::ptr::NonNull;

let mut v = 0;
let ptr = NonNull::new(&mut v as *mut i32).unwrap();
let ptr = NonNullExt::from_nonnull(ptr);

pub const fn dangling() -> Self

where T: Sized,

Creates a NonNullExt that is dangling, but well-aligned.

In many Rust functions, they require aligned pointers even if they are some trash values. This function will be usuful in that cases.

Examples

use my_ecs::ds::NonNullExt;

let dangling = NonNullExt::<i32>::dangling();

pub fn is_dangling(&self) -> bool

where T: Sized,

Returns true if the pointer is dangling.

Examples

use my_ecs::ds::NonNullExt;

let dangling = NonNullExt::<i32>::dangling();
assert!(dangling.is_dangling());

pub fn with_type(self, _ty: TypeIdExt) -> Self

Sets the TypeIdExt to the pointer then returns the pointer.

Basically, NonNullExt contains type name of the pointer if check feature is enabled. You can replace it with the given TypeIdExt using this method. But check feature is disabled, this method is no-op.

Examples

use my_ecs::{prelude::*, ds::NonNullExt};

let mut v = 0;
let ptr = NonNullExt::new(&mut v as *mut i32)
    .unwrap()
    .with_type(TypeIdExt::of::<i32>());

pub fn get_type(&self) -> Option<&TypeIdExt>

Returns TypeIdExt of the pointer if check feature is enabled and the pointer contains TypeIdExt rather than type name.

If you want to set the TypeIdExt to the pointer, call NonNullExt::with_type.

Examples

use my_ecs::{prelude::*, ds::NonNullExt};

let mut v = 0;
let ptr = NonNullExt::new(&mut v as *mut i32)
    .unwrap()
    .with_type(TypeIdExt::of::<i32>());

pub fn get_name(&self) -> Option<&'static str>

Returns type name of the pointer if check feature is enabled.

Examples

use my_ecs::ds::NonNullExt;

let mut v = 0;
let ptr = NonNullExt::new(&mut v as *mut i32).unwrap();
let name = ptr.get_name();

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

Casts the pointer to another type.

Note that this method resets TypeIdExt you set through NonNullExt::with_type.

Examples

use my_ecs::ds::NonNullExt;

let mut v = 0x1234_5678;
let ptr = NonNullExt::new(&mut v as *mut i32).unwrap();

let ptr = ptr.cast::<[u8; 4]>();
let ref_v = unsafe { ptr.as_ref() };
assert_eq!(*ref_v, i32::to_ne_bytes(v));

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

where T: Sized,

Adds an offset to the pointer then returns the result.

Note that count is in units of T. For example, count = 3 means 12 bytes offset if T is i32.

Safety

See NonNull::add.

Examples

use my_ecs::ds::NonNullExt;

let arr: [char; 3] = ['a', 'b', 'c'];
let ptr = NonNullExt::new(arr.as_ptr().cast_mut()).unwrap();

let ref_v = unsafe { ptr.add(1).as_ref() };
assert_eq!(ref_v, &'b');

let ref_v = unsafe { ptr.add(2).as_ref() };
assert_eq!(ref_v, &'c');

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

where T: Sized,

Subtracts an offset from the pointer then returns the result.

Note that count is in units of T. For example, count = 3 means 12 bytes offset if T is i32.

Safety

See NonNull::sub.

Examples

use my_ecs::ds::NonNullExt;

let arr: [char; 3] = ['a', 'b', 'c'];
let ptr = NonNullExt::new((&arr[2] as *const char).cast_mut()).unwrap();

let ref_v = unsafe { ptr.sub(1).as_ref() };
assert_eq!(ref_v, &'b');

let ref_v = unsafe { ptr.sub(2).as_ref() };
assert_eq!(ref_v, &'a');

Methods from Deref<Target = NonNull<T>>

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

Returns a shared reference to the value. If the value may be uninitialized, as_uninit_ref must be used instead.

For the mutable counterpart see as_mut.

Safety

When calling this method, you have to ensure that the pointer is convertible to a reference.

Examples

use std::ptr::NonNull;

let mut x = 0u32;
let ptr = NonNull::new(&mut x as *mut _).expect("ptr is null!");

let ref_x = unsafe { ptr.as_ref() };
println!("{ref_x}");

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

Returns a unique reference to the value. If the value may be uninitialized, as_uninit_mut must be used instead.

For the shared counterpart see as_ref.

Safety

When calling this method, you have to ensure that the pointer is convertible to a reference.

Examples

use std::ptr::NonNull;

let mut x = 0u32;
let mut ptr = NonNull::new(&mut x).expect("null pointer");

let x_ref = unsafe { ptr.as_mut() };
assert_eq!(*x_ref, 0);
*x_ref += 2;
assert_eq!(*x_ref, 2);

Trait Implementations

impl<T: ?Sized> Clone for NonNullExt<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: ?Sized> Debug for NonNullExt<T>

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

Formats the value using the given formatter.

impl<T: ?Sized> Deref for NonNullExt<T>

type Target = NonNull<T>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T: ?Sized> DerefMut for NonNullExt<T>

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: ?Sized> Hash for NonNullExt<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: ?Sized> Ord for NonNullExt<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: ?Sized> PartialEq for NonNullExt<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: ?Sized> PartialOrd for NonNullExt<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: ?Sized> Copy for NonNullExt<T>

impl<T: ?Sized> Eq for NonNullExt<T>