| use crate::cmp::Ordering; |
| use crate::convert::From; |
| use crate::fmt; |
| use crate::hash; |
| use crate::intrinsics::assert_unsafe_precondition; |
| 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]. |
| /// |
| /// 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 |
| /// properties. If you're not sure if you should use `NonNull<T>`, just use `*mut T`! |
| /// |
| /// Unlike `*mut T`, the pointer must always be non-null, even if the pointer |
| /// is never dereferenced. This is so that enums may use this forbidden value |
| /// as a discriminant -- `Option<NonNull<T>>` has the same size as `*mut T`. |
| /// However the pointer may still dangle if it isn't dereferenced. |
| /// |
| /// Unlike `*mut T`, `NonNull<T>` was chosen to be covariant over `T`. This makes it |
| /// possible to use `NonNull<T>` when building covariant types, but introduces the |
| /// risk of unsoundness if used in a type that shouldn't actually be covariant. |
| /// (The opposite choice was made for `*mut T` even though technically the unsoundness |
| /// could only be caused by calling unsafe functions.) |
| /// |
| /// Covariance is correct for most safe abstractions, such as `Box`, `Rc`, `Arc`, `Vec`, |
| /// and `LinkedList`. This is the case because they provide a public API that follows the |
| /// normal shared XOR mutable rules of Rust. |
| /// |
| /// If your type cannot safely be covariant, you must ensure it contains some |
| /// additional field to provide invariance. Often this field will be a [`PhantomData`] |
| /// type like `PhantomData<Cell<T>>` or `PhantomData<&'a mut T>`. |
| /// |
| /// Notice that `NonNull<T>` has a `From` instance for `&T`. However, this does |
| /// not change the fact that mutating through a (pointer derived from a) shared |
| /// reference is undefined behavior unless the mutation happens inside an |
| /// [`UnsafeCell<T>`]. The same goes for creating a mutable reference from a shared |
| /// reference. When using this `From` instance without an `UnsafeCell<T>`, |
| /// 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")] |
| #[repr(transparent)] |
| #[rustc_layout_scalar_valid_range_start(1)] |
| #[rustc_nonnull_optimization_guaranteed] |
| pub struct NonNull<T: ?Sized> { |
| pointer: *const T, |
| } |
| |
| /// `NonNull` pointers are not `Send` because the data they reference may be aliased. |
| // N.B., this impl is unnecessary, but should provide better error messages. |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> !Send for NonNull<T> {} |
| |
| /// `NonNull` pointers are not `Sync` because the data they reference may be aliased. |
| // N.B., this impl is unnecessary, but should provide better error messages. |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> !Sync for NonNull<T> {} |
| |
| impl<T: Sized> NonNull<T> { |
| /// Creates a new `NonNull` that is dangling, but well-aligned. |
| /// |
| /// This is useful for initializing types which lazily allocate, like |
| /// `Vec::new` does. |
| /// |
| /// Note that the pointer value may potentially represent a valid pointer to |
| /// a `T`, which means this must not be used as a "not yet initialized" |
| /// sentinel value. Types that lazily allocate must track initialization by |
| /// some other means. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::ptr::NonNull; |
| /// |
| /// let ptr = NonNull::<u32>::dangling(); |
| /// // Important: don't try to access the value of `ptr` without |
| /// // initializing it first! The pointer is not null but isn't valid either! |
| /// ``` |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| #[rustc_const_stable(feature = "const_nonnull_dangling", since = "1.36.0")] |
| #[must_use] |
| #[inline] |
| pub const fn dangling() -> Self { |
| // SAFETY: mem::align_of() returns a non-zero usize which is then casted |
| // to a *mut T. Therefore, `ptr` is not null and the conditions for |
| // calling new_unchecked() are respected. |
| unsafe { |
| let ptr = crate::ptr::invalid_mut::<T>(mem::align_of::<T>()); |
| NonNull::new_unchecked(ptr) |
| } |
| } |
| |
| /// Returns a shared references to the value. In contrast to [`as_ref`], this does not require |
| /// that the value has to be initialized. |
| /// |
| /// For the mutable counterpart see [`as_uninit_mut`]. |
| /// |
| /// [`as_ref`]: NonNull::as_ref |
| /// [`as_uninit_mut`]: NonNull::as_uninit_mut |
| /// |
| /// # Safety |
| /// |
| /// When calling this method, you have to ensure that all of the following is true: |
| /// |
| /// * The pointer must be properly aligned. |
| /// |
| /// * 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, 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! |
| /// |
| /// [the module documentation]: crate::ptr#safety |
| #[inline] |
| #[must_use] |
| #[unstable(feature = "ptr_as_uninit", issue = "75402")] |
| #[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() } |
| } |
| |
| /// Returns a unique references to the value. In contrast to [`as_mut`], this does not require |
| /// that the value has to be initialized. |
| /// |
| /// For the shared counterpart see [`as_uninit_ref`]. |
| /// |
| /// [`as_mut`]: NonNull::as_mut |
| /// [`as_uninit_ref`]: NonNull::as_uninit_ref |
| /// |
| /// # Safety |
| /// |
| /// When calling this method, you have to ensure that all of the following is true: |
| /// |
| /// * The pointer must be properly aligned. |
| /// |
| /// * 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, 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 |
| #[inline] |
| #[must_use] |
| #[unstable(feature = "ptr_as_uninit", issue = "75402")] |
| #[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() } |
| } |
| } |
| |
| impl<T: ?Sized> NonNull<T> { |
| /// Creates a new `NonNull`. |
| /// |
| /// # Safety |
| /// |
| /// `ptr` must be non-null. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::ptr::NonNull; |
| /// |
| /// let mut x = 0u32; |
| /// let ptr = unsafe { NonNull::new_unchecked(&mut x as *mut _) }; |
| /// ``` |
| /// |
| /// *Incorrect* usage of this function: |
| /// |
| /// ```rust,no_run |
| /// use std::ptr::NonNull; |
| /// |
| /// // NEVER DO THAT!!! This is undefined behavior. ⚠️ |
| /// let ptr = unsafe { NonNull::<u32>::new_unchecked(std::ptr::null_mut()) }; |
| /// ``` |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| #[rustc_const_stable(feature = "const_nonnull_new_unchecked", since = "1.25.0")] |
| #[inline] |
| pub const unsafe fn new_unchecked(ptr: *mut T) -> Self { |
| // SAFETY: the caller must guarantee that `ptr` is non-null. |
| unsafe { |
| assert_unsafe_precondition!("NonNull::new_unchecked requires that the pointer is non-null", [T: ?Sized](ptr: *mut T) => !ptr.is_null()); |
| NonNull { pointer: ptr as _ } |
| } |
| } |
| |
| /// Creates a new `NonNull` if `ptr` is non-null. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::ptr::NonNull; |
| /// |
| /// let mut x = 0u32; |
| /// let ptr = NonNull::<u32>::new(&mut x as *mut _).expect("ptr is null!"); |
| /// |
| /// if let Some(ptr) = NonNull::<u32>::new(std::ptr::null_mut()) { |
| /// unreachable!(); |
| /// } |
| /// ``` |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| #[rustc_const_unstable(feature = "const_nonnull_new", issue = "93235")] |
| #[inline] |
| 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) }) |
| } else { |
| None |
| } |
| } |
| |
| /// Performs the same functionality as [`std::ptr::from_raw_parts`], except that a |
| /// `NonNull` pointer is returned, as opposed to a raw `*const` pointer. |
| /// |
| /// See the documentation of [`std::ptr::from_raw_parts`] for more details. |
| /// |
| /// [`std::ptr::from_raw_parts`]: crate::ptr::from_raw_parts |
| #[unstable(feature = "ptr_metadata", issue = "81513")] |
| #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] |
| #[inline] |
| pub const fn from_raw_parts( |
| data_address: NonNull<()>, |
| metadata: <T as super::Pointee>::Metadata, |
| ) -> NonNull<T> { |
| // SAFETY: The result of `ptr::from::raw_parts_mut` is non-null because `data_address` is. |
| unsafe { |
| NonNull::new_unchecked(super::from_raw_parts_mut(data_address.as_ptr(), metadata)) |
| } |
| } |
| |
| /// Decompose a (possibly wide) pointer into its address and metadata components. |
| /// |
| /// The pointer can be later reconstructed with [`NonNull::from_raw_parts`]. |
| #[unstable(feature = "ptr_metadata", issue = "81513")] |
| #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] |
| #[must_use = "this returns the result of the operation, \ |
| without modifying the original"] |
| #[inline] |
| pub const fn to_raw_parts(self) -> (NonNull<()>, <T as super::Pointee>::Metadata) { |
| (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 |
| /// |
| /// ``` |
| /// use std::ptr::NonNull; |
| /// |
| /// let mut x = 0u32; |
| /// let ptr = NonNull::new(&mut x).expect("ptr is null!"); |
| /// |
| /// let x_value = unsafe { *ptr.as_ptr() }; |
| /// assert_eq!(x_value, 0); |
| /// |
| /// unsafe { *ptr.as_ptr() += 2; } |
| /// let x_value = unsafe { *ptr.as_ptr() }; |
| /// assert_eq!(x_value, 2); |
| /// ``` |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| #[rustc_const_stable(feature = "const_nonnull_as_ptr", since = "1.32.0")] |
| #[must_use] |
| #[inline(always)] |
| pub const fn as_ptr(self) -> *mut T { |
| self.pointer as *mut 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`]. |
| /// |
| /// [`as_uninit_ref`]: NonNull::as_uninit_ref |
| /// [`as_mut`]: NonNull::as_mut |
| /// |
| /// # Safety |
| /// |
| /// When calling this method, you have to ensure that all of the following is true: |
| /// |
| /// * The pointer must be properly aligned. |
| /// |
| /// * 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, 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! |
| /// (The part about being initialized is not yet fully decided, but until |
| /// it is, the only safe approach is to ensure that they are indeed initialized.) |
| /// |
| /// # 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}"); |
| /// ``` |
| /// |
| /// [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(always)] |
| 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() } |
| } |
| |
| /// 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`]. |
| /// |
| /// [`as_uninit_mut`]: NonNull::as_uninit_mut |
| /// [`as_ref`]: NonNull::as_ref |
| /// |
| /// # Safety |
| /// |
| /// When calling this method, you have to ensure that all of the following is true: |
| /// |
| /// * The pointer must be properly aligned. |
| /// |
| /// * 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, 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 part about being initialized is not yet fully decided, but until |
| /// it is, the only safe approach is to ensure that they are indeed initialized.) |
| /// # 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); |
| /// ``` |
| /// |
| /// [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(always)] |
| 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() } |
| } |
| |
| /// Casts to a pointer of another type. |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// use std::ptr::NonNull; |
| /// |
| /// let mut x = 0u32; |
| /// let ptr = NonNull::new(&mut x as *mut _).expect("null pointer"); |
| /// |
| /// let casted_ptr = ptr.cast::<i8>(); |
| /// let raw_ptr: *mut i8 = casted_ptr.as_ptr(); |
| /// ``` |
| #[stable(feature = "nonnull_cast", since = "1.27.0")] |
| #[rustc_const_stable(feature = "const_nonnull_cast", since = "1.36.0")] |
| #[must_use = "this returns the result of the operation, \ |
| without modifying the original"] |
| #[inline] |
| pub const fn cast<U>(self) -> NonNull<U> { |
| // SAFETY: `self` is a `NonNull` pointer which is necessarily non-null |
| unsafe { NonNull::new_unchecked(self.as_ptr() as *mut U) } |
| } |
| } |
| |
| impl<T> NonNull<[T]> { |
| /// Creates a non-null raw slice from a thin pointer and a length. |
| /// |
| /// The `len` argument is the number of **elements**, not the number of bytes. |
| /// |
| /// This function is safe, but dereferencing the return value is unsafe. |
| /// See the documentation of [`slice::from_raw_parts`] for slice safety requirements. |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// #![feature(nonnull_slice_from_raw_parts)] |
| /// |
| /// use std::ptr::NonNull; |
| /// |
| /// // create a slice pointer when starting out with a pointer to the first element |
| /// let mut x = [5, 6, 7]; |
| /// let nonnull_pointer = NonNull::new(x.as_mut_ptr()).unwrap(); |
| /// let slice = NonNull::slice_from_raw_parts(nonnull_pointer, 3); |
| /// assert_eq!(unsafe { slice.as_ref()[2] }, 7); |
| /// ``` |
| /// |
| /// (Note that this example artificially demonstrates a use of this method, |
| /// but `let slice = NonNull::from(&x[..]);` would be a better way to write code like this.) |
| #[unstable(feature = "nonnull_slice_from_raw_parts", issue = "71941")] |
| #[rustc_const_unstable(feature = "const_nonnull_slice_from_raw_parts", issue = "71941")] |
| #[must_use] |
| #[inline] |
| pub const fn slice_from_raw_parts(data: NonNull<T>, len: usize) -> Self { |
| // SAFETY: `data` is a `NonNull` pointer which is necessarily non-null |
| unsafe { Self::new_unchecked(super::slice_from_raw_parts_mut(data.as_ptr(), len)) } |
| } |
| |
| /// Returns the length of a non-null raw slice. |
| /// |
| /// The returned value is the number of **elements**, not the number of bytes. |
| /// |
| /// This function is safe, even when the non-null raw slice cannot be dereferenced to a slice |
| /// because the pointer does not have a valid address. |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// #![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); |
| /// ``` |
| #[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 { |
| self.as_ptr().len() |
| } |
| |
| /// Returns a non-null pointer to the slice's buffer. |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// #![feature(slice_ptr_get, nonnull_slice_from_raw_parts)] |
| /// use std::ptr::NonNull; |
| /// |
| /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3); |
| /// assert_eq!(slice.as_non_null_ptr(), NonNull::<i8>::dangling()); |
| /// ``` |
| #[inline] |
| #[must_use] |
| #[unstable(feature = "slice_ptr_get", issue = "74265")] |
| #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")] |
| pub const fn as_non_null_ptr(self) -> NonNull<T> { |
| // SAFETY: We know `self` is non-null. |
| unsafe { NonNull::new_unchecked(self.as_ptr().as_mut_ptr()) } |
| } |
| |
| /// Returns a raw pointer to the slice's buffer. |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// #![feature(slice_ptr_get, nonnull_slice_from_raw_parts)] |
| /// use std::ptr::NonNull; |
| /// |
| /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3); |
| /// assert_eq!(slice.as_mut_ptr(), NonNull::<i8>::dangling().as_ptr()); |
| /// ``` |
| #[inline] |
| #[must_use] |
| #[unstable(feature = "slice_ptr_get", issue = "74265")] |
| #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")] |
| pub const fn as_mut_ptr(self) -> *mut T { |
| self.as_non_null_ptr().as_ptr() |
| } |
| |
| /// Returns a shared reference to a slice of possibly uninitialized values. In contrast to |
| /// [`as_ref`], this does not require that the value has to be initialized. |
| /// |
| /// For the mutable counterpart see [`as_uninit_slice_mut`]. |
| /// |
| /// [`as_ref`]: NonNull::as_ref |
| /// [`as_uninit_slice_mut`]: NonNull::as_uninit_slice_mut |
| /// |
| /// # Safety |
| /// |
| /// When calling this method, you have to ensure that all of the following is true: |
| /// |
| /// * The pointer must be [valid] for reads for `ptr.len() * mem::size_of::<T>()` many bytes, |
| /// and it must be properly aligned. This means in particular: |
| /// |
| /// * The entire memory range of this slice must be contained within a single allocated object! |
| /// Slices can never span across multiple allocated objects. |
| /// |
| /// * The pointer must be aligned even for zero-length slices. One |
| /// reason for this is that enum layout optimizations may rely on references |
| /// (including slices of any length) being aligned and non-null to distinguish |
| /// them from other data. You can obtain a pointer that is usable as `data` |
| /// for zero-length slices using [`NonNull::dangling()`]. |
| /// |
| /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`. |
| /// See the safety documentation of [`pointer::offset`]. |
| /// |
| /// * 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, 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! |
| /// |
| /// See also [`slice::from_raw_parts`]. |
| /// |
| /// [valid]: crate::ptr#safety |
| #[inline] |
| #[must_use] |
| #[unstable(feature = "ptr_as_uninit", issue = "75402")] |
| #[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()) } |
| } |
| |
| /// Returns a unique reference to a slice of possibly uninitialized values. In contrast to |
| /// [`as_mut`], this does not require that the value has to be initialized. |
| /// |
| /// For the shared counterpart see [`as_uninit_slice`]. |
| /// |
| /// [`as_mut`]: NonNull::as_mut |
| /// [`as_uninit_slice`]: NonNull::as_uninit_slice |
| /// |
| /// # Safety |
| /// |
| /// When calling this method, you have to ensure that all of the following is true: |
| /// |
| /// * The pointer must be [valid] for reads and writes for `ptr.len() * mem::size_of::<T>()` |
| /// many bytes, and it must be properly aligned. This means in particular: |
| /// |
| /// * The entire memory range of this slice must be contained within a single allocated object! |
| /// Slices can never span across multiple allocated objects. |
| /// |
| /// * The pointer must be aligned even for zero-length slices. One |
| /// reason for this is that enum layout optimizations may rely on references |
| /// (including slices of any length) being aligned and non-null to distinguish |
| /// them from other data. You can obtain a pointer that is usable as `data` |
| /// for zero-length slices using [`NonNull::dangling()`]. |
| /// |
| /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`. |
| /// See the safety documentation of [`pointer::offset`]. |
| /// |
| /// * 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, 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! |
| /// |
| /// See also [`slice::from_raw_parts_mut`]. |
| /// |
| /// [valid]: crate::ptr#safety |
| /// |
| /// # Examples |
| /// |
| /// ```rust |
| /// #![feature(allocator_api, ptr_as_uninit)] |
| /// |
| /// use std::alloc::{Allocator, Layout, Global}; |
| /// use std::mem::MaybeUninit; |
| /// use std::ptr::NonNull; |
| /// |
| /// let memory: NonNull<[u8]> = Global.allocate(Layout::new::<[u8; 32]>())?; |
| /// // This is safe as `memory` is valid for reads and writes for `memory.len()` many bytes. |
| /// // Note that calling `memory.as_mut()` is not allowed here as the content may be uninitialized. |
| /// # #[allow(unused_variables)] |
| /// let slice: &mut [MaybeUninit<u8>] = unsafe { memory.as_uninit_slice_mut() }; |
| /// # Ok::<_, std::alloc::AllocError>(()) |
| /// ``` |
| #[inline] |
| #[must_use] |
| #[unstable(feature = "ptr_as_uninit", issue = "75402")] |
| #[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 dereferenceable |
| /// is *[undefined behavior]* even if the resulting pointer is not used. |
| /// |
| /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html |
| /// |
| /// # Examples |
| /// |
| /// ``` |
| /// #![feature(slice_ptr_get, nonnull_slice_from_raw_parts)] |
| /// use std::ptr::NonNull; |
| /// |
| /// let x = &mut [1, 2, 4]; |
| /// let x = NonNull::slice_from_raw_parts(NonNull::new(x.as_mut_ptr()).unwrap(), x.len()); |
| /// |
| /// unsafe { |
| /// assert_eq!(x.get_unchecked_mut(1).as_ptr(), x.as_non_null_ptr().as_ptr().add(1)); |
| /// } |
| /// ``` |
| #[unstable(feature = "slice_ptr_get", issue = "74265")] |
| #[rustc_const_unstable(feature = "const_slice_index", issue = "none")] |
| #[inline] |
| pub const unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output> |
| where |
| I: ~const SliceIndex<[T]>, |
| { |
| // 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")] |
| #[rustc_const_unstable(feature = "const_clone", issue = "91805")] |
| impl<T: ?Sized> const Clone for NonNull<T> { |
| #[inline(always)] |
| fn clone(&self) -> Self { |
| *self |
| } |
| } |
| |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> Copy for NonNull<T> {} |
| |
| #[unstable(feature = "coerce_unsized", issue = "27732")] |
| impl<T: ?Sized, U: ?Sized> CoerceUnsized<NonNull<U>> for NonNull<T> where T: Unsize<U> {} |
| |
| #[unstable(feature = "dispatch_from_dyn", issue = "none")] |
| impl<T: ?Sized, U: ?Sized> DispatchFromDyn<NonNull<U>> for NonNull<T> where T: Unsize<U> {} |
| |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> fmt::Debug for NonNull<T> { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| fmt::Pointer::fmt(&self.as_ptr(), f) |
| } |
| } |
| |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> fmt::Pointer for NonNull<T> { |
| fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { |
| fmt::Pointer::fmt(&self.as_ptr(), f) |
| } |
| } |
| |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> Eq for NonNull<T> {} |
| |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> PartialEq for NonNull<T> { |
| #[inline] |
| fn eq(&self, other: &Self) -> bool { |
| self.as_ptr() == other.as_ptr() |
| } |
| } |
| |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> Ord for NonNull<T> { |
| #[inline] |
| fn cmp(&self, other: &Self) -> Ordering { |
| self.as_ptr().cmp(&other.as_ptr()) |
| } |
| } |
| |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> PartialOrd for NonNull<T> { |
| #[inline] |
| fn partial_cmp(&self, other: &Self) -> Option<Ordering> { |
| self.as_ptr().partial_cmp(&other.as_ptr()) |
| } |
| } |
| |
| #[stable(feature = "nonnull", since = "1.25.0")] |
| impl<T: ?Sized> hash::Hash for NonNull<T> { |
| #[inline] |
| fn hash<H: hash::Hasher>(&self, state: &mut H) { |
| self.as_ptr().hash(state) |
| } |
| } |
| |
| #[unstable(feature = "ptr_internals", issue = "none")] |
| #[rustc_const_unstable(feature = "const_convert", issue = "88674")] |
| impl<T: ?Sized> const From<Unique<T>> for NonNull<T> { |
| #[inline] |
| fn from(unique: Unique<T>) -> Self { |
| // SAFETY: A Unique pointer cannot be null, so the conditions for |
| // new_unchecked() are respected. |
| unsafe { NonNull::new_unchecked(unique.as_ptr()) } |
| } |
| } |
| |
| #[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. |
| unsafe { NonNull { pointer: reference as *mut T } } |
| } |
| } |
| |
| #[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 |
| // new_unchecked() are respected. |
| unsafe { NonNull { pointer: reference as *const T } } |
| } |
| } |