core/ptr/
non_null.rs

1use crate::cmp::Ordering;
2use crate::marker::Unsize;
3use crate::mem::{MaybeUninit, SizedTypeProperties};
4use crate::num::NonZero;
5use crate::ops::{CoerceUnsized, DispatchFromDyn};
6use crate::pin::PinCoerceUnsized;
7use crate::ptr::Unique;
8use crate::slice::{self, SliceIndex};
9use crate::ub_checks::assert_unsafe_precondition;
10use crate::{fmt, hash, intrinsics, mem, ptr};
11
12/// `*mut T` but non-zero and [covariant].
13///
14/// This is often the correct thing to use when building data structures using
15/// raw pointers, but is ultimately more dangerous to use because of its additional
16/// properties. If you're not sure if you should use `NonNull<T>`, just use `*mut T`!
17///
18/// Unlike `*mut T`, the pointer must always be non-null, even if the pointer
19/// is never dereferenced. This is so that enums may use this forbidden value
20/// as a discriminant -- `Option<NonNull<T>>` has the same size as `*mut T`.
21/// However the pointer may still dangle if it isn't dereferenced.
22///
23/// Unlike `*mut T`, `NonNull<T>` was chosen to be covariant over `T`. This makes it
24/// possible to use `NonNull<T>` when building covariant types, but introduces the
25/// risk of unsoundness if used in a type that shouldn't actually be covariant.
26/// (The opposite choice was made for `*mut T` even though technically the unsoundness
27/// could only be caused by calling unsafe functions.)
28///
29/// Covariance is correct for most safe abstractions, such as `Box`, `Rc`, `Arc`, `Vec`,
30/// and `LinkedList`. This is the case because they provide a public API that follows the
31/// normal shared XOR mutable rules of Rust.
32///
33/// If your type cannot safely be covariant, you must ensure it contains some
34/// additional field to provide invariance. Often this field will be a [`PhantomData`]
35/// type like `PhantomData<Cell<T>>` or `PhantomData<&'a mut T>`.
36///
37/// Notice that `NonNull<T>` has a `From` instance for `&T`. However, this does
38/// not change the fact that mutating through a (pointer derived from a) shared
39/// reference is undefined behavior unless the mutation happens inside an
40/// [`UnsafeCell<T>`]. The same goes for creating a mutable reference from a shared
41/// reference. When using this `From` instance without an `UnsafeCell<T>`,
42/// it is your responsibility to ensure that `as_mut` is never called, and `as_ptr`
43/// is never used for mutation.
44///
45/// # Representation
46///
47/// Thanks to the [null pointer optimization],
48/// `NonNull<T>` and `Option<NonNull<T>>`
49/// are guaranteed to have the same size and alignment:
50///
51/// ```
52/// # use std::mem::{size_of, align_of};
53/// use std::ptr::NonNull;
54///
55/// assert_eq!(size_of::<NonNull<i16>>(), size_of::<Option<NonNull<i16>>>());
56/// assert_eq!(align_of::<NonNull<i16>>(), align_of::<Option<NonNull<i16>>>());
57///
58/// assert_eq!(size_of::<NonNull<str>>(), size_of::<Option<NonNull<str>>>());
59/// assert_eq!(align_of::<NonNull<str>>(), align_of::<Option<NonNull<str>>>());
60/// ```
61///
62/// [covariant]: https://doc.rust-lang.org/reference/subtyping.html
63/// [`PhantomData`]: crate::marker::PhantomData
64/// [`UnsafeCell<T>`]: crate::cell::UnsafeCell
65/// [null pointer optimization]: crate::option#representation
66#[stable(feature = "nonnull", since = "1.25.0")]
67#[repr(transparent)]
68#[rustc_layout_scalar_valid_range_start(1)]
69#[rustc_nonnull_optimization_guaranteed]
70#[rustc_diagnostic_item = "NonNull"]
71pub struct NonNull<T: ?Sized> {
72    // Remember to use `.as_ptr()` instead of `.pointer`, as field projecting to
73    // this is banned by <https://github.com/rust-lang/compiler-team/issues/807>.
74    pointer: *const T,
75}
76
77/// `NonNull` pointers are not `Send` because the data they reference may be aliased.
78// N.B., this impl is unnecessary, but should provide better error messages.
79#[stable(feature = "nonnull", since = "1.25.0")]
80impl<T: ?Sized> !Send for NonNull<T> {}
81
82/// `NonNull` pointers are not `Sync` because the data they reference may be aliased.
83// N.B., this impl is unnecessary, but should provide better error messages.
84#[stable(feature = "nonnull", since = "1.25.0")]
85impl<T: ?Sized> !Sync for NonNull<T> {}
86
87impl<T: Sized> NonNull<T> {
88    /// Creates a pointer with the given address and no [provenance][crate::ptr#provenance].
89    ///
90    /// For more details, see the equivalent method on a raw pointer, [`ptr::without_provenance_mut`].
91    ///
92    /// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
93    #[unstable(feature = "nonnull_provenance", issue = "135243")]
94    #[must_use]
95    #[inline]
96    pub const fn without_provenance(addr: NonZero<usize>) -> Self {
97        let pointer = crate::ptr::without_provenance(addr.get());
98        // SAFETY: we know `addr` is non-zero.
99        unsafe { NonNull { pointer } }
100    }
101
102    /// Creates a new `NonNull` that is dangling, but well-aligned.
103    ///
104    /// This is useful for initializing types which lazily allocate, like
105    /// `Vec::new` does.
106    ///
107    /// Note that the pointer value may potentially represent a valid pointer to
108    /// a `T`, which means this must not be used as a "not yet initialized"
109    /// sentinel value. Types that lazily allocate must track initialization by
110    /// some other means.
111    ///
112    /// # Examples
113    ///
114    /// ```
115    /// use std::ptr::NonNull;
116    ///
117    /// let ptr = NonNull::<u32>::dangling();
118    /// // Important: don't try to access the value of `ptr` without
119    /// // initializing it first! The pointer is not null but isn't valid either!
120    /// ```
121    #[stable(feature = "nonnull", since = "1.25.0")]
122    #[rustc_const_stable(feature = "const_nonnull_dangling", since = "1.36.0")]
123    #[must_use]
124    #[inline]
125    pub const fn dangling() -> Self {
126        let align = crate::ptr::Alignment::of::<T>();
127        NonNull::without_provenance(align.as_nonzero())
128    }
129
130    /// Converts an address back to a mutable pointer, picking up some previously 'exposed'
131    /// [provenance][crate::ptr#provenance].
132    ///
133    /// For more details, see the equivalent method on a raw pointer, [`ptr::with_exposed_provenance_mut`].
134    ///
135    /// This is an [Exposed Provenance][crate::ptr#exposed-provenance] API.
136    #[unstable(feature = "nonnull_provenance", issue = "135243")]
137    #[inline]
138    pub fn with_exposed_provenance(addr: NonZero<usize>) -> Self {
139        // SAFETY: we know `addr` is non-zero.
140        unsafe {
141            let ptr = crate::ptr::with_exposed_provenance_mut(addr.get());
142            NonNull::new_unchecked(ptr)
143        }
144    }
145
146    /// Returns a shared references to the value. In contrast to [`as_ref`], this does not require
147    /// that the value has to be initialized.
148    ///
149    /// For the mutable counterpart see [`as_uninit_mut`].
150    ///
151    /// [`as_ref`]: NonNull::as_ref
152    /// [`as_uninit_mut`]: NonNull::as_uninit_mut
153    ///
154    /// # Safety
155    ///
156    /// When calling this method, you have to ensure that
157    /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
158    /// Note that because the created reference is to `MaybeUninit<T>`, the
159    /// source pointer can point to uninitialized memory.
160    #[inline]
161    #[must_use]
162    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
163    pub const unsafe fn as_uninit_ref<'a>(self) -> &'a MaybeUninit<T> {
164        // SAFETY: the caller must guarantee that `self` meets all the
165        // requirements for a reference.
166        unsafe { &*self.cast().as_ptr() }
167    }
168
169    /// Returns a unique references to the value. In contrast to [`as_mut`], this does not require
170    /// that the value has to be initialized.
171    ///
172    /// For the shared counterpart see [`as_uninit_ref`].
173    ///
174    /// [`as_mut`]: NonNull::as_mut
175    /// [`as_uninit_ref`]: NonNull::as_uninit_ref
176    ///
177    /// # Safety
178    ///
179    /// When calling this method, you have to ensure that
180    /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
181    /// Note that because the created reference is to `MaybeUninit<T>`, the
182    /// source pointer can point to uninitialized memory.
183    #[inline]
184    #[must_use]
185    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
186    pub const unsafe fn as_uninit_mut<'a>(self) -> &'a mut MaybeUninit<T> {
187        // SAFETY: the caller must guarantee that `self` meets all the
188        // requirements for a reference.
189        unsafe { &mut *self.cast().as_ptr() }
190    }
191}
192
193impl<T: ?Sized> NonNull<T> {
194    /// Creates a new `NonNull`.
195    ///
196    /// # Safety
197    ///
198    /// `ptr` must be non-null.
199    ///
200    /// # Examples
201    ///
202    /// ```
203    /// use std::ptr::NonNull;
204    ///
205    /// let mut x = 0u32;
206    /// let ptr = unsafe { NonNull::new_unchecked(&mut x as *mut _) };
207    /// ```
208    ///
209    /// *Incorrect* usage of this function:
210    ///
211    /// ```rust,no_run
212    /// use std::ptr::NonNull;
213    ///
214    /// // NEVER DO THAT!!! This is undefined behavior. ⚠️
215    /// let ptr = unsafe { NonNull::<u32>::new_unchecked(std::ptr::null_mut()) };
216    /// ```
217    #[stable(feature = "nonnull", since = "1.25.0")]
218    #[rustc_const_stable(feature = "const_nonnull_new_unchecked", since = "1.25.0")]
219    #[inline]
220    pub const unsafe fn new_unchecked(ptr: *mut T) -> Self {
221        // SAFETY: the caller must guarantee that `ptr` is non-null.
222        unsafe {
223            assert_unsafe_precondition!(
224                check_language_ub,
225                "NonNull::new_unchecked requires that the pointer is non-null",
226                (ptr: *mut () = ptr as *mut ()) => !ptr.is_null()
227            );
228            NonNull { pointer: ptr as _ }
229        }
230    }
231
232    /// Creates a new `NonNull` if `ptr` is non-null.
233    ///
234    /// # Panics during const evaluation
235    ///
236    /// This method will panic during const evaluation if the pointer cannot be
237    /// determined to be null or not. See [`is_null`] for more information.
238    ///
239    /// [`is_null`]: ../primitive.pointer.html#method.is_null-1
240    ///
241    /// # Examples
242    ///
243    /// ```
244    /// use std::ptr::NonNull;
245    ///
246    /// let mut x = 0u32;
247    /// let ptr = NonNull::<u32>::new(&mut x as *mut _).expect("ptr is null!");
248    ///
249    /// if let Some(ptr) = NonNull::<u32>::new(std::ptr::null_mut()) {
250    ///     unreachable!();
251    /// }
252    /// ```
253    #[stable(feature = "nonnull", since = "1.25.0")]
254    #[rustc_const_stable(feature = "const_nonnull_new", since = "1.85.0")]
255    #[inline]
256    pub const fn new(ptr: *mut T) -> Option<Self> {
257        if !ptr.is_null() {
258            // SAFETY: The pointer is already checked and is not null
259            Some(unsafe { Self::new_unchecked(ptr) })
260        } else {
261            None
262        }
263    }
264
265    /// Converts a reference to a `NonNull` pointer.
266    #[unstable(feature = "non_null_from_ref", issue = "130823")]
267    #[inline]
268    pub const fn from_ref(r: &T) -> Self {
269        // SAFETY: A reference cannot be null.
270        unsafe { NonNull { pointer: r as *const T } }
271    }
272
273    /// Converts a mutable reference to a `NonNull` pointer.
274    #[unstable(feature = "non_null_from_ref", issue = "130823")]
275    #[inline]
276    pub const fn from_mut(r: &mut T) -> Self {
277        // SAFETY: A mutable reference cannot be null.
278        unsafe { NonNull { pointer: r as *mut T } }
279    }
280
281    /// Performs the same functionality as [`std::ptr::from_raw_parts`], except that a
282    /// `NonNull` pointer is returned, as opposed to a raw `*const` pointer.
283    ///
284    /// See the documentation of [`std::ptr::from_raw_parts`] for more details.
285    ///
286    /// [`std::ptr::from_raw_parts`]: crate::ptr::from_raw_parts
287    #[unstable(feature = "ptr_metadata", issue = "81513")]
288    #[inline]
289    pub const fn from_raw_parts(
290        data_pointer: NonNull<impl super::Thin>,
291        metadata: <T as super::Pointee>::Metadata,
292    ) -> NonNull<T> {
293        // SAFETY: The result of `ptr::from::raw_parts_mut` is non-null because `data_pointer` is.
294        unsafe {
295            NonNull::new_unchecked(super::from_raw_parts_mut(data_pointer.as_ptr(), metadata))
296        }
297    }
298
299    /// Decompose a (possibly wide) pointer into its data pointer and metadata components.
300    ///
301    /// The pointer can be later reconstructed with [`NonNull::from_raw_parts`].
302    #[unstable(feature = "ptr_metadata", issue = "81513")]
303    #[must_use = "this returns the result of the operation, \
304                  without modifying the original"]
305    #[inline]
306    pub const fn to_raw_parts(self) -> (NonNull<()>, <T as super::Pointee>::Metadata) {
307        (self.cast(), super::metadata(self.as_ptr()))
308    }
309
310    /// Gets the "address" portion of the pointer.
311    ///
312    /// For more details, see the equivalent method on a raw pointer, [`pointer::addr`].
313    ///
314    /// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
315    #[must_use]
316    #[inline]
317    #[stable(feature = "strict_provenance", since = "1.84.0")]
318    pub fn addr(self) -> NonZero<usize> {
319        // SAFETY: The pointer is guaranteed by the type to be non-null,
320        // meaning that the address will be non-zero.
321        unsafe { NonZero::new_unchecked(self.as_ptr().addr()) }
322    }
323
324    /// Exposes the ["provenance"][crate::ptr#provenance] part of the pointer for future use in
325    /// [`with_exposed_provenance`][NonNull::with_exposed_provenance] and returns the "address" portion.
326    ///
327    /// For more details, see the equivalent method on a raw pointer, [`pointer::expose_provenance`].
328    ///
329    /// This is an [Exposed Provenance][crate::ptr#exposed-provenance] API.
330    #[unstable(feature = "nonnull_provenance", issue = "135243")]
331    pub fn expose_provenance(self) -> NonZero<usize> {
332        // SAFETY: The pointer is guaranteed by the type to be non-null,
333        // meaning that the address will be non-zero.
334        unsafe { NonZero::new_unchecked(self.as_ptr().expose_provenance()) }
335    }
336
337    /// Creates a new pointer with the given address and the [provenance][crate::ptr#provenance] of
338    /// `self`.
339    ///
340    /// For more details, see the equivalent method on a raw pointer, [`pointer::with_addr`].
341    ///
342    /// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
343    #[must_use]
344    #[inline]
345    #[stable(feature = "strict_provenance", since = "1.84.0")]
346    pub fn with_addr(self, addr: NonZero<usize>) -> Self {
347        // SAFETY: The result of `ptr::from::with_addr` is non-null because `addr` is guaranteed to be non-zero.
348        unsafe { NonNull::new_unchecked(self.as_ptr().with_addr(addr.get()) as *mut _) }
349    }
350
351    /// Creates a new pointer by mapping `self`'s address to a new one, preserving the
352    /// [provenance][crate::ptr#provenance] of `self`.
353    ///
354    /// For more details, see the equivalent method on a raw pointer, [`pointer::map_addr`].
355    ///
356    /// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
357    #[must_use]
358    #[inline]
359    #[stable(feature = "strict_provenance", since = "1.84.0")]
360    pub fn map_addr(self, f: impl FnOnce(NonZero<usize>) -> NonZero<usize>) -> Self {
361        self.with_addr(f(self.addr()))
362    }
363
364    /// Acquires the underlying `*mut` pointer.
365    ///
366    /// # Examples
367    ///
368    /// ```
369    /// use std::ptr::NonNull;
370    ///
371    /// let mut x = 0u32;
372    /// let ptr = NonNull::new(&mut x).expect("ptr is null!");
373    ///
374    /// let x_value = unsafe { *ptr.as_ptr() };
375    /// assert_eq!(x_value, 0);
376    ///
377    /// unsafe { *ptr.as_ptr() += 2; }
378    /// let x_value = unsafe { *ptr.as_ptr() };
379    /// assert_eq!(x_value, 2);
380    /// ```
381    #[stable(feature = "nonnull", since = "1.25.0")]
382    #[rustc_const_stable(feature = "const_nonnull_as_ptr", since = "1.32.0")]
383    #[rustc_never_returns_null_ptr]
384    #[must_use]
385    #[inline(always)]
386    pub const fn as_ptr(self) -> *mut T {
387        // This is a transmute for the same reasons as `NonZero::get`.
388
389        // SAFETY: `NonNull` is `transparent` over a `*const T`, and `*const T`
390        // and `*mut T` have the same layout, so transitively we can transmute
391        // our `NonNull` to a `*mut T` directly.
392        unsafe { mem::transmute::<Self, *mut T>(self) }
393    }
394
395    /// Returns a shared reference to the value. If the value may be uninitialized, [`as_uninit_ref`]
396    /// must be used instead.
397    ///
398    /// For the mutable counterpart see [`as_mut`].
399    ///
400    /// [`as_uninit_ref`]: NonNull::as_uninit_ref
401    /// [`as_mut`]: NonNull::as_mut
402    ///
403    /// # Safety
404    ///
405    /// When calling this method, you have to ensure that
406    /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
407    ///
408    /// # Examples
409    ///
410    /// ```
411    /// use std::ptr::NonNull;
412    ///
413    /// let mut x = 0u32;
414    /// let ptr = NonNull::new(&mut x as *mut _).expect("ptr is null!");
415    ///
416    /// let ref_x = unsafe { ptr.as_ref() };
417    /// println!("{ref_x}");
418    /// ```
419    ///
420    /// [the module documentation]: crate::ptr#safety
421    #[stable(feature = "nonnull", since = "1.25.0")]
422    #[rustc_const_stable(feature = "const_nonnull_as_ref", since = "1.73.0")]
423    #[must_use]
424    #[inline(always)]
425    pub const unsafe fn as_ref<'a>(&self) -> &'a T {
426        // SAFETY: the caller must guarantee that `self` meets all the
427        // requirements for a reference.
428        // `cast_const` avoids a mutable raw pointer deref.
429        unsafe { &*self.as_ptr().cast_const() }
430    }
431
432    /// Returns a unique reference to the value. If the value may be uninitialized, [`as_uninit_mut`]
433    /// must be used instead.
434    ///
435    /// For the shared counterpart see [`as_ref`].
436    ///
437    /// [`as_uninit_mut`]: NonNull::as_uninit_mut
438    /// [`as_ref`]: NonNull::as_ref
439    ///
440    /// # Safety
441    ///
442    /// When calling this method, you have to ensure that
443    /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
444    /// # Examples
445    ///
446    /// ```
447    /// use std::ptr::NonNull;
448    ///
449    /// let mut x = 0u32;
450    /// let mut ptr = NonNull::new(&mut x).expect("null pointer");
451    ///
452    /// let x_ref = unsafe { ptr.as_mut() };
453    /// assert_eq!(*x_ref, 0);
454    /// *x_ref += 2;
455    /// assert_eq!(*x_ref, 2);
456    /// ```
457    ///
458    /// [the module documentation]: crate::ptr#safety
459    #[stable(feature = "nonnull", since = "1.25.0")]
460    #[rustc_const_stable(feature = "const_ptr_as_ref", since = "1.83.0")]
461    #[must_use]
462    #[inline(always)]
463    pub const unsafe fn as_mut<'a>(&mut self) -> &'a mut T {
464        // SAFETY: the caller must guarantee that `self` meets all the
465        // requirements for a mutable reference.
466        unsafe { &mut *self.as_ptr() }
467    }
468
469    /// Casts to a pointer of another type.
470    ///
471    /// # Examples
472    ///
473    /// ```
474    /// use std::ptr::NonNull;
475    ///
476    /// let mut x = 0u32;
477    /// let ptr = NonNull::new(&mut x as *mut _).expect("null pointer");
478    ///
479    /// let casted_ptr = ptr.cast::<i8>();
480    /// let raw_ptr: *mut i8 = casted_ptr.as_ptr();
481    /// ```
482    #[stable(feature = "nonnull_cast", since = "1.27.0")]
483    #[rustc_const_stable(feature = "const_nonnull_cast", since = "1.36.0")]
484    #[must_use = "this returns the result of the operation, \
485                  without modifying the original"]
486    #[inline]
487    pub const fn cast<U>(self) -> NonNull<U> {
488        // SAFETY: `self` is a `NonNull` pointer which is necessarily non-null
489        unsafe { NonNull { pointer: self.as_ptr() as *mut U } }
490    }
491
492    /// Adds an offset to a pointer.
493    ///
494    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
495    /// offset of `3 * size_of::<T>()` bytes.
496    ///
497    /// # Safety
498    ///
499    /// If any of the following conditions are violated, the result is Undefined Behavior:
500    ///
501    /// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
502    ///
503    /// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
504    ///   [allocated object], and the entire memory range between `self` and the result must be in
505    ///   bounds of that allocated object. In particular, this range must not "wrap around" the edge
506    ///   of the address space.
507    ///
508    /// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
509    /// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
510    /// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
511    /// safe.
512    ///
513    /// [allocated object]: crate::ptr#allocated-object
514    ///
515    /// # Examples
516    ///
517    /// ```
518    /// use std::ptr::NonNull;
519    ///
520    /// let mut s = [1, 2, 3];
521    /// let ptr: NonNull<u32> = NonNull::new(s.as_mut_ptr()).unwrap();
522    ///
523    /// unsafe {
524    ///     println!("{}", ptr.offset(1).read());
525    ///     println!("{}", ptr.offset(2).read());
526    /// }
527    /// ```
528    #[inline(always)]
529    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
530    #[must_use = "returns a new pointer rather than modifying its argument"]
531    #[stable(feature = "non_null_convenience", since = "1.80.0")]
532    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
533    pub const unsafe fn offset(self, count: isize) -> Self
534    where
535        T: Sized,
536    {
537        // SAFETY: the caller must uphold the safety contract for `offset`.
538        // Additionally safety contract of `offset` guarantees that the resulting pointer is
539        // pointing to an allocation, there can't be an allocation at null, thus it's safe to
540        // construct `NonNull`.
541        unsafe { NonNull { pointer: intrinsics::offset(self.as_ptr(), count) } }
542    }
543
544    /// Calculates the offset from a pointer in bytes.
545    ///
546    /// `count` is in units of **bytes**.
547    ///
548    /// This is purely a convenience for casting to a `u8` pointer and
549    /// using [offset][pointer::offset] on it. See that method for documentation
550    /// and safety requirements.
551    ///
552    /// For non-`Sized` pointees this operation changes only the data pointer,
553    /// leaving the metadata untouched.
554    #[must_use]
555    #[inline(always)]
556    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
557    #[stable(feature = "non_null_convenience", since = "1.80.0")]
558    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
559    pub const unsafe fn byte_offset(self, count: isize) -> Self {
560        // SAFETY: the caller must uphold the safety contract for `offset` and `byte_offset` has
561        // the same safety contract.
562        // Additionally safety contract of `offset` guarantees that the resulting pointer is
563        // pointing to an allocation, there can't be an allocation at null, thus it's safe to
564        // construct `NonNull`.
565        unsafe { NonNull { pointer: self.as_ptr().byte_offset(count) } }
566    }
567
568    /// Adds an offset to a pointer (convenience for `.offset(count as isize)`).
569    ///
570    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
571    /// offset of `3 * size_of::<T>()` bytes.
572    ///
573    /// # Safety
574    ///
575    /// If any of the following conditions are violated, the result is Undefined Behavior:
576    ///
577    /// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
578    ///
579    /// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
580    ///   [allocated object], and the entire memory range between `self` and the result must be in
581    ///   bounds of that allocated object. In particular, this range must not "wrap around" the edge
582    ///   of the address space.
583    ///
584    /// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
585    /// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
586    /// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
587    /// safe.
588    ///
589    /// [allocated object]: crate::ptr#allocated-object
590    ///
591    /// # Examples
592    ///
593    /// ```
594    /// use std::ptr::NonNull;
595    ///
596    /// let s: &str = "123";
597    /// let ptr: NonNull<u8> = NonNull::new(s.as_ptr().cast_mut()).unwrap();
598    ///
599    /// unsafe {
600    ///     println!("{}", ptr.add(1).read() as char);
601    ///     println!("{}", ptr.add(2).read() as char);
602    /// }
603    /// ```
604    #[inline(always)]
605    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
606    #[must_use = "returns a new pointer rather than modifying its argument"]
607    #[stable(feature = "non_null_convenience", since = "1.80.0")]
608    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
609    pub const unsafe fn add(self, count: usize) -> Self
610    where
611        T: Sized,
612    {
613        // SAFETY: the caller must uphold the safety contract for `offset`.
614        // Additionally safety contract of `offset` guarantees that the resulting pointer is
615        // pointing to an allocation, there can't be an allocation at null, thus it's safe to
616        // construct `NonNull`.
617        unsafe { NonNull { pointer: intrinsics::offset(self.as_ptr(), count) } }
618    }
619
620    /// Calculates the offset from a pointer in bytes (convenience for `.byte_offset(count as isize)`).
621    ///
622    /// `count` is in units of bytes.
623    ///
624    /// This is purely a convenience for casting to a `u8` pointer and
625    /// using [`add`][NonNull::add] on it. See that method for documentation
626    /// and safety requirements.
627    ///
628    /// For non-`Sized` pointees this operation changes only the data pointer,
629    /// leaving the metadata untouched.
630    #[must_use]
631    #[inline(always)]
632    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
633    #[stable(feature = "non_null_convenience", since = "1.80.0")]
634    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
635    pub const unsafe fn byte_add(self, count: usize) -> Self {
636        // SAFETY: the caller must uphold the safety contract for `add` and `byte_add` has the same
637        // safety contract.
638        // Additionally safety contract of `add` guarantees that the resulting pointer is pointing
639        // to an allocation, there can't be an allocation at null, thus it's safe to construct
640        // `NonNull`.
641        unsafe { NonNull { pointer: self.as_ptr().byte_add(count) } }
642    }
643
644    /// Subtracts an offset from a pointer (convenience for
645    /// `.offset((count as isize).wrapping_neg())`).
646    ///
647    /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
648    /// offset of `3 * size_of::<T>()` bytes.
649    ///
650    /// # Safety
651    ///
652    /// If any of the following conditions are violated, the result is Undefined Behavior:
653    ///
654    /// * The computed offset, `count * size_of::<T>()` bytes, must not overflow `isize`.
655    ///
656    /// * If the computed offset is non-zero, then `self` must be derived from a pointer to some
657    ///   [allocated object], and the entire memory range between `self` and the result must be in
658    ///   bounds of that allocated object. In particular, this range must not "wrap around" the edge
659    ///   of the address space.
660    ///
661    /// Allocated objects can never be larger than `isize::MAX` bytes, so if the computed offset
662    /// stays in bounds of the allocated object, it is guaranteed to satisfy the first requirement.
663    /// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
664    /// safe.
665    ///
666    /// [allocated object]: crate::ptr#allocated-object
667    ///
668    /// # Examples
669    ///
670    /// ```
671    /// use std::ptr::NonNull;
672    ///
673    /// let s: &str = "123";
674    ///
675    /// unsafe {
676    ///     let end: NonNull<u8> = NonNull::new(s.as_ptr().cast_mut()).unwrap().add(3);
677    ///     println!("{}", end.sub(1).read() as char);
678    ///     println!("{}", end.sub(2).read() as char);
679    /// }
680    /// ```
681    #[inline(always)]
682    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
683    #[must_use = "returns a new pointer rather than modifying its argument"]
684    #[stable(feature = "non_null_convenience", since = "1.80.0")]
685    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
686    pub const unsafe fn sub(self, count: usize) -> Self
687    where
688        T: Sized,
689    {
690        if T::IS_ZST {
691            // Pointer arithmetic does nothing when the pointee is a ZST.
692            self
693        } else {
694            // SAFETY: the caller must uphold the safety contract for `offset`.
695            // Because the pointee is *not* a ZST, that means that `count` is
696            // at most `isize::MAX`, and thus the negation cannot overflow.
697            unsafe { self.offset((count as isize).unchecked_neg()) }
698        }
699    }
700
701    /// Calculates the offset from a pointer in bytes (convenience for
702    /// `.byte_offset((count as isize).wrapping_neg())`).
703    ///
704    /// `count` is in units of bytes.
705    ///
706    /// This is purely a convenience for casting to a `u8` pointer and
707    /// using [`sub`][NonNull::sub] on it. See that method for documentation
708    /// and safety requirements.
709    ///
710    /// For non-`Sized` pointees this operation changes only the data pointer,
711    /// leaving the metadata untouched.
712    #[must_use]
713    #[inline(always)]
714    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
715    #[stable(feature = "non_null_convenience", since = "1.80.0")]
716    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
717    pub const unsafe fn byte_sub(self, count: usize) -> Self {
718        // SAFETY: the caller must uphold the safety contract for `sub` and `byte_sub` has the same
719        // safety contract.
720        // Additionally safety contract of `sub` guarantees that the resulting pointer is pointing
721        // to an allocation, there can't be an allocation at null, thus it's safe to construct
722        // `NonNull`.
723        unsafe { NonNull { pointer: self.as_ptr().byte_sub(count) } }
724    }
725
726    /// Calculates the distance between two pointers within the same allocation. The returned value is in
727    /// units of T: the distance in bytes divided by `mem::size_of::<T>()`.
728    ///
729    /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::<T>() as isize)`,
730    /// except that it has a lot more opportunities for UB, in exchange for the compiler
731    /// better understanding what you are doing.
732    ///
733    /// The primary motivation of this method is for computing the `len` of an array/slice
734    /// of `T` that you are currently representing as a "start" and "end" pointer
735    /// (and "end" is "one past the end" of the array).
736    /// In that case, `end.offset_from(start)` gets you the length of the array.
737    ///
738    /// All of the following safety requirements are trivially satisfied for this usecase.
739    ///
740    /// [`offset`]: #method.offset
741    ///
742    /// # Safety
743    ///
744    /// If any of the following conditions are violated, the result is Undefined Behavior:
745    ///
746    /// * `self` and `origin` must either
747    ///
748    ///   * point to the same address, or
749    ///   * both be *derived from* a pointer to the same [allocated object], and the memory range between
750    ///     the two pointers must be in bounds of that object. (See below for an example.)
751    ///
752    /// * The distance between the pointers, in bytes, must be an exact multiple
753    ///   of the size of `T`.
754    ///
755    /// As a consequence, the absolute distance between the pointers, in bytes, computed on
756    /// mathematical integers (without "wrapping around"), cannot overflow an `isize`. This is
757    /// implied by the in-bounds requirement, and the fact that no allocated object can be larger
758    /// than `isize::MAX` bytes.
759    ///
760    /// The requirement for pointers to be derived from the same allocated object is primarily
761    /// needed for `const`-compatibility: the distance between pointers into *different* allocated
762    /// objects is not known at compile-time. However, the requirement also exists at
763    /// runtime and may be exploited by optimizations. If you wish to compute the difference between
764    /// pointers that are not guaranteed to be from the same allocation, use `(self as isize -
765    /// origin as isize) / mem::size_of::<T>()`.
766    // FIXME: recommend `addr()` instead of `as usize` once that is stable.
767    ///
768    /// [`add`]: #method.add
769    /// [allocated object]: crate::ptr#allocated-object
770    ///
771    /// # Panics
772    ///
773    /// This function panics if `T` is a Zero-Sized Type ("ZST").
774    ///
775    /// # Examples
776    ///
777    /// Basic usage:
778    ///
779    /// ```
780    /// use std::ptr::NonNull;
781    ///
782    /// let a = [0; 5];
783    /// let ptr1: NonNull<u32> = NonNull::from(&a[1]);
784    /// let ptr2: NonNull<u32> = NonNull::from(&a[3]);
785    /// unsafe {
786    ///     assert_eq!(ptr2.offset_from(ptr1), 2);
787    ///     assert_eq!(ptr1.offset_from(ptr2), -2);
788    ///     assert_eq!(ptr1.offset(2), ptr2);
789    ///     assert_eq!(ptr2.offset(-2), ptr1);
790    /// }
791    /// ```
792    ///
793    /// *Incorrect* usage:
794    ///
795    /// ```rust,no_run
796    /// use std::ptr::NonNull;
797    ///
798    /// let ptr1 = NonNull::new(Box::into_raw(Box::new(0u8))).unwrap();
799    /// let ptr2 = NonNull::new(Box::into_raw(Box::new(1u8))).unwrap();
800    /// let diff = (ptr2.addr().get() as isize).wrapping_sub(ptr1.addr().get() as isize);
801    /// // Make ptr2_other an "alias" of ptr2.add(1), but derived from ptr1.
802    /// let diff_plus_1 = diff.wrapping_add(1);
803    /// let ptr2_other = NonNull::new(ptr1.as_ptr().wrapping_byte_offset(diff_plus_1)).unwrap();
804    /// assert_eq!(ptr2.addr(), ptr2_other.addr());
805    /// // Since ptr2_other and ptr2 are derived from pointers to different objects,
806    /// // computing their offset is undefined behavior, even though
807    /// // they point to addresses that are in-bounds of the same object!
808    ///
809    /// let one = unsafe { ptr2_other.offset_from(ptr2) }; // Undefined Behavior! ⚠️
810    /// ```
811    #[inline]
812    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
813    #[stable(feature = "non_null_convenience", since = "1.80.0")]
814    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
815    pub const unsafe fn offset_from(self, origin: NonNull<T>) -> isize
816    where
817        T: Sized,
818    {
819        // SAFETY: the caller must uphold the safety contract for `offset_from`.
820        unsafe { self.as_ptr().offset_from(origin.as_ptr()) }
821    }
822
823    /// Calculates the distance between two pointers within the same allocation. The returned value is in
824    /// units of **bytes**.
825    ///
826    /// This is purely a convenience for casting to a `u8` pointer and
827    /// using [`offset_from`][NonNull::offset_from] on it. See that method for
828    /// documentation and safety requirements.
829    ///
830    /// For non-`Sized` pointees this operation considers only the data pointers,
831    /// ignoring the metadata.
832    #[inline(always)]
833    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
834    #[stable(feature = "non_null_convenience", since = "1.80.0")]
835    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
836    pub const unsafe fn byte_offset_from<U: ?Sized>(self, origin: NonNull<U>) -> isize {
837        // SAFETY: the caller must uphold the safety contract for `byte_offset_from`.
838        unsafe { self.as_ptr().byte_offset_from(origin.as_ptr()) }
839    }
840
841    // N.B. `wrapping_offset``, `wrapping_add`, etc are not implemented because they can wrap to null
842
843    /// Calculates the distance between two pointers within the same allocation, *where it's known that
844    /// `self` is equal to or greater than `origin`*. The returned value is in
845    /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
846    ///
847    /// This computes the same value that [`offset_from`](#method.offset_from)
848    /// would compute, but with the added precondition that the offset is
849    /// guaranteed to be non-negative.  This method is equivalent to
850    /// `usize::try_from(self.offset_from(origin)).unwrap_unchecked()`,
851    /// but it provides slightly more information to the optimizer, which can
852    /// sometimes allow it to optimize slightly better with some backends.
853    ///
854    /// This method can be though of as recovering the `count` that was passed
855    /// to [`add`](#method.add) (or, with the parameters in the other order,
856    /// to [`sub`](#method.sub)).  The following are all equivalent, assuming
857    /// that their safety preconditions are met:
858    /// ```rust
859    /// # #![feature(ptr_sub_ptr)]
860    /// # unsafe fn blah(ptr: std::ptr::NonNull<u32>, origin: std::ptr::NonNull<u32>, count: usize) -> bool {
861    /// ptr.sub_ptr(origin) == count
862    /// # &&
863    /// origin.add(count) == ptr
864    /// # &&
865    /// ptr.sub(count) == origin
866    /// # }
867    /// ```
868    ///
869    /// # Safety
870    ///
871    /// - The distance between the pointers must be non-negative (`self >= origin`)
872    ///
873    /// - *All* the safety conditions of [`offset_from`](#method.offset_from)
874    ///   apply to this method as well; see it for the full details.
875    ///
876    /// Importantly, despite the return type of this method being able to represent
877    /// a larger offset, it's still *not permitted* to pass pointers which differ
878    /// by more than `isize::MAX` *bytes*.  As such, the result of this method will
879    /// always be less than or equal to `isize::MAX as usize`.
880    ///
881    /// # Panics
882    ///
883    /// This function panics if `T` is a Zero-Sized Type ("ZST").
884    ///
885    /// # Examples
886    ///
887    /// ```
888    /// #![feature(ptr_sub_ptr)]
889    /// use std::ptr::NonNull;
890    ///
891    /// let a = [0; 5];
892    /// let ptr1: NonNull<u32> = NonNull::from(&a[1]);
893    /// let ptr2: NonNull<u32> = NonNull::from(&a[3]);
894    /// unsafe {
895    ///     assert_eq!(ptr2.sub_ptr(ptr1), 2);
896    ///     assert_eq!(ptr1.add(2), ptr2);
897    ///     assert_eq!(ptr2.sub(2), ptr1);
898    ///     assert_eq!(ptr2.sub_ptr(ptr2), 0);
899    /// }
900    ///
901    /// // This would be incorrect, as the pointers are not correctly ordered:
902    /// // ptr1.sub_ptr(ptr2)
903    /// ```
904    #[inline]
905    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
906    #[unstable(feature = "ptr_sub_ptr", issue = "95892")]
907    #[rustc_const_unstable(feature = "const_ptr_sub_ptr", issue = "95892")]
908    pub const unsafe fn sub_ptr(self, subtracted: NonNull<T>) -> usize
909    where
910        T: Sized,
911    {
912        // SAFETY: the caller must uphold the safety contract for `sub_ptr`.
913        unsafe { self.as_ptr().sub_ptr(subtracted.as_ptr()) }
914    }
915
916    /// Calculates the distance between two pointers within the same allocation, *where it's known that
917    /// `self` is equal to or greater than `origin`*. The returned value is in
918    /// units of **bytes**.
919    ///
920    /// This is purely a convenience for casting to a `u8` pointer and
921    /// using [`sub_ptr`][NonNull::sub_ptr] on it. See that method for
922    /// documentation and safety requirements.
923    ///
924    /// For non-`Sized` pointees this operation considers only the data pointers,
925    /// ignoring the metadata.
926    #[inline(always)]
927    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
928    #[unstable(feature = "ptr_sub_ptr", issue = "95892")]
929    #[rustc_const_unstable(feature = "const_ptr_sub_ptr", issue = "95892")]
930    pub const unsafe fn byte_sub_ptr<U: ?Sized>(self, origin: NonNull<U>) -> usize {
931        // SAFETY: the caller must uphold the safety contract for `byte_sub_ptr`.
932        unsafe { self.as_ptr().byte_sub_ptr(origin.as_ptr()) }
933    }
934
935    /// Reads the value from `self` without moving it. This leaves the
936    /// memory in `self` unchanged.
937    ///
938    /// See [`ptr::read`] for safety concerns and examples.
939    ///
940    /// [`ptr::read`]: crate::ptr::read()
941    #[inline]
942    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
943    #[stable(feature = "non_null_convenience", since = "1.80.0")]
944    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
945    pub const unsafe fn read(self) -> T
946    where
947        T: Sized,
948    {
949        // SAFETY: the caller must uphold the safety contract for `read`.
950        unsafe { ptr::read(self.as_ptr()) }
951    }
952
953    /// Performs a volatile read of the value from `self` without moving it. This
954    /// leaves the memory in `self` unchanged.
955    ///
956    /// Volatile operations are intended to act on I/O memory, and are guaranteed
957    /// to not be elided or reordered by the compiler across other volatile
958    /// operations.
959    ///
960    /// See [`ptr::read_volatile`] for safety concerns and examples.
961    ///
962    /// [`ptr::read_volatile`]: crate::ptr::read_volatile()
963    #[inline]
964    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
965    #[stable(feature = "non_null_convenience", since = "1.80.0")]
966    pub unsafe fn read_volatile(self) -> T
967    where
968        T: Sized,
969    {
970        // SAFETY: the caller must uphold the safety contract for `read_volatile`.
971        unsafe { ptr::read_volatile(self.as_ptr()) }
972    }
973
974    /// Reads the value from `self` without moving it. This leaves the
975    /// memory in `self` unchanged.
976    ///
977    /// Unlike `read`, the pointer may be unaligned.
978    ///
979    /// See [`ptr::read_unaligned`] for safety concerns and examples.
980    ///
981    /// [`ptr::read_unaligned`]: crate::ptr::read_unaligned()
982    #[inline]
983    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
984    #[stable(feature = "non_null_convenience", since = "1.80.0")]
985    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
986    pub const unsafe fn read_unaligned(self) -> T
987    where
988        T: Sized,
989    {
990        // SAFETY: the caller must uphold the safety contract for `read_unaligned`.
991        unsafe { ptr::read_unaligned(self.as_ptr()) }
992    }
993
994    /// Copies `count * size_of<T>` bytes from `self` to `dest`. The source
995    /// and destination may overlap.
996    ///
997    /// NOTE: this has the *same* argument order as [`ptr::copy`].
998    ///
999    /// See [`ptr::copy`] for safety concerns and examples.
1000    ///
1001    /// [`ptr::copy`]: crate::ptr::copy()
1002    #[inline(always)]
1003    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1004    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1005    #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1006    pub const unsafe fn copy_to(self, dest: NonNull<T>, count: usize)
1007    where
1008        T: Sized,
1009    {
1010        // SAFETY: the caller must uphold the safety contract for `copy`.
1011        unsafe { ptr::copy(self.as_ptr(), dest.as_ptr(), count) }
1012    }
1013
1014    /// Copies `count * size_of<T>` bytes from `self` to `dest`. The source
1015    /// and destination may *not* overlap.
1016    ///
1017    /// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`].
1018    ///
1019    /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.
1020    ///
1021    /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
1022    #[inline(always)]
1023    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1024    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1025    #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1026    pub const unsafe fn copy_to_nonoverlapping(self, dest: NonNull<T>, count: usize)
1027    where
1028        T: Sized,
1029    {
1030        // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`.
1031        unsafe { ptr::copy_nonoverlapping(self.as_ptr(), dest.as_ptr(), count) }
1032    }
1033
1034    /// Copies `count * size_of<T>` bytes from `src` to `self`. The source
1035    /// and destination may overlap.
1036    ///
1037    /// NOTE: this has the *opposite* argument order of [`ptr::copy`].
1038    ///
1039    /// See [`ptr::copy`] for safety concerns and examples.
1040    ///
1041    /// [`ptr::copy`]: crate::ptr::copy()
1042    #[inline(always)]
1043    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1044    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1045    #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1046    pub const unsafe fn copy_from(self, src: NonNull<T>, count: usize)
1047    where
1048        T: Sized,
1049    {
1050        // SAFETY: the caller must uphold the safety contract for `copy`.
1051        unsafe { ptr::copy(src.as_ptr(), self.as_ptr(), count) }
1052    }
1053
1054    /// Copies `count * size_of<T>` bytes from `src` to `self`. The source
1055    /// and destination may *not* overlap.
1056    ///
1057    /// NOTE: this has the *opposite* argument order of [`ptr::copy_nonoverlapping`].
1058    ///
1059    /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.
1060    ///
1061    /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
1062    #[inline(always)]
1063    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1064    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1065    #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1066    pub const unsafe fn copy_from_nonoverlapping(self, src: NonNull<T>, count: usize)
1067    where
1068        T: Sized,
1069    {
1070        // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`.
1071        unsafe { ptr::copy_nonoverlapping(src.as_ptr(), self.as_ptr(), count) }
1072    }
1073
1074    /// Executes the destructor (if any) of the pointed-to value.
1075    ///
1076    /// See [`ptr::drop_in_place`] for safety concerns and examples.
1077    ///
1078    /// [`ptr::drop_in_place`]: crate::ptr::drop_in_place()
1079    #[inline(always)]
1080    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1081    pub unsafe fn drop_in_place(self) {
1082        // SAFETY: the caller must uphold the safety contract for `drop_in_place`.
1083        unsafe { ptr::drop_in_place(self.as_ptr()) }
1084    }
1085
1086    /// Overwrites a memory location with the given value without reading or
1087    /// dropping the old value.
1088    ///
1089    /// See [`ptr::write`] for safety concerns and examples.
1090    ///
1091    /// [`ptr::write`]: crate::ptr::write()
1092    #[inline(always)]
1093    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1094    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1095    #[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
1096    pub const unsafe fn write(self, val: T)
1097    where
1098        T: Sized,
1099    {
1100        // SAFETY: the caller must uphold the safety contract for `write`.
1101        unsafe { ptr::write(self.as_ptr(), val) }
1102    }
1103
1104    /// Invokes memset on the specified pointer, setting `count * size_of::<T>()`
1105    /// bytes of memory starting at `self` to `val`.
1106    ///
1107    /// See [`ptr::write_bytes`] for safety concerns and examples.
1108    ///
1109    /// [`ptr::write_bytes`]: crate::ptr::write_bytes()
1110    #[inline(always)]
1111    #[doc(alias = "memset")]
1112    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1113    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1114    #[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
1115    pub const unsafe fn write_bytes(self, val: u8, count: usize)
1116    where
1117        T: Sized,
1118    {
1119        // SAFETY: the caller must uphold the safety contract for `write_bytes`.
1120        unsafe { ptr::write_bytes(self.as_ptr(), val, count) }
1121    }
1122
1123    /// Performs a volatile write of a memory location with the given value without
1124    /// reading or dropping the old value.
1125    ///
1126    /// Volatile operations are intended to act on I/O memory, and are guaranteed
1127    /// to not be elided or reordered by the compiler across other volatile
1128    /// operations.
1129    ///
1130    /// See [`ptr::write_volatile`] for safety concerns and examples.
1131    ///
1132    /// [`ptr::write_volatile`]: crate::ptr::write_volatile()
1133    #[inline(always)]
1134    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1135    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1136    pub unsafe fn write_volatile(self, val: T)
1137    where
1138        T: Sized,
1139    {
1140        // SAFETY: the caller must uphold the safety contract for `write_volatile`.
1141        unsafe { ptr::write_volatile(self.as_ptr(), val) }
1142    }
1143
1144    /// Overwrites a memory location with the given value without reading or
1145    /// dropping the old value.
1146    ///
1147    /// Unlike `write`, the pointer may be unaligned.
1148    ///
1149    /// See [`ptr::write_unaligned`] for safety concerns and examples.
1150    ///
1151    /// [`ptr::write_unaligned`]: crate::ptr::write_unaligned()
1152    #[inline(always)]
1153    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1154    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1155    #[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
1156    pub const unsafe fn write_unaligned(self, val: T)
1157    where
1158        T: Sized,
1159    {
1160        // SAFETY: the caller must uphold the safety contract for `write_unaligned`.
1161        unsafe { ptr::write_unaligned(self.as_ptr(), val) }
1162    }
1163
1164    /// Replaces the value at `self` with `src`, returning the old
1165    /// value, without dropping either.
1166    ///
1167    /// See [`ptr::replace`] for safety concerns and examples.
1168    ///
1169    /// [`ptr::replace`]: crate::ptr::replace()
1170    #[inline(always)]
1171    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1172    pub unsafe fn replace(self, src: T) -> T
1173    where
1174        T: Sized,
1175    {
1176        // SAFETY: the caller must uphold the safety contract for `replace`.
1177        unsafe { ptr::replace(self.as_ptr(), src) }
1178    }
1179
1180    /// Swaps the values at two mutable locations of the same type, without
1181    /// deinitializing either. They may overlap, unlike `mem::swap` which is
1182    /// otherwise equivalent.
1183    ///
1184    /// See [`ptr::swap`] for safety concerns and examples.
1185    ///
1186    /// [`ptr::swap`]: crate::ptr::swap()
1187    #[inline(always)]
1188    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1189    #[rustc_const_stable(feature = "const_swap", since = "1.85.0")]
1190    pub const unsafe fn swap(self, with: NonNull<T>)
1191    where
1192        T: Sized,
1193    {
1194        // SAFETY: the caller must uphold the safety contract for `swap`.
1195        unsafe { ptr::swap(self.as_ptr(), with.as_ptr()) }
1196    }
1197
1198    /// Computes the offset that needs to be applied to the pointer in order to make it aligned to
1199    /// `align`.
1200    ///
1201    /// If it is not possible to align the pointer, the implementation returns
1202    /// `usize::MAX`.
1203    ///
1204    /// The offset is expressed in number of `T` elements, and not bytes.
1205    ///
1206    /// There are no guarantees whatsoever that offsetting the pointer will not overflow or go
1207    /// beyond the allocation that the pointer points into. It is up to the caller to ensure that
1208    /// the returned offset is correct in all terms other than alignment.
1209    ///
1210    /// When this is called during compile-time evaluation (which is unstable), the implementation
1211    /// may return `usize::MAX` in cases where that can never happen at runtime. This is because the
1212    /// actual alignment of pointers is not known yet during compile-time, so an offset with
1213    /// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8;
1214    /// N]` might be allocated at an odd or an even address, but at compile-time this is not yet
1215    /// known, so the execution has to be correct for either choice. It is therefore impossible to
1216    /// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual
1217    /// for unstable APIs.)
1218    ///
1219    /// # Panics
1220    ///
1221    /// The function panics if `align` is not a power-of-two.
1222    ///
1223    /// # Examples
1224    ///
1225    /// Accessing adjacent `u8` as `u16`
1226    ///
1227    /// ```
1228    /// use std::mem::align_of;
1229    /// use std::ptr::NonNull;
1230    ///
1231    /// # unsafe {
1232    /// let x = [5_u8, 6, 7, 8, 9];
1233    /// let ptr = NonNull::new(x.as_ptr() as *mut u8).unwrap();
1234    /// let offset = ptr.align_offset(align_of::<u16>());
1235    ///
1236    /// if offset < x.len() - 1 {
1237    ///     let u16_ptr = ptr.add(offset).cast::<u16>();
1238    ///     assert!(u16_ptr.read() == u16::from_ne_bytes([5, 6]) || u16_ptr.read() == u16::from_ne_bytes([6, 7]));
1239    /// } else {
1240    ///     // while the pointer can be aligned via `offset`, it would point
1241    ///     // outside the allocation
1242    /// }
1243    /// # }
1244    /// ```
1245    #[inline]
1246    #[must_use]
1247    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1248    pub fn align_offset(self, align: usize) -> usize
1249    where
1250        T: Sized,
1251    {
1252        if !align.is_power_of_two() {
1253            panic!("align_offset: align is not a power-of-two");
1254        }
1255
1256        {
1257            // SAFETY: `align` has been checked to be a power of 2 above.
1258            unsafe { ptr::align_offset(self.as_ptr(), align) }
1259        }
1260    }
1261
1262    /// Returns whether the pointer is properly aligned for `T`.
1263    ///
1264    /// # Examples
1265    ///
1266    /// ```
1267    /// use std::ptr::NonNull;
1268    ///
1269    /// // On some platforms, the alignment of i32 is less than 4.
1270    /// #[repr(align(4))]
1271    /// struct AlignedI32(i32);
1272    ///
1273    /// let data = AlignedI32(42);
1274    /// let ptr = NonNull::<AlignedI32>::from(&data);
1275    ///
1276    /// assert!(ptr.is_aligned());
1277    /// assert!(!NonNull::new(ptr.as_ptr().wrapping_byte_add(1)).unwrap().is_aligned());
1278    /// ```
1279    #[inline]
1280    #[must_use]
1281    #[stable(feature = "pointer_is_aligned", since = "1.79.0")]
1282    pub fn is_aligned(self) -> bool
1283    where
1284        T: Sized,
1285    {
1286        self.as_ptr().is_aligned()
1287    }
1288
1289    /// Returns whether the pointer is aligned to `align`.
1290    ///
1291    /// For non-`Sized` pointees this operation considers only the data pointer,
1292    /// ignoring the metadata.
1293    ///
1294    /// # Panics
1295    ///
1296    /// The function panics if `align` is not a power-of-two (this includes 0).
1297    ///
1298    /// # Examples
1299    ///
1300    /// ```
1301    /// #![feature(pointer_is_aligned_to)]
1302    ///
1303    /// // On some platforms, the alignment of i32 is less than 4.
1304    /// #[repr(align(4))]
1305    /// struct AlignedI32(i32);
1306    ///
1307    /// let data = AlignedI32(42);
1308    /// let ptr = &data as *const AlignedI32;
1309    ///
1310    /// assert!(ptr.is_aligned_to(1));
1311    /// assert!(ptr.is_aligned_to(2));
1312    /// assert!(ptr.is_aligned_to(4));
1313    ///
1314    /// assert!(ptr.wrapping_byte_add(2).is_aligned_to(2));
1315    /// assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4));
1316    ///
1317    /// assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8));
1318    /// ```
1319    #[inline]
1320    #[must_use]
1321    #[unstable(feature = "pointer_is_aligned_to", issue = "96284")]
1322    pub fn is_aligned_to(self, align: usize) -> bool {
1323        self.as_ptr().is_aligned_to(align)
1324    }
1325}
1326
1327impl<T> NonNull<[T]> {
1328    /// Creates a non-null raw slice from a thin pointer and a length.
1329    ///
1330    /// The `len` argument is the number of **elements**, not the number of bytes.
1331    ///
1332    /// This function is safe, but dereferencing the return value is unsafe.
1333    /// See the documentation of [`slice::from_raw_parts`] for slice safety requirements.
1334    ///
1335    /// # Examples
1336    ///
1337    /// ```rust
1338    /// use std::ptr::NonNull;
1339    ///
1340    /// // create a slice pointer when starting out with a pointer to the first element
1341    /// let mut x = [5, 6, 7];
1342    /// let nonnull_pointer = NonNull::new(x.as_mut_ptr()).unwrap();
1343    /// let slice = NonNull::slice_from_raw_parts(nonnull_pointer, 3);
1344    /// assert_eq!(unsafe { slice.as_ref()[2] }, 7);
1345    /// ```
1346    ///
1347    /// (Note that this example artificially demonstrates a use of this method,
1348    /// but `let slice = NonNull::from(&x[..]);` would be a better way to write code like this.)
1349    #[stable(feature = "nonnull_slice_from_raw_parts", since = "1.70.0")]
1350    #[rustc_const_stable(feature = "const_slice_from_raw_parts_mut", since = "1.83.0")]
1351    #[must_use]
1352    #[inline]
1353    pub const fn slice_from_raw_parts(data: NonNull<T>, len: usize) -> Self {
1354        // SAFETY: `data` is a `NonNull` pointer which is necessarily non-null
1355        unsafe { Self::new_unchecked(super::slice_from_raw_parts_mut(data.as_ptr(), len)) }
1356    }
1357
1358    /// Returns the length of a non-null raw slice.
1359    ///
1360    /// The returned value is the number of **elements**, not the number of bytes.
1361    ///
1362    /// This function is safe, even when the non-null raw slice cannot be dereferenced to a slice
1363    /// because the pointer does not have a valid address.
1364    ///
1365    /// # Examples
1366    ///
1367    /// ```rust
1368    /// use std::ptr::NonNull;
1369    ///
1370    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
1371    /// assert_eq!(slice.len(), 3);
1372    /// ```
1373    #[stable(feature = "slice_ptr_len_nonnull", since = "1.63.0")]
1374    #[rustc_const_stable(feature = "const_slice_ptr_len_nonnull", since = "1.63.0")]
1375    #[must_use]
1376    #[inline]
1377    pub const fn len(self) -> usize {
1378        self.as_ptr().len()
1379    }
1380
1381    /// Returns `true` if the non-null raw slice has a length of 0.
1382    ///
1383    /// # Examples
1384    ///
1385    /// ```rust
1386    /// use std::ptr::NonNull;
1387    ///
1388    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
1389    /// assert!(!slice.is_empty());
1390    /// ```
1391    #[stable(feature = "slice_ptr_is_empty_nonnull", since = "1.79.0")]
1392    #[rustc_const_stable(feature = "const_slice_ptr_is_empty_nonnull", since = "1.79.0")]
1393    #[must_use]
1394    #[inline]
1395    pub const fn is_empty(self) -> bool {
1396        self.len() == 0
1397    }
1398
1399    /// Returns a non-null pointer to the slice's buffer.
1400    ///
1401    /// # Examples
1402    ///
1403    /// ```rust
1404    /// #![feature(slice_ptr_get)]
1405    /// use std::ptr::NonNull;
1406    ///
1407    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
1408    /// assert_eq!(slice.as_non_null_ptr(), NonNull::<i8>::dangling());
1409    /// ```
1410    #[inline]
1411    #[must_use]
1412    #[unstable(feature = "slice_ptr_get", issue = "74265")]
1413    pub const fn as_non_null_ptr(self) -> NonNull<T> {
1414        self.cast()
1415    }
1416
1417    /// Returns a raw pointer to the slice's buffer.
1418    ///
1419    /// # Examples
1420    ///
1421    /// ```rust
1422    /// #![feature(slice_ptr_get)]
1423    /// use std::ptr::NonNull;
1424    ///
1425    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
1426    /// assert_eq!(slice.as_mut_ptr(), NonNull::<i8>::dangling().as_ptr());
1427    /// ```
1428    #[inline]
1429    #[must_use]
1430    #[unstable(feature = "slice_ptr_get", issue = "74265")]
1431    #[rustc_never_returns_null_ptr]
1432    pub const fn as_mut_ptr(self) -> *mut T {
1433        self.as_non_null_ptr().as_ptr()
1434    }
1435
1436    /// Returns a shared reference to a slice of possibly uninitialized values. In contrast to
1437    /// [`as_ref`], this does not require that the value has to be initialized.
1438    ///
1439    /// For the mutable counterpart see [`as_uninit_slice_mut`].
1440    ///
1441    /// [`as_ref`]: NonNull::as_ref
1442    /// [`as_uninit_slice_mut`]: NonNull::as_uninit_slice_mut
1443    ///
1444    /// # Safety
1445    ///
1446    /// When calling this method, you have to ensure that all of the following is true:
1447    ///
1448    /// * The pointer must be [valid] for reads for `ptr.len() * mem::size_of::<T>()` many bytes,
1449    ///   and it must be properly aligned. This means in particular:
1450    ///
1451    ///     * The entire memory range of this slice must be contained within a single allocated object!
1452    ///       Slices can never span across multiple allocated objects.
1453    ///
1454    ///     * The pointer must be aligned even for zero-length slices. One
1455    ///       reason for this is that enum layout optimizations may rely on references
1456    ///       (including slices of any length) being aligned and non-null to distinguish
1457    ///       them from other data. You can obtain a pointer that is usable as `data`
1458    ///       for zero-length slices using [`NonNull::dangling()`].
1459    ///
1460    /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
1461    ///   See the safety documentation of [`pointer::offset`].
1462    ///
1463    /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
1464    ///   arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
1465    ///   In particular, while this reference exists, the memory the pointer points to must
1466    ///   not get mutated (except inside `UnsafeCell`).
1467    ///
1468    /// This applies even if the result of this method is unused!
1469    ///
1470    /// See also [`slice::from_raw_parts`].
1471    ///
1472    /// [valid]: crate::ptr#safety
1473    #[inline]
1474    #[must_use]
1475    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
1476    pub const unsafe fn as_uninit_slice<'a>(self) -> &'a [MaybeUninit<T>] {
1477        // SAFETY: the caller must uphold the safety contract for `as_uninit_slice`.
1478        unsafe { slice::from_raw_parts(self.cast().as_ptr(), self.len()) }
1479    }
1480
1481    /// Returns a unique reference to a slice of possibly uninitialized values. In contrast to
1482    /// [`as_mut`], this does not require that the value has to be initialized.
1483    ///
1484    /// For the shared counterpart see [`as_uninit_slice`].
1485    ///
1486    /// [`as_mut`]: NonNull::as_mut
1487    /// [`as_uninit_slice`]: NonNull::as_uninit_slice
1488    ///
1489    /// # Safety
1490    ///
1491    /// When calling this method, you have to ensure that all of the following is true:
1492    ///
1493    /// * The pointer must be [valid] for reads and writes for `ptr.len() * mem::size_of::<T>()`
1494    ///   many bytes, and it must be properly aligned. This means in particular:
1495    ///
1496    ///     * The entire memory range of this slice must be contained within a single allocated object!
1497    ///       Slices can never span across multiple allocated objects.
1498    ///
1499    ///     * The pointer must be aligned even for zero-length slices. One
1500    ///       reason for this is that enum layout optimizations may rely on references
1501    ///       (including slices of any length) being aligned and non-null to distinguish
1502    ///       them from other data. You can obtain a pointer that is usable as `data`
1503    ///       for zero-length slices using [`NonNull::dangling()`].
1504    ///
1505    /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
1506    ///   See the safety documentation of [`pointer::offset`].
1507    ///
1508    /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
1509    ///   arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
1510    ///   In particular, while this reference exists, the memory the pointer points to must
1511    ///   not get accessed (read or written) through any other pointer.
1512    ///
1513    /// This applies even if the result of this method is unused!
1514    ///
1515    /// See also [`slice::from_raw_parts_mut`].
1516    ///
1517    /// [valid]: crate::ptr#safety
1518    ///
1519    /// # Examples
1520    ///
1521    /// ```rust
1522    /// #![feature(allocator_api, ptr_as_uninit)]
1523    ///
1524    /// use std::alloc::{Allocator, Layout, Global};
1525    /// use std::mem::MaybeUninit;
1526    /// use std::ptr::NonNull;
1527    ///
1528    /// let memory: NonNull<[u8]> = Global.allocate(Layout::new::<[u8; 32]>())?;
1529    /// // This is safe as `memory` is valid for reads and writes for `memory.len()` many bytes.
1530    /// // Note that calling `memory.as_mut()` is not allowed here as the content may be uninitialized.
1531    /// # #[allow(unused_variables)]
1532    /// let slice: &mut [MaybeUninit<u8>] = unsafe { memory.as_uninit_slice_mut() };
1533    /// # // Prevent leaks for Miri.
1534    /// # unsafe { Global.deallocate(memory.cast(), Layout::new::<[u8; 32]>()); }
1535    /// # Ok::<_, std::alloc::AllocError>(())
1536    /// ```
1537    #[inline]
1538    #[must_use]
1539    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
1540    pub const unsafe fn as_uninit_slice_mut<'a>(self) -> &'a mut [MaybeUninit<T>] {
1541        // SAFETY: the caller must uphold the safety contract for `as_uninit_slice_mut`.
1542        unsafe { slice::from_raw_parts_mut(self.cast().as_ptr(), self.len()) }
1543    }
1544
1545    /// Returns a raw pointer to an element or subslice, without doing bounds
1546    /// checking.
1547    ///
1548    /// Calling this method with an out-of-bounds index or when `self` is not dereferenceable
1549    /// is *[undefined behavior]* even if the resulting pointer is not used.
1550    ///
1551    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
1552    ///
1553    /// # Examples
1554    ///
1555    /// ```
1556    /// #![feature(slice_ptr_get)]
1557    /// use std::ptr::NonNull;
1558    ///
1559    /// let x = &mut [1, 2, 4];
1560    /// let x = NonNull::slice_from_raw_parts(NonNull::new(x.as_mut_ptr()).unwrap(), x.len());
1561    ///
1562    /// unsafe {
1563    ///     assert_eq!(x.get_unchecked_mut(1).as_ptr(), x.as_non_null_ptr().as_ptr().add(1));
1564    /// }
1565    /// ```
1566    #[unstable(feature = "slice_ptr_get", issue = "74265")]
1567    #[inline]
1568    pub unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output>
1569    where
1570        I: SliceIndex<[T]>,
1571    {
1572        // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds.
1573        // As a consequence, the resulting pointer cannot be null.
1574        unsafe { NonNull::new_unchecked(self.as_ptr().get_unchecked_mut(index)) }
1575    }
1576}
1577
1578#[stable(feature = "nonnull", since = "1.25.0")]
1579impl<T: ?Sized> Clone for NonNull<T> {
1580    #[inline(always)]
1581    fn clone(&self) -> Self {
1582        *self
1583    }
1584}
1585
1586#[stable(feature = "nonnull", since = "1.25.0")]
1587impl<T: ?Sized> Copy for NonNull<T> {}
1588
1589#[unstable(feature = "coerce_unsized", issue = "18598")]
1590impl<T: ?Sized, U: ?Sized> CoerceUnsized<NonNull<U>> for NonNull<T> where T: Unsize<U> {}
1591
1592#[unstable(feature = "dispatch_from_dyn", issue = "none")]
1593impl<T: ?Sized, U: ?Sized> DispatchFromDyn<NonNull<U>> for NonNull<T> where T: Unsize<U> {}
1594
1595#[stable(feature = "pin", since = "1.33.0")]
1596unsafe impl<T: ?Sized> PinCoerceUnsized for NonNull<T> {}
1597
1598#[unstable(feature = "pointer_like_trait", issue = "none")]
1599impl<T> core::marker::PointerLike for NonNull<T> {}
1600
1601#[stable(feature = "nonnull", since = "1.25.0")]
1602impl<T: ?Sized> fmt::Debug for NonNull<T> {
1603    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1604        fmt::Pointer::fmt(&self.as_ptr(), f)
1605    }
1606}
1607
1608#[stable(feature = "nonnull", since = "1.25.0")]
1609impl<T: ?Sized> fmt::Pointer for NonNull<T> {
1610    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1611        fmt::Pointer::fmt(&self.as_ptr(), f)
1612    }
1613}
1614
1615#[stable(feature = "nonnull", since = "1.25.0")]
1616impl<T: ?Sized> Eq for NonNull<T> {}
1617
1618#[stable(feature = "nonnull", since = "1.25.0")]
1619impl<T: ?Sized> PartialEq for NonNull<T> {
1620    #[inline]
1621    #[allow(ambiguous_wide_pointer_comparisons)]
1622    fn eq(&self, other: &Self) -> bool {
1623        self.as_ptr() == other.as_ptr()
1624    }
1625}
1626
1627#[stable(feature = "nonnull", since = "1.25.0")]
1628impl<T: ?Sized> Ord for NonNull<T> {
1629    #[inline]
1630    #[allow(ambiguous_wide_pointer_comparisons)]
1631    fn cmp(&self, other: &Self) -> Ordering {
1632        self.as_ptr().cmp(&other.as_ptr())
1633    }
1634}
1635
1636#[stable(feature = "nonnull", since = "1.25.0")]
1637impl<T: ?Sized> PartialOrd for NonNull<T> {
1638    #[inline]
1639    #[allow(ambiguous_wide_pointer_comparisons)]
1640    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
1641        self.as_ptr().partial_cmp(&other.as_ptr())
1642    }
1643}
1644
1645#[stable(feature = "nonnull", since = "1.25.0")]
1646impl<T: ?Sized> hash::Hash for NonNull<T> {
1647    #[inline]
1648    fn hash<H: hash::Hasher>(&self, state: &mut H) {
1649        self.as_ptr().hash(state)
1650    }
1651}
1652
1653#[unstable(feature = "ptr_internals", issue = "none")]
1654impl<T: ?Sized> From<Unique<T>> for NonNull<T> {
1655    #[inline]
1656    fn from(unique: Unique<T>) -> Self {
1657        unique.as_non_null_ptr()
1658    }
1659}
1660
1661#[stable(feature = "nonnull", since = "1.25.0")]
1662impl<T: ?Sized> From<&mut T> for NonNull<T> {
1663    /// Converts a `&mut T` to a `NonNull<T>`.
1664    ///
1665    /// This conversion is safe and infallible since references cannot be null.
1666    #[inline]
1667    fn from(r: &mut T) -> Self {
1668        NonNull::from_mut(r)
1669    }
1670}
1671
1672#[stable(feature = "nonnull", since = "1.25.0")]
1673impl<T: ?Sized> From<&T> for NonNull<T> {
1674    /// Converts a `&T` to a `NonNull<T>`.
1675    ///
1676    /// This conversion is safe and infallible since references cannot be null.
1677    #[inline]
1678    fn from(r: &T) -> Self {
1679        NonNull::from_ref(r)
1680    }
1681}