1 use crate::cmp
::Ordering
;
2 use crate::convert
::From
;
5 use crate::intrinsics
::assert_unsafe_precondition
;
6 use crate::marker
::Unsize
;
7 use crate::mem
::{self, MaybeUninit}
;
8 use crate::num
::NonZeroUsize
;
9 use crate::ops
::{CoerceUnsized, DispatchFromDyn}
;
10 use crate::ptr
::Unique
;
11 use crate::slice
::{self, SliceIndex}
;
13 /// `*mut T` but non-zero and [covariant].
15 /// This is often the correct thing to use when building data structures using
16 /// raw pointers, but is ultimately more dangerous to use because of its additional
17 /// properties. If you're not sure if you should use `NonNull<T>`, just use `*mut T`!
19 /// Unlike `*mut T`, the pointer must always be non-null, even if the pointer
20 /// is never dereferenced. This is so that enums may use this forbidden value
21 /// as a discriminant -- `Option<NonNull<T>>` has the same size as `*mut T`.
22 /// However the pointer may still dangle if it isn't dereferenced.
24 /// Unlike `*mut T`, `NonNull<T>` was chosen to be covariant over `T`. This makes it
25 /// possible to use `NonNull<T>` when building covariant types, but introduces the
26 /// risk of unsoundness if used in a type that shouldn't actually be covariant.
27 /// (The opposite choice was made for `*mut T` even though technically the unsoundness
28 /// could only be caused by calling unsafe functions.)
30 /// Covariance is correct for most safe abstractions, such as `Box`, `Rc`, `Arc`, `Vec`,
31 /// and `LinkedList`. This is the case because they provide a public API that follows the
32 /// normal shared XOR mutable rules of Rust.
34 /// If your type cannot safely be covariant, you must ensure it contains some
35 /// additional field to provide invariance. Often this field will be a [`PhantomData`]
36 /// type like `PhantomData<Cell<T>>` or `PhantomData<&'a mut T>`.
38 /// Notice that `NonNull<T>` has a `From` instance for `&T`. However, this does
39 /// not change the fact that mutating through a (pointer derived from a) shared
40 /// reference is undefined behavior unless the mutation happens inside an
41 /// [`UnsafeCell<T>`]. The same goes for creating a mutable reference from a shared
42 /// reference. When using this `From` instance without an `UnsafeCell<T>`,
43 /// it is your responsibility to ensure that `as_mut` is never called, and `as_ptr`
44 /// is never used for mutation.
48 /// Thanks to the [null pointer optimization],
49 /// `NonNull<T>` and `Option<NonNull<T>>`
50 /// are guaranteed to have the same size and alignment:
53 /// # use std::mem::{size_of, align_of};
54 /// use std::ptr::NonNull;
56 /// assert_eq!(size_of::<NonNull<i16>>(), size_of::<Option<NonNull<i16>>>());
57 /// assert_eq!(align_of::<NonNull<i16>>(), align_of::<Option<NonNull<i16>>>());
59 /// assert_eq!(size_of::<NonNull<str>>(), size_of::<Option<NonNull<str>>>());
60 /// assert_eq!(align_of::<NonNull<str>>(), align_of::<Option<NonNull<str>>>());
63 /// [covariant]: https://doc.rust-lang.org/reference/subtyping.html
64 /// [`PhantomData`]: crate::marker::PhantomData
65 /// [`UnsafeCell<T>`]: crate::cell::UnsafeCell
66 /// [null pointer optimization]: crate::option#representation
67 #[stable(feature = "nonnull", since = "1.25.0")]
69 #[rustc_layout_scalar_valid_range_start(1)]
70 #[rustc_nonnull_optimization_guaranteed]
71 pub struct NonNull
<T
: ?Sized
> {
75 /// `NonNull` pointers are not `Send` because the data they reference may be aliased.
76 // N.B., this impl is unnecessary, but should provide better error messages.
77 #[stable(feature = "nonnull", since = "1.25.0")]
78 impl<T
: ?Sized
> !Send
for NonNull
<T
> {}
80 /// `NonNull` pointers are not `Sync` because the data they reference may be aliased.
81 // N.B., this impl is unnecessary, but should provide better error messages.
82 #[stable(feature = "nonnull", since = "1.25.0")]
83 impl<T
: ?Sized
> !Sync
for NonNull
<T
> {}
85 impl<T
: Sized
> NonNull
<T
> {
86 /// Creates a new `NonNull` that is dangling, but well-aligned.
88 /// This is useful for initializing types which lazily allocate, like
91 /// Note that the pointer value may potentially represent a valid pointer to
92 /// a `T`, which means this must not be used as a "not yet initialized"
93 /// sentinel value. Types that lazily allocate must track initialization by
99 /// use std::ptr::NonNull;
101 /// let ptr = NonNull::<u32>::dangling();
102 /// // Important: don't try to access the value of `ptr` without
103 /// // initializing it first! The pointer is not null but isn't valid either!
105 #[stable(feature = "nonnull", since = "1.25.0")]
106 #[rustc_const_stable(feature = "const_nonnull_dangling", since = "1.36.0")]
109 pub const fn dangling() -> Self {
110 // SAFETY: mem::align_of() returns a non-zero usize which is then casted
111 // to a *mut T. Therefore, `ptr` is not null and the conditions for
112 // calling new_unchecked() are respected.
114 let ptr
= crate::ptr
::invalid_mut
::<T
>(mem
::align_of
::<T
>());
115 NonNull
::new_unchecked(ptr
)
119 /// Returns a shared references to the value. In contrast to [`as_ref`], this does not require
120 /// that the value has to be initialized.
122 /// For the mutable counterpart see [`as_uninit_mut`].
124 /// [`as_ref`]: NonNull::as_ref
125 /// [`as_uninit_mut`]: NonNull::as_uninit_mut
129 /// When calling this method, you have to ensure that all of the following is true:
131 /// * The pointer must be properly aligned.
133 /// * It must be "dereferenceable" in the sense defined in [the module documentation].
135 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
136 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
137 /// In particular, while this reference exists, the memory the pointer points to must
138 /// not get mutated (except inside `UnsafeCell`).
140 /// This applies even if the result of this method is unused!
142 /// [the module documentation]: crate::ptr#safety
145 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
146 #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
147 pub const unsafe fn as_uninit_ref
<'a
>(self) -> &'a MaybeUninit
<T
> {
148 // SAFETY: the caller must guarantee that `self` meets all the
149 // requirements for a reference.
150 unsafe { &*self.cast().as_ptr() }
153 /// Returns a unique references to the value. In contrast to [`as_mut`], this does not require
154 /// that the value has to be initialized.
156 /// For the shared counterpart see [`as_uninit_ref`].
158 /// [`as_mut`]: NonNull::as_mut
159 /// [`as_uninit_ref`]: NonNull::as_uninit_ref
163 /// When calling this method, you have to ensure that all of the following is true:
165 /// * The pointer must be properly aligned.
167 /// * It must be "dereferenceable" in the sense defined in [the module documentation].
169 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
170 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
171 /// In particular, while this reference exists, the memory the pointer points to must
172 /// not get accessed (read or written) through any other pointer.
174 /// This applies even if the result of this method is unused!
176 /// [the module documentation]: crate::ptr#safety
179 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
180 #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
181 pub const unsafe fn as_uninit_mut
<'a
>(self) -> &'a
mut MaybeUninit
<T
> {
182 // SAFETY: the caller must guarantee that `self` meets all the
183 // requirements for a reference.
184 unsafe { &mut *self.cast().as_ptr() }
188 impl<T
: ?Sized
> NonNull
<T
> {
189 /// Creates a new `NonNull`.
193 /// `ptr` must be non-null.
198 /// use std::ptr::NonNull;
200 /// let mut x = 0u32;
201 /// let ptr = unsafe { NonNull::new_unchecked(&mut x as *mut _) };
204 /// *Incorrect* usage of this function:
207 /// use std::ptr::NonNull;
209 /// // NEVER DO THAT!!! This is undefined behavior. ⚠️
210 /// let ptr = unsafe { NonNull::<u32>::new_unchecked(std::ptr::null_mut()) };
212 #[stable(feature = "nonnull", since = "1.25.0")]
213 #[rustc_const_stable(feature = "const_nonnull_new_unchecked", since = "1.25.0")]
215 pub const unsafe fn new_unchecked(ptr
: *mut T
) -> Self {
216 // SAFETY: the caller must guarantee that `ptr` is non-null.
218 assert_unsafe_precondition
!("NonNull::new_unchecked requires that the pointer is non-null", [T
: ?Sized
](ptr
: *mut T
) => !ptr
.is_null());
219 NonNull { pointer: ptr as _ }
223 /// Creates a new `NonNull` if `ptr` is non-null.
228 /// use std::ptr::NonNull;
230 /// let mut x = 0u32;
231 /// let ptr = NonNull::<u32>::new(&mut x as *mut _).expect("ptr is null!");
233 /// if let Some(ptr) = NonNull::<u32>::new(std::ptr::null_mut()) {
237 #[stable(feature = "nonnull", since = "1.25.0")]
238 #[rustc_const_unstable(feature = "const_nonnull_new", issue = "93235")]
240 pub const fn new(ptr
: *mut T
) -> Option
<Self> {
242 // SAFETY: The pointer is already checked and is not null
243 Some(unsafe { Self::new_unchecked(ptr) }
)
249 /// Performs the same functionality as [`std::ptr::from_raw_parts`], except that a
250 /// `NonNull` pointer is returned, as opposed to a raw `*const` pointer.
252 /// See the documentation of [`std::ptr::from_raw_parts`] for more details.
254 /// [`std::ptr::from_raw_parts`]: crate::ptr::from_raw_parts
255 #[unstable(feature = "ptr_metadata", issue = "81513")]
256 #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")]
258 pub const fn from_raw_parts(
259 data_address
: NonNull
<()>,
260 metadata
: <T
as super::Pointee
>::Metadata
,
262 // SAFETY: The result of `ptr::from::raw_parts_mut` is non-null because `data_address` is.
264 NonNull
::new_unchecked(super::from_raw_parts_mut(data_address
.as_ptr(), metadata
))
268 /// Decompose a (possibly wide) pointer into its address and metadata components.
270 /// The pointer can be later reconstructed with [`NonNull::from_raw_parts`].
271 #[unstable(feature = "ptr_metadata", issue = "81513")]
272 #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")]
273 #[must_use = "this returns the result of the operation, \
274 without modifying the original"]
276 pub const fn to_raw_parts(self) -> (NonNull
<()>, <T
as super::Pointee
>::Metadata
) {
277 (self.cast(), super::metadata(self.as_ptr()))
280 /// Gets the "address" portion of the pointer.
282 /// For more details see the equivalent method on a raw pointer, [`pointer::addr`].
284 /// This API and its claimed semantics are part of the Strict Provenance experiment,
285 /// see the [`ptr` module documentation][crate::ptr].
288 #[unstable(feature = "strict_provenance", issue = "95228")]
289 pub fn addr(self) -> NonZeroUsize
{
290 // SAFETY: The pointer is guaranteed by the type to be non-null,
291 // meaning that the address will be non-zero.
292 unsafe { NonZeroUsize::new_unchecked(self.pointer.addr()) }
295 /// Creates a new pointer with the given address.
297 /// For more details see the equivalent method on a raw pointer, [`pointer::with_addr`].
299 /// This API and its claimed semantics are part of the Strict Provenance experiment,
300 /// see the [`ptr` module documentation][crate::ptr].
303 #[unstable(feature = "strict_provenance", issue = "95228")]
304 pub fn with_addr(self, addr
: NonZeroUsize
) -> Self {
305 // SAFETY: The result of `ptr::from::with_addr` is non-null because `addr` is guaranteed to be non-zero.
306 unsafe { NonNull::new_unchecked(self.pointer.with_addr(addr.get()) as *mut _) }
309 /// Creates a new pointer by mapping `self`'s address to a new one.
311 /// For more details see the equivalent method on a raw pointer, [`pointer::map_addr`].
313 /// This API and its claimed semantics are part of the Strict Provenance experiment,
314 /// see the [`ptr` module documentation][crate::ptr].
317 #[unstable(feature = "strict_provenance", issue = "95228")]
318 pub fn map_addr(self, f
: impl FnOnce(NonZeroUsize
) -> NonZeroUsize
) -> Self {
319 self.with_addr(f(self.addr()))
322 /// Acquires the underlying `*mut` pointer.
327 /// use std::ptr::NonNull;
329 /// let mut x = 0u32;
330 /// let ptr = NonNull::new(&mut x).expect("ptr is null!");
332 /// let x_value = unsafe { *ptr.as_ptr() };
333 /// assert_eq!(x_value, 0);
335 /// unsafe { *ptr.as_ptr() += 2; }
336 /// let x_value = unsafe { *ptr.as_ptr() };
337 /// assert_eq!(x_value, 2);
339 #[stable(feature = "nonnull", since = "1.25.0")]
340 #[rustc_const_stable(feature = "const_nonnull_as_ptr", since = "1.32.0")]
341 #[cfg_attr(not(bootstrap), rustc_never_returns_null_ptr)]
344 pub const fn as_ptr(self) -> *mut T
{
345 self.pointer
as *mut T
348 /// Returns a shared reference to the value. If the value may be uninitialized, [`as_uninit_ref`]
349 /// must be used instead.
351 /// For the mutable counterpart see [`as_mut`].
353 /// [`as_uninit_ref`]: NonNull::as_uninit_ref
354 /// [`as_mut`]: NonNull::as_mut
358 /// When calling this method, you have to ensure that all of the following is true:
360 /// * The pointer must be properly aligned.
362 /// * It must be "dereferenceable" in the sense defined in [the module documentation].
364 /// * The pointer must point to an initialized instance of `T`.
366 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
367 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
368 /// In particular, while this reference exists, the memory the pointer points to must
369 /// not get mutated (except inside `UnsafeCell`).
371 /// This applies even if the result of this method is unused!
372 /// (The part about being initialized is not yet fully decided, but until
373 /// it is, the only safe approach is to ensure that they are indeed initialized.)
378 /// use std::ptr::NonNull;
380 /// let mut x = 0u32;
381 /// let ptr = NonNull::new(&mut x as *mut _).expect("ptr is null!");
383 /// let ref_x = unsafe { ptr.as_ref() };
384 /// println!("{ref_x}");
387 /// [the module documentation]: crate::ptr#safety
388 #[stable(feature = "nonnull", since = "1.25.0")]
389 #[rustc_const_stable(feature = "const_nonnull_as_ref", since = "1.73.0")]
392 pub const unsafe fn as_ref
<'a
>(&self) -> &'a T
{
393 // SAFETY: the caller must guarantee that `self` meets all the
394 // requirements for a reference.
395 // `cast_const` avoids a mutable raw pointer deref.
396 unsafe { &*self.as_ptr().cast_const() }
399 /// Returns a unique reference to the value. If the value may be uninitialized, [`as_uninit_mut`]
400 /// must be used instead.
402 /// For the shared counterpart see [`as_ref`].
404 /// [`as_uninit_mut`]: NonNull::as_uninit_mut
405 /// [`as_ref`]: NonNull::as_ref
409 /// When calling this method, you have to ensure that all of the following is true:
411 /// * The pointer must be properly aligned.
413 /// * It must be "dereferenceable" in the sense defined in [the module documentation].
415 /// * The pointer must point to an initialized instance of `T`.
417 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
418 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
419 /// In particular, while this reference exists, the memory the pointer points to must
420 /// not get accessed (read or written) through any other pointer.
422 /// This applies even if the result of this method is unused!
423 /// (The part about being initialized is not yet fully decided, but until
424 /// it is, the only safe approach is to ensure that they are indeed initialized.)
428 /// use std::ptr::NonNull;
430 /// let mut x = 0u32;
431 /// let mut ptr = NonNull::new(&mut x).expect("null pointer");
433 /// let x_ref = unsafe { ptr.as_mut() };
434 /// assert_eq!(*x_ref, 0);
436 /// assert_eq!(*x_ref, 2);
439 /// [the module documentation]: crate::ptr#safety
440 #[stable(feature = "nonnull", since = "1.25.0")]
441 #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
444 pub const unsafe fn as_mut
<'a
>(&mut self) -> &'a
mut T
{
445 // SAFETY: the caller must guarantee that `self` meets all the
446 // requirements for a mutable reference.
447 unsafe { &mut *self.as_ptr() }
450 /// Casts to a pointer of another type.
455 /// use std::ptr::NonNull;
457 /// let mut x = 0u32;
458 /// let ptr = NonNull::new(&mut x as *mut _).expect("null pointer");
460 /// let casted_ptr = ptr.cast::<i8>();
461 /// let raw_ptr: *mut i8 = casted_ptr.as_ptr();
463 #[stable(feature = "nonnull_cast", since = "1.27.0")]
464 #[rustc_const_stable(feature = "const_nonnull_cast", since = "1.36.0")]
465 #[must_use = "this returns the result of the operation, \
466 without modifying the original"]
468 pub const fn cast
<U
>(self) -> NonNull
<U
> {
469 // SAFETY: `self` is a `NonNull` pointer which is necessarily non-null
470 unsafe { NonNull::new_unchecked(self.as_ptr() as *mut U) }
473 /// See [`pointer::add`] for semantics and safety requirements.
475 pub(crate) const unsafe fn add(self, delta
: usize) -> Self
479 // SAFETY: We require that the delta stays in-bounds of the object, and
480 // thus it cannot become null, as that would require wrapping the
481 // address space, which no legal objects are allowed to do.
482 // And the caller promised the `delta` is sound to add.
483 unsafe { NonNull { pointer: self.pointer.add(delta) }
}
486 /// See [`pointer::sub`] for semantics and safety requirements.
488 pub(crate) const unsafe fn sub(self, delta
: usize) -> Self
492 // SAFETY: We require that the delta stays in-bounds of the object, and
493 // thus it cannot become null, as no legal objects can be allocated
494 // in such as way that the null address is part of them.
495 // And the caller promised the `delta` is sound to subtract.
496 unsafe { NonNull { pointer: self.pointer.sub(delta) }
}
499 /// See [`pointer::sub_ptr`] for semantics and safety requirements.
501 pub(crate) const unsafe fn sub_ptr(self, subtrahend
: Self) -> usize
505 // SAFETY: The caller promised that this is safe to do, and
506 // the non-nullness is irrelevant to the operation.
507 unsafe { self.pointer.sub_ptr(subtrahend.pointer) }
511 impl<T
> NonNull
<[T
]> {
512 /// Creates a non-null raw slice from a thin pointer and a length.
514 /// The `len` argument is the number of **elements**, not the number of bytes.
516 /// This function is safe, but dereferencing the return value is unsafe.
517 /// See the documentation of [`slice::from_raw_parts`] for slice safety requirements.
522 /// use std::ptr::NonNull;
524 /// // create a slice pointer when starting out with a pointer to the first element
525 /// let mut x = [5, 6, 7];
526 /// let nonnull_pointer = NonNull::new(x.as_mut_ptr()).unwrap();
527 /// let slice = NonNull::slice_from_raw_parts(nonnull_pointer, 3);
528 /// assert_eq!(unsafe { slice.as_ref()[2] }, 7);
531 /// (Note that this example artificially demonstrates a use of this method,
532 /// but `let slice = NonNull::from(&x[..]);` would be a better way to write code like this.)
533 #[stable(feature = "nonnull_slice_from_raw_parts", since = "1.70.0")]
534 #[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")]
537 pub const fn slice_from_raw_parts(data
: NonNull
<T
>, len
: usize) -> Self {
538 // SAFETY: `data` is a `NonNull` pointer which is necessarily non-null
539 unsafe { Self::new_unchecked(super::slice_from_raw_parts_mut(data.as_ptr(), len)) }
542 /// Returns the length of a non-null raw slice.
544 /// The returned value is the number of **elements**, not the number of bytes.
546 /// This function is safe, even when the non-null raw slice cannot be dereferenced to a slice
547 /// because the pointer does not have a valid address.
552 /// use std::ptr::NonNull;
554 /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
555 /// assert_eq!(slice.len(), 3);
557 #[stable(feature = "slice_ptr_len_nonnull", since = "1.63.0")]
558 #[rustc_const_stable(feature = "const_slice_ptr_len_nonnull", since = "1.63.0")]
559 #[rustc_allow_const_fn_unstable(const_slice_ptr_len)]
562 pub const fn len(self) -> usize {
566 /// Returns a non-null pointer to the slice's buffer.
571 /// #![feature(slice_ptr_get)]
572 /// use std::ptr::NonNull;
574 /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
575 /// assert_eq!(slice.as_non_null_ptr(), NonNull::<i8>::dangling());
579 #[unstable(feature = "slice_ptr_get", issue = "74265")]
580 #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")]
581 pub const fn as_non_null_ptr(self) -> NonNull
<T
> {
582 // SAFETY: We know `self` is non-null.
583 unsafe { NonNull::new_unchecked(self.as_ptr().as_mut_ptr()) }
586 /// Returns a raw pointer to the slice's buffer.
591 /// #![feature(slice_ptr_get)]
592 /// use std::ptr::NonNull;
594 /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
595 /// assert_eq!(slice.as_mut_ptr(), NonNull::<i8>::dangling().as_ptr());
599 #[unstable(feature = "slice_ptr_get", issue = "74265")]
600 #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")]
601 #[cfg_attr(not(bootstrap), rustc_never_returns_null_ptr)]
602 pub const fn as_mut_ptr(self) -> *mut T
{
603 self.as_non_null_ptr().as_ptr()
606 /// Returns a shared reference to a slice of possibly uninitialized values. In contrast to
607 /// [`as_ref`], this does not require that the value has to be initialized.
609 /// For the mutable counterpart see [`as_uninit_slice_mut`].
611 /// [`as_ref`]: NonNull::as_ref
612 /// [`as_uninit_slice_mut`]: NonNull::as_uninit_slice_mut
616 /// When calling this method, you have to ensure that all of the following is true:
618 /// * The pointer must be [valid] for reads for `ptr.len() * mem::size_of::<T>()` many bytes,
619 /// and it must be properly aligned. This means in particular:
621 /// * The entire memory range of this slice must be contained within a single allocated object!
622 /// Slices can never span across multiple allocated objects.
624 /// * The pointer must be aligned even for zero-length slices. One
625 /// reason for this is that enum layout optimizations may rely on references
626 /// (including slices of any length) being aligned and non-null to distinguish
627 /// them from other data. You can obtain a pointer that is usable as `data`
628 /// for zero-length slices using [`NonNull::dangling()`].
630 /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
631 /// See the safety documentation of [`pointer::offset`].
633 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
634 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
635 /// In particular, while this reference exists, the memory the pointer points to must
636 /// not get mutated (except inside `UnsafeCell`).
638 /// This applies even if the result of this method is unused!
640 /// See also [`slice::from_raw_parts`].
642 /// [valid]: crate::ptr#safety
645 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
646 #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
647 pub const unsafe fn as_uninit_slice
<'a
>(self) -> &'a
[MaybeUninit
<T
>] {
648 // SAFETY: the caller must uphold the safety contract for `as_uninit_slice`.
649 unsafe { slice::from_raw_parts(self.cast().as_ptr(), self.len()) }
652 /// Returns a unique reference to a slice of possibly uninitialized values. In contrast to
653 /// [`as_mut`], this does not require that the value has to be initialized.
655 /// For the shared counterpart see [`as_uninit_slice`].
657 /// [`as_mut`]: NonNull::as_mut
658 /// [`as_uninit_slice`]: NonNull::as_uninit_slice
662 /// When calling this method, you have to ensure that all of the following is true:
664 /// * The pointer must be [valid] for reads and writes for `ptr.len() * mem::size_of::<T>()`
665 /// many bytes, and it must be properly aligned. This means in particular:
667 /// * The entire memory range of this slice must be contained within a single allocated object!
668 /// Slices can never span across multiple allocated objects.
670 /// * The pointer must be aligned even for zero-length slices. One
671 /// reason for this is that enum layout optimizations may rely on references
672 /// (including slices of any length) being aligned and non-null to distinguish
673 /// them from other data. You can obtain a pointer that is usable as `data`
674 /// for zero-length slices using [`NonNull::dangling()`].
676 /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
677 /// See the safety documentation of [`pointer::offset`].
679 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
680 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
681 /// In particular, while this reference exists, the memory the pointer points to must
682 /// not get accessed (read or written) through any other pointer.
684 /// This applies even if the result of this method is unused!
686 /// See also [`slice::from_raw_parts_mut`].
688 /// [valid]: crate::ptr#safety
693 /// #![feature(allocator_api, ptr_as_uninit)]
695 /// use std::alloc::{Allocator, Layout, Global};
696 /// use std::mem::MaybeUninit;
697 /// use std::ptr::NonNull;
699 /// let memory: NonNull<[u8]> = Global.allocate(Layout::new::<[u8; 32]>())?;
700 /// // This is safe as `memory` is valid for reads and writes for `memory.len()` many bytes.
701 /// // Note that calling `memory.as_mut()` is not allowed here as the content may be uninitialized.
702 /// # #[allow(unused_variables)]
703 /// let slice: &mut [MaybeUninit<u8>] = unsafe { memory.as_uninit_slice_mut() };
704 /// # Ok::<_, std::alloc::AllocError>(())
708 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
709 #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")]
710 pub const unsafe fn as_uninit_slice_mut
<'a
>(self) -> &'a
mut [MaybeUninit
<T
>] {
711 // SAFETY: the caller must uphold the safety contract for `as_uninit_slice_mut`.
712 unsafe { slice::from_raw_parts_mut(self.cast().as_ptr(), self.len()) }
715 /// Returns a raw pointer to an element or subslice, without doing bounds
718 /// Calling this method with an out-of-bounds index or when `self` is not dereferenceable
719 /// is *[undefined behavior]* even if the resulting pointer is not used.
721 /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
726 /// #![feature(slice_ptr_get)]
727 /// use std::ptr::NonNull;
729 /// let x = &mut [1, 2, 4];
730 /// let x = NonNull::slice_from_raw_parts(NonNull::new(x.as_mut_ptr()).unwrap(), x.len());
733 /// assert_eq!(x.get_unchecked_mut(1).as_ptr(), x.as_non_null_ptr().as_ptr().add(1));
736 #[unstable(feature = "slice_ptr_get", issue = "74265")]
738 pub unsafe fn get_unchecked_mut
<I
>(self, index
: I
) -> NonNull
<I
::Output
>
742 // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds.
743 // As a consequence, the resulting pointer cannot be null.
744 unsafe { NonNull::new_unchecked(self.as_ptr().get_unchecked_mut(index)) }
748 #[stable(feature = "nonnull", since = "1.25.0")]
749 impl<T
: ?Sized
> Clone
for NonNull
<T
> {
751 fn clone(&self) -> Self {
756 #[stable(feature = "nonnull", since = "1.25.0")]
757 impl<T
: ?Sized
> Copy
for NonNull
<T
> {}
759 #[unstable(feature = "coerce_unsized", issue = "18598")]
760 impl<T
: ?Sized
, U
: ?Sized
> CoerceUnsized
<NonNull
<U
>> for NonNull
<T
> where T
: Unsize
<U
> {}
762 #[unstable(feature = "dispatch_from_dyn", issue = "none")]
763 impl<T
: ?Sized
, U
: ?Sized
> DispatchFromDyn
<NonNull
<U
>> for NonNull
<T
> where T
: Unsize
<U
> {}
765 #[stable(feature = "nonnull", since = "1.25.0")]
766 impl<T
: ?Sized
> fmt
::Debug
for NonNull
<T
> {
767 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
768 fmt
::Pointer
::fmt(&self.as_ptr(), f
)
772 #[stable(feature = "nonnull", since = "1.25.0")]
773 impl<T
: ?Sized
> fmt
::Pointer
for NonNull
<T
> {
774 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
775 fmt
::Pointer
::fmt(&self.as_ptr(), f
)
779 #[stable(feature = "nonnull", since = "1.25.0")]
780 impl<T
: ?Sized
> Eq
for NonNull
<T
> {}
782 #[stable(feature = "nonnull", since = "1.25.0")]
783 impl<T
: ?Sized
> PartialEq
for NonNull
<T
> {
785 fn eq(&self, other
: &Self) -> bool
{
786 self.as_ptr() == other
.as_ptr()
790 #[stable(feature = "nonnull", since = "1.25.0")]
791 impl<T
: ?Sized
> Ord
for NonNull
<T
> {
793 fn cmp(&self, other
: &Self) -> Ordering
{
794 self.as_ptr().cmp(&other
.as_ptr())
798 #[stable(feature = "nonnull", since = "1.25.0")]
799 impl<T
: ?Sized
> PartialOrd
for NonNull
<T
> {
801 fn partial_cmp(&self, other
: &Self) -> Option
<Ordering
> {
802 self.as_ptr().partial_cmp(&other
.as_ptr())
806 #[stable(feature = "nonnull", since = "1.25.0")]
807 impl<T
: ?Sized
> hash
::Hash
for NonNull
<T
> {
809 fn hash
<H
: hash
::Hasher
>(&self, state
: &mut H
) {
810 self.as_ptr().hash(state
)
814 #[unstable(feature = "ptr_internals", issue = "none")]
815 impl<T
: ?Sized
> From
<Unique
<T
>> for NonNull
<T
> {
817 fn from(unique
: Unique
<T
>) -> Self {
818 // SAFETY: A Unique pointer cannot be null, so the conditions for
819 // new_unchecked() are respected.
820 unsafe { NonNull::new_unchecked(unique.as_ptr()) }
824 #[stable(feature = "nonnull", since = "1.25.0")]
825 impl<T
: ?Sized
> From
<&mut T
> for NonNull
<T
> {
826 /// Converts a `&mut T` to a `NonNull<T>`.
828 /// This conversion is safe and infallible since references cannot be null.
830 fn from(reference
: &mut T
) -> Self {
831 // SAFETY: A mutable reference cannot be null.
832 unsafe { NonNull { pointer: reference as *mut T }
}
836 #[stable(feature = "nonnull", since = "1.25.0")]
837 impl<T
: ?Sized
> From
<&T
> for NonNull
<T
> {
838 /// Converts a `&T` to a `NonNull<T>`.
840 /// This conversion is safe and infallible since references cannot be null.
842 fn from(reference
: &T
) -> Self {
843 // SAFETY: A reference cannot be null, so the conditions for
844 // new_unchecked() are respected.
845 unsafe { NonNull { pointer: reference as *const T }
}