1 use crate::cmp
::Ordering
;
2 use crate::convert
::From
;
5 use crate::marker
::Unsize
;
6 use crate::mem
::{self, MaybeUninit}
;
7 use crate::ops
::{CoerceUnsized, DispatchFromDyn}
;
8 use crate::ptr
::Unique
;
9 use crate::slice
::{self, SliceIndex}
;
11 /// `*mut T` but non-zero and covariant.
13 /// This is often the correct thing to use when building data structures using
14 /// raw pointers, but is ultimately more dangerous to use because of its additional
15 /// properties. If you're not sure if you should use `NonNull<T>`, just use `*mut T`!
17 /// Unlike `*mut T`, the pointer must always be non-null, even if the pointer
18 /// is never dereferenced. This is so that enums may use this forbidden value
19 /// as a discriminant -- `Option<NonNull<T>>` has the same size as `*mut T`.
20 /// However the pointer may still dangle if it isn't dereferenced.
22 /// Unlike `*mut T`, `NonNull<T>` is covariant over `T`. If this is incorrect
23 /// for your use case, you should include some [`PhantomData`] in your type to
24 /// provide invariance, such as `PhantomData<Cell<T>>` or `PhantomData<&'a mut T>`.
25 /// Usually this won't be necessary; covariance is correct for most safe abstractions,
26 /// such as `Box`, `Rc`, `Arc`, `Vec`, and `LinkedList`. This is the case because they
27 /// provide a public API that follows the normal shared XOR mutable rules of Rust.
29 /// Notice that `NonNull<T>` has a `From` instance for `&T`. However, this does
30 /// not change the fact that mutating through a (pointer derived from a) shared
31 /// reference is undefined behavior unless the mutation happens inside an
32 /// [`UnsafeCell<T>`]. The same goes for creating a mutable reference from a shared
33 /// reference. When using this `From` instance without an `UnsafeCell<T>`,
34 /// it is your responsibility to ensure that `as_mut` is never called, and `as_ptr`
35 /// is never used for mutation.
37 /// [`PhantomData`]: crate::marker::PhantomData
38 /// [`UnsafeCell<T>`]: crate::cell::UnsafeCell
39 #[stable(feature = "nonnull", since = "1.25.0")]
41 #[rustc_layout_scalar_valid_range_start(1)]
42 #[rustc_nonnull_optimization_guaranteed]
43 pub struct NonNull
<T
: ?Sized
> {
47 /// `NonNull` pointers are not `Send` because the data they reference may be aliased.
48 // N.B., this impl is unnecessary, but should provide better error messages.
49 #[stable(feature = "nonnull", since = "1.25.0")]
50 impl<T
: ?Sized
> !Send
for NonNull
<T
> {}
52 /// `NonNull` pointers are not `Sync` because the data they reference may be aliased.
53 // N.B., this impl is unnecessary, but should provide better error messages.
54 #[stable(feature = "nonnull", since = "1.25.0")]
55 impl<T
: ?Sized
> !Sync
for NonNull
<T
> {}
57 impl<T
: Sized
> NonNull
<T
> {
58 /// Creates a new `NonNull` that is dangling, but well-aligned.
60 /// This is useful for initializing types which lazily allocate, like
63 /// Note that the pointer value may potentially represent a valid pointer to
64 /// a `T`, which means this must not be used as a "not yet initialized"
65 /// sentinel value. Types that lazily allocate must track initialization by
67 #[stable(feature = "nonnull", since = "1.25.0")]
68 #[rustc_const_stable(feature = "const_nonnull_dangling", since = "1.32.0")]
70 pub const fn dangling() -> Self {
71 // SAFETY: mem::align_of() returns a non-zero usize which is then casted
72 // to a *mut T. Therefore, `ptr` is not null and the conditions for
73 // calling new_unchecked() are respected.
75 let ptr
= mem
::align_of
::<T
>() as *mut T
;
76 NonNull
::new_unchecked(ptr
)
80 /// Returns a shared references to the value. In contrast to [`as_ref`], this does not require
81 /// that the value has to be initialized.
83 /// For the mutable counterpart see [`as_uninit_mut`].
85 /// [`as_ref`]: NonNull::as_ref
86 /// [`as_uninit_mut`]: NonNull::as_uninit_mut
90 /// When calling this method, you have to ensure that all of the following is true:
92 /// * The pointer must be properly aligned.
94 /// * It must be "dereferencable" in the sense defined in [the module documentation].
96 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
97 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
98 /// In particular, for the duration of this lifetime, the memory the pointer points to must
99 /// not get mutated (except inside `UnsafeCell`).
101 /// This applies even if the result of this method is unused!
103 /// [the module documentation]: crate::ptr#safety
105 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
106 pub unsafe fn as_uninit_ref(&self) -> &MaybeUninit
<T
> {
107 // SAFETY: the caller must guarantee that `self` meets all the
108 // requirements for a reference.
109 unsafe { &*self.cast().as_ptr() }
112 /// Returns a unique references to the value. In contrast to [`as_mut`], this does not require
113 /// that the value has to be initialized.
115 /// For the shared counterpart see [`as_uninit_ref`].
117 /// [`as_mut`]: NonNull::as_mut
118 /// [`as_uninit_ref`]: NonNull::as_uninit_ref
122 /// When calling this method, you have to ensure that all of the following is true:
124 /// * The pointer must be properly aligned.
126 /// * It must be "dereferencable" in the sense defined in [the module documentation].
128 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
129 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
130 /// In particular, for the duration of this lifetime, the memory the pointer points to must
131 /// not get accessed (read or written) through any other pointer.
133 /// This applies even if the result of this method is unused!
135 /// [the module documentation]: crate::ptr#safety
137 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
138 pub unsafe fn as_uninit_mut(&mut self) -> &mut MaybeUninit
<T
> {
139 // SAFETY: the caller must guarantee that `self` meets all the
140 // requirements for a reference.
141 unsafe { &mut *self.cast().as_ptr() }
145 impl<T
: ?Sized
> NonNull
<T
> {
146 /// Creates a new `NonNull`.
150 /// `ptr` must be non-null.
151 #[stable(feature = "nonnull", since = "1.25.0")]
152 #[rustc_const_stable(feature = "const_nonnull_new_unchecked", since = "1.32.0")]
154 pub const unsafe fn new_unchecked(ptr
: *mut T
) -> Self {
155 // SAFETY: the caller must guarantee that `ptr` is non-null.
156 unsafe { NonNull { pointer: ptr as _ }
}
159 /// Creates a new `NonNull` if `ptr` is non-null.
160 #[stable(feature = "nonnull", since = "1.25.0")]
162 pub fn new(ptr
: *mut T
) -> Option
<Self> {
164 // SAFETY: The pointer is already checked and is not null
165 Some(unsafe { Self::new_unchecked(ptr) }
)
171 /// Acquires the underlying `*mut` pointer.
172 #[stable(feature = "nonnull", since = "1.25.0")]
173 #[rustc_const_stable(feature = "const_nonnull_as_ptr", since = "1.32.0")]
175 pub const fn as_ptr(self) -> *mut T
{
176 self.pointer
as *mut T
179 /// Returns a shared reference to the value. If the value may be uninitialized, [`as_uninit_ref`]
180 /// must be used instead.
182 /// For the mutable counterpart see [`as_mut`].
184 /// [`as_uninit_ref`]: NonNull::as_uninit_ref
185 /// [`as_mut`]: NonNull::as_mut
189 /// When calling this method, you have to ensure that all of the following is true:
191 /// * The pointer must be properly aligned.
193 /// * It must be "dereferencable" in the sense defined in [the module documentation].
195 /// * The pointer must point to an initialized instance of `T`.
197 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
198 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
199 /// In particular, for the duration of this lifetime, the memory the pointer points to must
200 /// not get mutated (except inside `UnsafeCell`).
202 /// This applies even if the result of this method is unused!
203 /// (The part about being initialized is not yet fully decided, but until
204 /// it is, the only safe approach is to ensure that they are indeed initialized.)
206 /// [the module documentation]: crate::ptr#safety
207 #[stable(feature = "nonnull", since = "1.25.0")]
209 pub unsafe fn as_ref(&self) -> &T
{
210 // SAFETY: the caller must guarantee that `self` meets all the
211 // requirements for a reference.
212 unsafe { &*self.as_ptr() }
215 /// Returns a unique reference to the value. If the value may be uninitialized, [`as_uninit_mut`]
216 /// must be used instead.
218 /// For the shared counterpart see [`as_ref`].
220 /// [`as_uninit_mut`]: NonNull::as_uninit_mut
221 /// [`as_ref`]: NonNull::as_ref
225 /// When calling this method, you have to ensure that all of the following is true:
227 /// * The pointer must be properly aligned.
229 /// * It must be "dereferencable" in the sense defined in [the module documentation].
231 /// * The pointer must point to an initialized instance of `T`.
233 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
234 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
235 /// In particular, for the duration of this lifetime, the memory the pointer points to must
236 /// not get accessed (read or written) through any other pointer.
238 /// This applies even if the result of this method is unused!
239 /// (The part about being initialized is not yet fully decided, but until
240 /// it is, the only safe approach is to ensure that they are indeed initialized.)
242 /// [the module documentation]: crate::ptr#safety
243 #[stable(feature = "nonnull", since = "1.25.0")]
245 pub unsafe fn as_mut(&mut self) -> &mut T
{
246 // SAFETY: the caller must guarantee that `self` meets all the
247 // requirements for a mutable reference.
248 unsafe { &mut *self.as_ptr() }
251 /// Casts to a pointer of another type.
252 #[stable(feature = "nonnull_cast", since = "1.27.0")]
253 #[rustc_const_stable(feature = "const_nonnull_cast", since = "1.32.0")]
255 pub const fn cast
<U
>(self) -> NonNull
<U
> {
256 // SAFETY: `self` is a `NonNull` pointer which is necessarily non-null
257 unsafe { NonNull::new_unchecked(self.as_ptr() as *mut U) }
261 impl<T
> NonNull
<[T
]> {
262 /// Creates a non-null raw slice from a thin pointer and a length.
264 /// The `len` argument is the number of **elements**, not the number of bytes.
266 /// This function is safe, but dereferencing the return value is unsafe.
267 /// See the documentation of [`slice::from_raw_parts`] for slice safety requirements.
272 /// #![feature(nonnull_slice_from_raw_parts)]
274 /// use std::ptr::NonNull;
276 /// // create a slice pointer when starting out with a pointer to the first element
277 /// let mut x = [5, 6, 7];
278 /// let nonnull_pointer = NonNull::new(x.as_mut_ptr()).unwrap();
279 /// let slice = NonNull::slice_from_raw_parts(nonnull_pointer, 3);
280 /// assert_eq!(unsafe { slice.as_ref()[2] }, 7);
283 /// (Note that this example artificially demonstrates a use of this method,
284 /// but `let slice = NonNull::from(&x[..]);` would be a better way to write code like this.)
285 #[unstable(feature = "nonnull_slice_from_raw_parts", issue = "71941")]
286 #[rustc_const_unstable(feature = "const_nonnull_slice_from_raw_parts", issue = "71941")]
288 pub const fn slice_from_raw_parts(data
: NonNull
<T
>, len
: usize) -> Self {
289 // SAFETY: `data` is a `NonNull` pointer which is necessarily non-null
290 unsafe { Self::new_unchecked(super::slice_from_raw_parts_mut(data.as_ptr(), len)) }
293 /// Returns the length of a non-null raw slice.
295 /// The returned value is the number of **elements**, not the number of bytes.
297 /// This function is safe, even when the non-null raw slice cannot be dereferenced to a slice
298 /// because the pointer does not have a valid address.
303 /// #![feature(slice_ptr_len, nonnull_slice_from_raw_parts)]
304 /// use std::ptr::NonNull;
306 /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
307 /// assert_eq!(slice.len(), 3);
309 #[unstable(feature = "slice_ptr_len", issue = "71146")]
310 #[rustc_const_unstable(feature = "const_slice_ptr_len", issue = "71146")]
312 pub const fn len(self) -> usize {
316 /// Returns a non-null pointer to the slice's buffer.
321 /// #![feature(slice_ptr_get, nonnull_slice_from_raw_parts)]
322 /// use std::ptr::NonNull;
324 /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
325 /// assert_eq!(slice.as_non_null_ptr(), NonNull::new(1 as *mut i8).unwrap());
328 #[unstable(feature = "slice_ptr_get", issue = "74265")]
329 #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")]
330 pub const fn as_non_null_ptr(self) -> NonNull
<T
> {
331 // SAFETY: We know `self` is non-null.
332 unsafe { NonNull::new_unchecked(self.as_ptr().as_mut_ptr()) }
335 /// Returns a raw pointer to the slice's buffer.
340 /// #![feature(slice_ptr_get, nonnull_slice_from_raw_parts)]
341 /// use std::ptr::NonNull;
343 /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
344 /// assert_eq!(slice.as_mut_ptr(), 1 as *mut i8);
347 #[unstable(feature = "slice_ptr_get", issue = "74265")]
348 #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")]
349 pub const fn as_mut_ptr(self) -> *mut T
{
350 self.as_non_null_ptr().as_ptr()
353 /// Returns a shared reference to a slice of possibly uninitialized values. In contrast to
354 /// [`as_ref`], this does not require that the value has to be initialized.
356 /// For the mutable counterpart see [`as_uninit_slice_mut`].
358 /// [`as_ref`]: NonNull::as_ref
359 /// [`as_uninit_slice_mut`]: NonNull::as_uninit_slice_mut
363 /// When calling this method, you have to ensure that all of the following is true:
365 /// * The pointer must be [valid] for reads for `ptr.len() * mem::size_of::<T>()` many bytes,
366 /// and it must be properly aligned. This means in particular:
368 /// * The entire memory range of this slice must be contained within a single allocated object!
369 /// Slices can never span across multiple allocated objects.
371 /// * The pointer must be aligned even for zero-length slices. One
372 /// reason for this is that enum layout optimizations may rely on references
373 /// (including slices of any length) being aligned and non-null to distinguish
374 /// them from other data. You can obtain a pointer that is usable as `data`
375 /// for zero-length slices using [`NonNull::dangling()`].
377 /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
378 /// See the safety documentation of [`pointer::offset`].
380 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
381 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
382 /// In particular, for the duration of this lifetime, the memory the pointer points to must
383 /// not get mutated (except inside `UnsafeCell`).
385 /// This applies even if the result of this method is unused!
387 /// See also [`slice::from_raw_parts`].
389 /// [valid]: crate::ptr#safety
390 /// [`pointer::offset`]: ../../std/primitive.pointer.html#method.offset
392 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
393 pub unsafe fn as_uninit_slice(&self) -> &[MaybeUninit
<T
>] {
394 // SAFETY: the caller must uphold the safety contract for `as_uninit_slice`.
395 unsafe { slice::from_raw_parts(self.cast().as_ptr(), self.len()) }
398 /// Returns a unique reference to a slice of possibly uninitialized values. In contrast to
399 /// [`as_mut`], this does not require that the value has to be initialized.
401 /// For the shared counterpart see [`as_uninit_slice`].
403 /// [`as_mut`]: NonNull::as_mut
404 /// [`as_uninit_slice`]: NonNull::as_uninit_slice
408 /// When calling this method, you have to ensure that all of the following is true:
410 /// * The pointer must be [valid] for reads and writes for `ptr.len() * mem::size_of::<T>()`
411 /// many bytes, and it must be properly aligned. This means in particular:
413 /// * The entire memory range of this slice must be contained within a single allocated object!
414 /// Slices can never span across multiple allocated objects.
416 /// * The pointer must be aligned even for zero-length slices. One
417 /// reason for this is that enum layout optimizations may rely on references
418 /// (including slices of any length) being aligned and non-null to distinguish
419 /// them from other data. You can obtain a pointer that is usable as `data`
420 /// for zero-length slices using [`NonNull::dangling()`].
422 /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
423 /// See the safety documentation of [`pointer::offset`].
425 /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
426 /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
427 /// In particular, for the duration of this lifetime, the memory the pointer points to must
428 /// not get accessed (read or written) through any other pointer.
430 /// This applies even if the result of this method is unused!
432 /// See also [`slice::from_raw_parts_mut`].
434 /// [valid]: crate::ptr#safety
435 /// [`pointer::offset`]: ../../std/primitive.pointer.html#method.offset
440 /// #![feature(allocator_api, ptr_as_uninit)]
442 /// use std::alloc::{Allocator, Layout, Global};
443 /// use std::mem::MaybeUninit;
444 /// use std::ptr::NonNull;
446 /// let memory: NonNull<[u8]> = Global.allocate(Layout::new::<[u8; 32]>())?;
447 /// // This is safe as `memory` is valid for reads and writes for `memory.len()` many bytes.
448 /// // Note that calling `memory.as_mut()` is not allowed here as the content may be uninitialized.
449 /// # #[allow(unused_variables)]
450 /// let slice: &mut [MaybeUninit<u8>] = unsafe { memory.as_uninit_slice_mut() };
451 /// # Ok::<_, std::alloc::AllocError>(())
454 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
455 pub unsafe fn as_uninit_slice_mut(&self) -> &mut [MaybeUninit
<T
>] {
456 // SAFETY: the caller must uphold the safety contract for `as_uninit_slice_mut`.
457 unsafe { slice::from_raw_parts_mut(self.cast().as_ptr(), self.len()) }
460 /// Returns a raw pointer to an element or subslice, without doing bounds
463 /// Calling this method with an out-of-bounds index or when `self` is not dereferencable
464 /// is *[undefined behavior]* even if the resulting pointer is not used.
466 /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
471 /// #![feature(slice_ptr_get, nonnull_slice_from_raw_parts)]
472 /// use std::ptr::NonNull;
474 /// let x = &mut [1, 2, 4];
475 /// let x = NonNull::slice_from_raw_parts(NonNull::new(x.as_mut_ptr()).unwrap(), x.len());
478 /// assert_eq!(x.get_unchecked_mut(1).as_ptr(), x.as_non_null_ptr().as_ptr().add(1));
481 #[unstable(feature = "slice_ptr_get", issue = "74265")]
483 pub unsafe fn get_unchecked_mut
<I
>(self, index
: I
) -> NonNull
<I
::Output
>
487 // SAFETY: the caller ensures that `self` is dereferencable and `index` in-bounds.
488 // As a consequence, the resulting pointer cannot be NULL.
489 unsafe { NonNull::new_unchecked(self.as_ptr().get_unchecked_mut(index)) }
493 #[stable(feature = "nonnull", since = "1.25.0")]
494 impl<T
: ?Sized
> Clone
for NonNull
<T
> {
496 fn clone(&self) -> Self {
501 #[stable(feature = "nonnull", since = "1.25.0")]
502 impl<T
: ?Sized
> Copy
for NonNull
<T
> {}
504 #[unstable(feature = "coerce_unsized", issue = "27732")]
505 impl<T
: ?Sized
, U
: ?Sized
> CoerceUnsized
<NonNull
<U
>> for NonNull
<T
> where T
: Unsize
<U
> {}
507 #[unstable(feature = "dispatch_from_dyn", issue = "none")]
508 impl<T
: ?Sized
, U
: ?Sized
> DispatchFromDyn
<NonNull
<U
>> for NonNull
<T
> where T
: Unsize
<U
> {}
510 #[stable(feature = "nonnull", since = "1.25.0")]
511 impl<T
: ?Sized
> fmt
::Debug
for NonNull
<T
> {
512 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
513 fmt
::Pointer
::fmt(&self.as_ptr(), f
)
517 #[stable(feature = "nonnull", since = "1.25.0")]
518 impl<T
: ?Sized
> fmt
::Pointer
for NonNull
<T
> {
519 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
520 fmt
::Pointer
::fmt(&self.as_ptr(), f
)
524 #[stable(feature = "nonnull", since = "1.25.0")]
525 impl<T
: ?Sized
> Eq
for NonNull
<T
> {}
527 #[stable(feature = "nonnull", since = "1.25.0")]
528 impl<T
: ?Sized
> PartialEq
for NonNull
<T
> {
530 fn eq(&self, other
: &Self) -> bool
{
531 self.as_ptr() == other
.as_ptr()
535 #[stable(feature = "nonnull", since = "1.25.0")]
536 impl<T
: ?Sized
> Ord
for NonNull
<T
> {
538 fn cmp(&self, other
: &Self) -> Ordering
{
539 self.as_ptr().cmp(&other
.as_ptr())
543 #[stable(feature = "nonnull", since = "1.25.0")]
544 impl<T
: ?Sized
> PartialOrd
for NonNull
<T
> {
546 fn partial_cmp(&self, other
: &Self) -> Option
<Ordering
> {
547 self.as_ptr().partial_cmp(&other
.as_ptr())
551 #[stable(feature = "nonnull", since = "1.25.0")]
552 impl<T
: ?Sized
> hash
::Hash
for NonNull
<T
> {
554 fn hash
<H
: hash
::Hasher
>(&self, state
: &mut H
) {
555 self.as_ptr().hash(state
)
559 #[unstable(feature = "ptr_internals", issue = "none")]
560 impl<T
: ?Sized
> From
<Unique
<T
>> for NonNull
<T
> {
562 fn from(unique
: Unique
<T
>) -> Self {
563 // SAFETY: A Unique pointer cannot be null, so the conditions for
564 // new_unchecked() are respected.
565 unsafe { NonNull::new_unchecked(unique.as_ptr()) }
569 #[stable(feature = "nonnull", since = "1.25.0")]
570 impl<T
: ?Sized
> From
<&mut T
> for NonNull
<T
> {
572 fn from(reference
: &mut T
) -> Self {
573 // SAFETY: A mutable reference cannot be null.
574 unsafe { NonNull { pointer: reference as *mut T }
}
578 #[stable(feature = "nonnull", since = "1.25.0")]
579 impl<T
: ?Sized
> From
<&T
> for NonNull
<T
> {
581 fn from(reference
: &T
) -> Self {
582 // SAFETY: A reference cannot be null, so the conditions for
583 // new_unchecked() are respected.
584 unsafe { NonNull { pointer: reference as *const T }
}