use crate::hash;
use crate::marker::Unsize;
use crate::mem::{self, MaybeUninit};
+use crate::num::NonZeroUsize;
use crate::ops::{CoerceUnsized, DispatchFromDyn};
use crate::ptr::Unique;
use crate::slice::{self, SliceIndex};
-/// `*mut T` but non-zero and covariant.
+/// `*mut T` but non-zero and [covariant].
///
/// This is often the correct thing to use when building data structures using
/// raw pointers, but is ultimately more dangerous to use because of its additional
/// it is your responsibility to ensure that `as_mut` is never called, and `as_ptr`
/// is never used for mutation.
///
+/// [covariant]: https://doc.rust-lang.org/reference/subtyping.html
/// [`PhantomData`]: crate::marker::PhantomData
/// [`UnsafeCell<T>`]: crate::cell::UnsafeCell
#[stable(feature = "nonnull", since = "1.25.0")]
// to a *mut T. Therefore, `ptr` is not null and the conditions for
// calling new_unchecked() are respected.
unsafe {
- let ptr = mem::align_of::<T>() as *mut T;
+ let ptr = crate::ptr::invalid_mut::<T>(mem::align_of::<T>());
NonNull::new_unchecked(ptr)
}
}
///
/// * The pointer must be properly aligned.
///
- /// * It must be "dereferencable" in the sense defined in [the module documentation].
+ /// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
- /// In particular, for the duration of this lifetime, the memory the pointer points to must
+ /// In particular, while this reference exists, the memory the pointer points to must
/// not get mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method is unused!
#[inline]
#[must_use]
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
- pub unsafe fn as_uninit_ref<'a>(&self) -> &'a MaybeUninit<T> {
+ #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
+ pub const unsafe fn as_uninit_ref<'a>(self) -> &'a MaybeUninit<T> {
// SAFETY: the caller must guarantee that `self` meets all the
// requirements for a reference.
unsafe { &*self.cast().as_ptr() }
///
/// * The pointer must be properly aligned.
///
- /// * It must be "dereferencable" in the sense defined in [the module documentation].
+ /// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
- /// In particular, for the duration of this lifetime, the memory the pointer points to must
+ /// In particular, while this reference exists, the memory the pointer points to must
/// not get accessed (read or written) through any other pointer.
///
/// This applies even if the result of this method is unused!
#[inline]
#[must_use]
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
- pub unsafe fn as_uninit_mut<'a>(&mut self) -> &'a mut MaybeUninit<T> {
+ #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
+ pub const unsafe fn as_uninit_mut<'a>(self) -> &'a mut MaybeUninit<T> {
// SAFETY: the caller must guarantee that `self` meets all the
// requirements for a reference.
unsafe { &mut *self.cast().as_ptr() }
/// }
/// ```
#[stable(feature = "nonnull", since = "1.25.0")]
+ #[rustc_const_unstable(feature = "const_nonnull_new", issue = "93235")]
#[inline]
- pub fn new(ptr: *mut T) -> Option<Self> {
+ pub const fn new(ptr: *mut T) -> Option<Self> {
if !ptr.is_null() {
// SAFETY: The pointer is already checked and is not null
Some(unsafe { Self::new_unchecked(ptr) })
(self.cast(), super::metadata(self.as_ptr()))
}
+ /// Gets the "address" portion of the pointer.
+ ///
+ /// For more details see the equivalent method on a raw pointer, [`pointer::addr`].
+ ///
+ /// This API and its claimed semantics are part of the Strict Provenance experiment,
+ /// see the [`ptr` module documentation][crate::ptr].
+ #[must_use]
+ #[inline]
+ #[unstable(feature = "strict_provenance", issue = "95228")]
+ pub fn addr(self) -> NonZeroUsize
+ where
+ T: Sized,
+ {
+ // SAFETY: The pointer is guaranteed by the type to be non-null,
+ // meaning that the address will be non-zero.
+ unsafe { NonZeroUsize::new_unchecked(self.pointer.addr()) }
+ }
+
+ /// Creates a new pointer with the given address.
+ ///
+ /// For more details see the equivalent method on a raw pointer, [`pointer::with_addr`].
+ ///
+ /// This API and its claimed semantics are part of the Strict Provenance experiment,
+ /// see the [`ptr` module documentation][crate::ptr].
+ #[must_use]
+ #[inline]
+ #[unstable(feature = "strict_provenance", issue = "95228")]
+ pub fn with_addr(self, addr: NonZeroUsize) -> Self
+ where
+ T: Sized,
+ {
+ // SAFETY: The result of `ptr::from::with_addr` is non-null because `addr` is guaranteed to be non-zero.
+ unsafe { NonNull::new_unchecked(self.pointer.with_addr(addr.get()) as *mut _) }
+ }
+
+ /// Creates a new pointer by mapping `self`'s address to a new one.
+ ///
+ /// For more details see the equivalent method on a raw pointer, [`pointer::map_addr`].
+ ///
+ /// This API and its claimed semantics are part of the Strict Provenance experiment,
+ /// see the [`ptr` module documentation][crate::ptr].
+ #[must_use]
+ #[inline]
+ #[unstable(feature = "strict_provenance", issue = "95228")]
+ pub fn map_addr(self, f: impl FnOnce(NonZeroUsize) -> NonZeroUsize) -> Self
+ where
+ T: Sized,
+ {
+ self.with_addr(f(self.addr()))
+ }
+
/// Acquires the underlying `*mut` pointer.
///
/// # Examples
///
/// * The pointer must be properly aligned.
///
- /// * It must be "dereferencable" in the sense defined in [the module documentation].
+ /// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * The pointer must point to an initialized instance of `T`.
///
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
- /// In particular, for the duration of this lifetime, the memory the pointer points to must
+ /// In particular, while this reference exists, the memory the pointer points to must
/// not get mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method is unused!
/// let ptr = NonNull::new(&mut x as *mut _).expect("ptr is null!");
///
/// let ref_x = unsafe { ptr.as_ref() };
- /// println!("{}", ref_x);
+ /// println!("{ref_x}");
/// ```
///
/// [the module documentation]: crate::ptr#safety
#[stable(feature = "nonnull", since = "1.25.0")]
+ #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
#[must_use]
#[inline]
- pub unsafe fn as_ref<'a>(&self) -> &'a T {
+ pub const unsafe fn as_ref<'a>(&self) -> &'a T {
// SAFETY: the caller must guarantee that `self` meets all the
// requirements for a reference.
unsafe { &*self.as_ptr() }
///
/// * The pointer must be properly aligned.
///
- /// * It must be "dereferencable" in the sense defined in [the module documentation].
+ /// * It must be "dereferenceable" in the sense defined in [the module documentation].
///
/// * The pointer must point to an initialized instance of `T`.
///
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
- /// In particular, for the duration of this lifetime, the memory the pointer points to must
+ /// In particular, while this reference exists, the memory the pointer points to must
/// not get accessed (read or written) through any other pointer.
///
/// This applies even if the result of this method is unused!
///
/// [the module documentation]: crate::ptr#safety
#[stable(feature = "nonnull", since = "1.25.0")]
+ #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
#[must_use]
#[inline]
- pub unsafe fn as_mut<'a>(&mut self) -> &'a mut T {
+ pub const unsafe fn as_mut<'a>(&mut self) -> &'a mut T {
// SAFETY: the caller must guarantee that `self` meets all the
// requirements for a mutable reference.
unsafe { &mut *self.as_ptr() }
/// # Examples
///
/// ```rust
- /// #![feature(slice_ptr_len, nonnull_slice_from_raw_parts)]
+ /// #![feature(nonnull_slice_from_raw_parts)]
/// use std::ptr::NonNull;
///
/// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
/// assert_eq!(slice.len(), 3);
/// ```
- #[unstable(feature = "slice_ptr_len", issue = "71146")]
- #[rustc_const_unstable(feature = "const_slice_ptr_len", issue = "71146")]
+ #[stable(feature = "slice_ptr_len_nonnull", since = "1.63.0")]
+ #[rustc_const_stable(feature = "const_slice_ptr_len_nonnull", since = "1.63.0")]
+ #[rustc_allow_const_fn_unstable(const_slice_ptr_len)]
#[must_use]
#[inline]
pub const fn len(self) -> usize {
/// use std::ptr::NonNull;
///
/// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
- /// assert_eq!(slice.as_non_null_ptr(), NonNull::new(1 as *mut i8).unwrap());
+ /// assert_eq!(slice.as_non_null_ptr(), NonNull::<i8>::dangling());
/// ```
#[inline]
#[must_use]
/// use std::ptr::NonNull;
///
/// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
- /// assert_eq!(slice.as_mut_ptr(), 1 as *mut i8);
+ /// assert_eq!(slice.as_mut_ptr(), NonNull::<i8>::dangling().as_ptr());
/// ```
#[inline]
#[must_use]
///
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
- /// In particular, for the duration of this lifetime, the memory the pointer points to must
+ /// In particular, while this reference exists, the memory the pointer points to must
/// not get mutated (except inside `UnsafeCell`).
///
/// This applies even if the result of this method is unused!
#[inline]
#[must_use]
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
- pub unsafe fn as_uninit_slice<'a>(&self) -> &'a [MaybeUninit<T>] {
+ #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
+ pub const unsafe fn as_uninit_slice<'a>(self) -> &'a [MaybeUninit<T>] {
// SAFETY: the caller must uphold the safety contract for `as_uninit_slice`.
unsafe { slice::from_raw_parts(self.cast().as_ptr(), self.len()) }
}
///
/// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
/// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
- /// In particular, for the duration of this lifetime, the memory the pointer points to must
+ /// In particular, while this reference exists, the memory the pointer points to must
/// not get accessed (read or written) through any other pointer.
///
/// This applies even if the result of this method is unused!
#[inline]
#[must_use]
#[unstable(feature = "ptr_as_uninit", issue = "75402")]
- pub unsafe fn as_uninit_slice_mut<'a>(&self) -> &'a mut [MaybeUninit<T>] {
+ #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
+ pub const unsafe fn as_uninit_slice_mut<'a>(self) -> &'a mut [MaybeUninit<T>] {
// SAFETY: the caller must uphold the safety contract for `as_uninit_slice_mut`.
unsafe { slice::from_raw_parts_mut(self.cast().as_ptr(), self.len()) }
}
/// Returns a raw pointer to an element or subslice, without doing bounds
/// checking.
///
- /// Calling this method with an out-of-bounds index or when `self` is not dereferencable
+ /// Calling this method with an out-of-bounds index or when `self` is not dereferenceable
/// is *[undefined behavior]* even if the resulting pointer is not used.
///
/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
/// }
/// ```
#[unstable(feature = "slice_ptr_get", issue = "74265")]
+ #[rustc_const_unstable(feature = "const_slice_index", issue = "none")]
#[inline]
- pub unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output>
+ pub const unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output>
where
- I: SliceIndex<[T]>,
+ I: ~const SliceIndex<[T]>,
{
- // SAFETY: the caller ensures that `self` is dereferencable and `index` in-bounds.
+ // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds.
// As a consequence, the resulting pointer cannot be null.
unsafe { NonNull::new_unchecked(self.as_ptr().get_unchecked_mut(index)) }
}
}
#[stable(feature = "nonnull", since = "1.25.0")]
-impl<T: ?Sized> Clone for NonNull<T> {
+#[rustc_const_unstable(feature = "const_clone", issue = "91805")]
+impl<T: ?Sized> const Clone for NonNull<T> {
#[inline]
fn clone(&self) -> Self {
*self
#[stable(feature = "nonnull", since = "1.25.0")]
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
impl<T: ?Sized> const From<&mut T> for NonNull<T> {
+ /// Converts a `&mut T` to a `NonNull<T>`.
+ ///
+ /// This conversion is safe and infallible since references cannot be null.
#[inline]
fn from(reference: &mut T) -> Self {
// SAFETY: A mutable reference cannot be null.
#[stable(feature = "nonnull", since = "1.25.0")]
#[rustc_const_unstable(feature = "const_convert", issue = "88674")]
impl<T: ?Sized> const From<&T> for NonNull<T> {
+ /// Converts a `&T` to a `NonNull<T>`.
+ ///
+ /// This conversion is safe and infallible since references cannot be null.
#[inline]
fn from(reference: &T) -> Self {
// SAFETY: A reference cannot be null, so the conditions for
projects / rustc.git / blobdiff