Struct Ptr

pub struct Ptr;

Pointer-related operations.

See also Mem, Slice.

Implementations

impl Ptr

Safe methods

pub const BITS: usize = 64usize

The size of a pointer in bits, for the current platform.

pub const BYTES: usize = 8usize

The size of a pointer in bytes, for the current platform.

pub const LITTLE_ENDIAN: bool = true

True if the system’s architecture is little-endian.

pub const BIG_ENDIAN: bool = false

True if the system’s architecture is big-endian.

pub fn addr_eq<T: ?Sized, U: ?Sized>(p: *const T, q: *const U) -> bool

Compares raw pointer addresses for equality, ignoring any metadata in fat pointers.

See core::ptr::addr_eq.

pub fn eq<T: ?Sized>(a: *const T, b: *const T) -> bool

Compares raw pointers for equality.

See core::ptr::eq.

pub const fn dangling<T>() -> *const T

Creates a new pointer that is dangling, but non-null and well-aligned.

See core::ptr::dangling.

pub const fn dangling_mut<T>() -> *mut T

Creates a new pointer that is dangling, but non-null and well-aligned.

See core::ptr::dangling_mut.

pub fn in_stack<T>(address: *const T, stack_size: usize) -> bool

Returns true if it’s probable the given address is in the stack, for a given stack_size.

Stack size

• https://doc.rust-lang.org/std/thread/#stack-size.

The default stack size is platform-dependent and subject to change. Currently, it is 2 MiB on all Tier-1 platforms. Note that the stack size of the main thread is not determined by Rust.

If the address is close to a stack variable address it might be stack allocated.

Example

const STACK_SIZE: usize = 2 << 20; // assume a 2 MB stack size

let in_stack: [i32; 10] = [0; 10];
let in_heap = vec![0; 10];

assert_eq!(true, Ptr::in_stack(in_stack.as_ptr(), STACK_SIZE));
assert_eq!(false, Ptr::in_stack(in_heap.as_ptr(), STACK_SIZE));

pub const fn from_mut<T: ?Sized>(r: &mut T) -> *mut T

Convert an exclusive reference to a raw pointer.

See core::ptr::from_mut.

pub const fn from_ref<T: ?Sized>(r: &T) -> *const T

Convert a shared reference to a raw pointer.

See core::ptr::from_ref.

pub fn hash<T: ?Sized, S: Hasher>(hashee: *const T, into: &mut S)

Hash a raw pointer.

See core::ptr::hash.

pub const fn null<T>() -> *const T

Creates a null raw pointer.

See core::ptr::null and <ptr>::is_null.

pub const fn null_mut<T>() -> *mut T

Creates a null mutable raw pointer.

See core::ptr::null_mut.

pub const fn size_ratio(other_size: usize) -> [usize; 2]

Returns the ratio of a usize in respect to other_size.

For example: the ratio will be (1, 1) if both sizes are equal, (2, 1) if the pointer size is double the other size, and (1, 2) if is is half the other byte size.

Examples

use devela::Ptr;

assert_eq![Ptr::size_ratio(0), [1, 0]];
assert_eq![Ptr::size_ratio(size_of::<usize>()), [1, 1]];
assert_eq![Ptr::size_ratio(size_of::<&str>()), [1, 2]];
assert_eq![Ptr::size_ratio(size_of::<String>()), [1, 3]];

#[cfg(target_pointer_width = "64")]
assert_eq![Ptr::size_ratio(size_of::<char>()), [2,1]];

Note that when other_size == 0 it returns (1, 0) which is an invalid ratio.

pub const fn slice_from_raw_parts<T>(data: *const T, len: usize) -> *const [T]

Forms a raw slice from a pointer and a length.

See core::ptr::slice_from_raw_parts, and also Slice::from_raw_parts.

pub const fn slice_from_raw_parts_mut<T>(data: *mut T, len: usize) -> *mut [T]

Forms a mutable raw slice from a mutable pointer and a length.

See core::ptr::slice_from_raw_parts_mut, and also Slice::from_raw_parts_mut.

pub fn with_exposed_provenance<T>(addr: usize) -> *const T

Converts an address back to a pointer, picking up some previously ‘exposed’ provenance.

See core::ptr::with_exposed_provenance and <ptr>::expose_provenance.

pub fn with_exposed_provenance_mut<T>(addr: usize) -> *mut T

Converts an address back to a mutable pointer, picking up some previously ‘exposed’ provenance.

See core::ptr::with_exposed_provenance_mut and <ptr>::expose_provenance.

pub fn without_provenance<T>(addr: usize) -> *const T

Creates a pointer with the given address and no provenance.

See core::ptr::without_provenance <ptr>::with_addr, and <ptr>::map_addr.

pub fn without_provenance_mut<T>(addr: usize) -> *mut T

Creates a pointer with the given address and no provenance.

See core::ptr::without_provenance_mut <ptr>::with_addr, and <ptr>::map_addr.

impl Ptr

Unsafe methods gated by unsafe_ptr

pub unsafe fn copy<T>(src: *const T, dst: *mut T, count: usize)

Available on crate feature unsafe_ptr only.

Copies count * size_of::<T>() bytes from src to dst. Can overlap.

Safety

See core::ptr::copy.

pub unsafe fn copy_nonoverlapping<T>(src: *const T, dst: *mut T, count: usize)

Available on crate feature unsafe_ptr only.

Copies count * size_of::<T>() bytes from src to dst. Must not overlap.

Safety

See core::ptr::copy_nonoverlapping.

pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T)

Available on crate feature unsafe_ptr only.

Executes the destructor (if any) of the pointed-to value.

Safety

See core::ptr::drop_in_place.

pub const unsafe fn read<T>(src: *const T) -> T

Available on crate feature unsafe_ptr only.

Reads the value from src without moving it.

Safety

See core::ptr::read.

pub const unsafe fn read_unaligned<T>(src: *const T) -> T

Available on crate feature unsafe_ptr only.

Reads the value from src without moving it.

Safety

See core::ptr::read_unaligned.

pub unsafe fn read_volatile<T>(src: *const T) -> T

Available on crate feature unsafe_ptr only.

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

Safety

See core::ptr::read_volatile.

pub unsafe fn replace<T>(dst: *mut T, src: T) -> T

Available on crate feature unsafe_ptr only.

Moves src into the pointed dst, returning the previous dst value.

Safety

See core::ptr::replace.

pub unsafe fn swap<T>(x: *mut T, y: *mut T)

Available on crate feature unsafe_ptr only.

Swaps the values at two mutable locations of the same type, without deinitializing.

Safety

See core::ptr::swap.

pub unsafe fn swap_nonoverlapping<T>(x: *mut T, y: *mut T, count: usize)

Available on crate feature unsafe_ptr only.

Swaps the two regions of memory beginning at x and y. Must not overlap.

Safety

See core::ptr::swap_nonoverlapping.

pub unsafe fn write<T>(dst: *mut T, src: T)

Available on crate feature unsafe_ptr only.

Overwrites a memory location with src without reading or dropping.

Safety

See core::ptr::write.

pub unsafe fn write_bytes<T>(dst: *mut T, val: u8, count: usize)

Available on crate feature unsafe_ptr only.

Sets count * size_of::<T>() bytes of memory starting at dst to val.

Safety

See core::ptr::write_bytes.

pub unsafe fn write_unaligned<T>(dst: *mut T, src: T)

Available on crate feature unsafe_ptr only.

Overwrites a memory location with src without reading or dropping.

Safety

See core::ptr::write_unaligned.

pub unsafe fn write_volatile<T>(dst: *mut T, src: T)

Available on crate feature unsafe_ptr only.

Performs a volatile write of a memory location with src without reading or dropping.

Safety

See core::ptr::write_volatile.