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    /// # unsafe fn blah(ptr: std::ptr::NonNull<u32>, origin: std::ptr::NonNull<u32>, count: usize) -> bool { unsafe {
860    /// ptr.offset_from_unsigned(origin) == count
861    /// # &&
862    /// origin.add(count) == ptr
863    /// # &&
864    /// ptr.sub(count) == origin
865    /// # } }
866    /// ```
867    ///
868    /// # Safety
869    ///
870    /// - The distance between the pointers must be non-negative (`self >= origin`)
871    ///
872    /// - *All* the safety conditions of [`offset_from`](#method.offset_from)
873    ///   apply to this method as well; see it for the full details.
874    ///
875    /// Importantly, despite the return type of this method being able to represent
876    /// a larger offset, it's still *not permitted* to pass pointers which differ
877    /// by more than `isize::MAX` *bytes*.  As such, the result of this method will
878    /// always be less than or equal to `isize::MAX as usize`.
879    ///
880    /// # Panics
881    ///
882    /// This function panics if `T` is a Zero-Sized Type ("ZST").
883    ///
884    /// # Examples
885    ///
886    /// ```
887    /// use std::ptr::NonNull;
888    ///
889    /// let a = [0; 5];
890    /// let ptr1: NonNull<u32> = NonNull::from(&a[1]);
891    /// let ptr2: NonNull<u32> = NonNull::from(&a[3]);
892    /// unsafe {
893    ///     assert_eq!(ptr2.offset_from_unsigned(ptr1), 2);
894    ///     assert_eq!(ptr1.add(2), ptr2);
895    ///     assert_eq!(ptr2.sub(2), ptr1);
896    ///     assert_eq!(ptr2.offset_from_unsigned(ptr2), 0);
897    /// }
898    ///
899    /// // This would be incorrect, as the pointers are not correctly ordered:
900    /// // ptr1.offset_from_unsigned(ptr2)
901    /// ```
902    #[inline]
903    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
904    #[stable(feature = "ptr_sub_ptr", since = "CURRENT_RUSTC_VERSION")]
905    #[rustc_const_stable(feature = "const_ptr_sub_ptr", since = "CURRENT_RUSTC_VERSION")]
906    pub const unsafe fn offset_from_unsigned(self, subtracted: NonNull<T>) -> usize
907    where
908        T: Sized,
909    {
910        // SAFETY: the caller must uphold the safety contract for `sub_ptr`.
911        unsafe { self.as_ptr().offset_from_unsigned(subtracted.as_ptr()) }
912    }
913
914    /// Calculates the distance between two pointers within the same allocation, *where it's known that
915    /// `self` is equal to or greater than `origin`*. The returned value is in
916    /// units of **bytes**.
917    ///
918    /// This is purely a convenience for casting to a `u8` pointer and
919    /// using [`sub_ptr`][NonNull::offset_from_unsigned] on it. See that method for
920    /// documentation and safety requirements.
921    ///
922    /// For non-`Sized` pointees this operation considers only the data pointers,
923    /// ignoring the metadata.
924    #[inline(always)]
925    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
926    #[stable(feature = "ptr_sub_ptr", since = "CURRENT_RUSTC_VERSION")]
927    #[rustc_const_stable(feature = "const_ptr_sub_ptr", since = "CURRENT_RUSTC_VERSION")]
928    pub const unsafe fn byte_offset_from_unsigned<U: ?Sized>(self, origin: NonNull<U>) -> usize {
929        // SAFETY: the caller must uphold the safety contract for `byte_sub_ptr`.
930        unsafe { self.as_ptr().byte_offset_from_unsigned(origin.as_ptr()) }
931    }
932
933    /// Reads the value from `self` without moving it. This leaves the
934    /// memory in `self` unchanged.
935    ///
936    /// See [`ptr::read`] for safety concerns and examples.
937    ///
938    /// [`ptr::read`]: crate::ptr::read()
939    #[inline]
940    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
941    #[stable(feature = "non_null_convenience", since = "1.80.0")]
942    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
943    pub const unsafe fn read(self) -> T
944    where
945        T: Sized,
946    {
947        // SAFETY: the caller must uphold the safety contract for `read`.
948        unsafe { ptr::read(self.as_ptr()) }
949    }
950
951    /// Performs a volatile read of the value from `self` without moving it. This
952    /// leaves the memory in `self` unchanged.
953    ///
954    /// Volatile operations are intended to act on I/O memory, and are guaranteed
955    /// to not be elided or reordered by the compiler across other volatile
956    /// operations.
957    ///
958    /// See [`ptr::read_volatile`] for safety concerns and examples.
959    ///
960    /// [`ptr::read_volatile`]: crate::ptr::read_volatile()
961    #[inline]
962    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
963    #[stable(feature = "non_null_convenience", since = "1.80.0")]
964    pub unsafe fn read_volatile(self) -> T
965    where
966        T: Sized,
967    {
968        // SAFETY: the caller must uphold the safety contract for `read_volatile`.
969        unsafe { ptr::read_volatile(self.as_ptr()) }
970    }
971
972    /// Reads the value from `self` without moving it. This leaves the
973    /// memory in `self` unchanged.
974    ///
975    /// Unlike `read`, the pointer may be unaligned.
976    ///
977    /// See [`ptr::read_unaligned`] for safety concerns and examples.
978    ///
979    /// [`ptr::read_unaligned`]: crate::ptr::read_unaligned()
980    #[inline]
981    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
982    #[stable(feature = "non_null_convenience", since = "1.80.0")]
983    #[rustc_const_stable(feature = "non_null_convenience", since = "1.80.0")]
984    pub const unsafe fn read_unaligned(self) -> T
985    where
986        T: Sized,
987    {
988        // SAFETY: the caller must uphold the safety contract for `read_unaligned`.
989        unsafe { ptr::read_unaligned(self.as_ptr()) }
990    }
991
992    /// Copies `count * size_of<T>` bytes from `self` to `dest`. The source
993    /// and destination may overlap.
994    ///
995    /// NOTE: this has the *same* argument order as [`ptr::copy`].
996    ///
997    /// See [`ptr::copy`] for safety concerns and examples.
998    ///
999    /// [`ptr::copy`]: crate::ptr::copy()
1000    #[inline(always)]
1001    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1002    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1003    #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1004    pub const unsafe fn copy_to(self, dest: NonNull<T>, count: usize)
1005    where
1006        T: Sized,
1007    {
1008        // SAFETY: the caller must uphold the safety contract for `copy`.
1009        unsafe { ptr::copy(self.as_ptr(), dest.as_ptr(), count) }
1010    }
1011
1012    /// Copies `count * size_of<T>` bytes from `self` to `dest`. The source
1013    /// and destination may *not* overlap.
1014    ///
1015    /// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`].
1016    ///
1017    /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.
1018    ///
1019    /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
1020    #[inline(always)]
1021    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1022    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1023    #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1024    pub const unsafe fn copy_to_nonoverlapping(self, dest: NonNull<T>, count: usize)
1025    where
1026        T: Sized,
1027    {
1028        // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`.
1029        unsafe { ptr::copy_nonoverlapping(self.as_ptr(), dest.as_ptr(), count) }
1030    }
1031
1032    /// Copies `count * size_of<T>` bytes from `src` to `self`. The source
1033    /// and destination may overlap.
1034    ///
1035    /// NOTE: this has the *opposite* argument order of [`ptr::copy`].
1036    ///
1037    /// See [`ptr::copy`] for safety concerns and examples.
1038    ///
1039    /// [`ptr::copy`]: crate::ptr::copy()
1040    #[inline(always)]
1041    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1042    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1043    #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1044    pub const unsafe fn copy_from(self, src: NonNull<T>, count: usize)
1045    where
1046        T: Sized,
1047    {
1048        // SAFETY: the caller must uphold the safety contract for `copy`.
1049        unsafe { ptr::copy(src.as_ptr(), self.as_ptr(), count) }
1050    }
1051
1052    /// Copies `count * size_of<T>` bytes from `src` to `self`. The source
1053    /// and destination may *not* overlap.
1054    ///
1055    /// NOTE: this has the *opposite* argument order of [`ptr::copy_nonoverlapping`].
1056    ///
1057    /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.
1058    ///
1059    /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
1060    #[inline(always)]
1061    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1062    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1063    #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1064    pub const unsafe fn copy_from_nonoverlapping(self, src: NonNull<T>, count: usize)
1065    where
1066        T: Sized,
1067    {
1068        // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`.
1069        unsafe { ptr::copy_nonoverlapping(src.as_ptr(), self.as_ptr(), count) }
1070    }
1071
1072    /// Executes the destructor (if any) of the pointed-to value.
1073    ///
1074    /// See [`ptr::drop_in_place`] for safety concerns and examples.
1075    ///
1076    /// [`ptr::drop_in_place`]: crate::ptr::drop_in_place()
1077    #[inline(always)]
1078    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1079    pub unsafe fn drop_in_place(self) {
1080        // SAFETY: the caller must uphold the safety contract for `drop_in_place`.
1081        unsafe { ptr::drop_in_place(self.as_ptr()) }
1082    }
1083
1084    /// Overwrites a memory location with the given value without reading or
1085    /// dropping the old value.
1086    ///
1087    /// See [`ptr::write`] for safety concerns and examples.
1088    ///
1089    /// [`ptr::write`]: crate::ptr::write()
1090    #[inline(always)]
1091    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1092    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1093    #[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
1094    pub const unsafe fn write(self, val: T)
1095    where
1096        T: Sized,
1097    {
1098        // SAFETY: the caller must uphold the safety contract for `write`.
1099        unsafe { ptr::write(self.as_ptr(), val) }
1100    }
1101
1102    /// Invokes memset on the specified pointer, setting `count * size_of::<T>()`
1103    /// bytes of memory starting at `self` to `val`.
1104    ///
1105    /// See [`ptr::write_bytes`] for safety concerns and examples.
1106    ///
1107    /// [`ptr::write_bytes`]: crate::ptr::write_bytes()
1108    #[inline(always)]
1109    #[doc(alias = "memset")]
1110    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1111    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1112    #[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
1113    pub const unsafe fn write_bytes(self, val: u8, count: usize)
1114    where
1115        T: Sized,
1116    {
1117        // SAFETY: the caller must uphold the safety contract for `write_bytes`.
1118        unsafe { ptr::write_bytes(self.as_ptr(), val, count) }
1119    }
1120
1121    /// Performs a volatile write of a memory location with the given value without
1122    /// reading or dropping the old value.
1123    ///
1124    /// Volatile operations are intended to act on I/O memory, and are guaranteed
1125    /// to not be elided or reordered by the compiler across other volatile
1126    /// operations.
1127    ///
1128    /// See [`ptr::write_volatile`] for safety concerns and examples.
1129    ///
1130    /// [`ptr::write_volatile`]: crate::ptr::write_volatile()
1131    #[inline(always)]
1132    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1133    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1134    pub unsafe fn write_volatile(self, val: T)
1135    where
1136        T: Sized,
1137    {
1138        // SAFETY: the caller must uphold the safety contract for `write_volatile`.
1139        unsafe { ptr::write_volatile(self.as_ptr(), val) }
1140    }
1141
1142    /// Overwrites a memory location with the given value without reading or
1143    /// dropping the old value.
1144    ///
1145    /// Unlike `write`, the pointer may be unaligned.
1146    ///
1147    /// See [`ptr::write_unaligned`] for safety concerns and examples.
1148    ///
1149    /// [`ptr::write_unaligned`]: crate::ptr::write_unaligned()
1150    #[inline(always)]
1151    #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
1152    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1153    #[rustc_const_stable(feature = "const_ptr_write", since = "1.83.0")]
1154    pub const unsafe fn write_unaligned(self, val: T)
1155    where
1156        T: Sized,
1157    {
1158        // SAFETY: the caller must uphold the safety contract for `write_unaligned`.
1159        unsafe { ptr::write_unaligned(self.as_ptr(), val) }
1160    }
1161
1162    /// Replaces the value at `self` with `src`, returning the old
1163    /// value, without dropping either.
1164    ///
1165    /// See [`ptr::replace`] for safety concerns and examples.
1166    ///
1167    /// [`ptr::replace`]: crate::ptr::replace()
1168    #[inline(always)]
1169    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1170    pub unsafe fn replace(self, src: T) -> T
1171    where
1172        T: Sized,
1173    {
1174        // SAFETY: the caller must uphold the safety contract for `replace`.
1175        unsafe { ptr::replace(self.as_ptr(), src) }
1176    }
1177
1178    /// Swaps the values at two mutable locations of the same type, without
1179    /// deinitializing either. They may overlap, unlike `mem::swap` which is
1180    /// otherwise equivalent.
1181    ///
1182    /// See [`ptr::swap`] for safety concerns and examples.
1183    ///
1184    /// [`ptr::swap`]: crate::ptr::swap()
1185    #[inline(always)]
1186    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1187    #[rustc_const_stable(feature = "const_swap", since = "1.85.0")]
1188    pub const unsafe fn swap(self, with: NonNull<T>)
1189    where
1190        T: Sized,
1191    {
1192        // SAFETY: the caller must uphold the safety contract for `swap`.
1193        unsafe { ptr::swap(self.as_ptr(), with.as_ptr()) }
1194    }
1195
1196    /// Computes the offset that needs to be applied to the pointer in order to make it aligned to
1197    /// `align`.
1198    ///
1199    /// If it is not possible to align the pointer, the implementation returns
1200    /// `usize::MAX`.
1201    ///
1202    /// The offset is expressed in number of `T` elements, and not bytes.
1203    ///
1204    /// There are no guarantees whatsoever that offsetting the pointer will not overflow or go
1205    /// beyond the allocation that the pointer points into. It is up to the caller to ensure that
1206    /// the returned offset is correct in all terms other than alignment.
1207    ///
1208    /// When this is called during compile-time evaluation (which is unstable), the implementation
1209    /// may return `usize::MAX` in cases where that can never happen at runtime. This is because the
1210    /// actual alignment of pointers is not known yet during compile-time, so an offset with
1211    /// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8;
1212    /// N]` might be allocated at an odd or an even address, but at compile-time this is not yet
1213    /// known, so the execution has to be correct for either choice. It is therefore impossible to
1214    /// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual
1215    /// for unstable APIs.)
1216    ///
1217    /// # Panics
1218    ///
1219    /// The function panics if `align` is not a power-of-two.
1220    ///
1221    /// # Examples
1222    ///
1223    /// Accessing adjacent `u8` as `u16`
1224    ///
1225    /// ```
1226    /// use std::mem::align_of;
1227    /// use std::ptr::NonNull;
1228    ///
1229    /// # unsafe {
1230    /// let x = [5_u8, 6, 7, 8, 9];
1231    /// let ptr = NonNull::new(x.as_ptr() as *mut u8).unwrap();
1232    /// let offset = ptr.align_offset(align_of::<u16>());
1233    ///
1234    /// if offset < x.len() - 1 {
1235    ///     let u16_ptr = ptr.add(offset).cast::<u16>();
1236    ///     assert!(u16_ptr.read() == u16::from_ne_bytes([5, 6]) || u16_ptr.read() == u16::from_ne_bytes([6, 7]));
1237    /// } else {
1238    ///     // while the pointer can be aligned via `offset`, it would point
1239    ///     // outside the allocation
1240    /// }
1241    /// # }
1242    /// ```
1243    #[inline]
1244    #[must_use]
1245    #[stable(feature = "non_null_convenience", since = "1.80.0")]
1246    pub fn align_offset(self, align: usize) -> usize
1247    where
1248        T: Sized,
1249    {
1250        if !align.is_power_of_two() {
1251            panic!("align_offset: align is not a power-of-two");
1252        }
1253
1254        {
1255            // SAFETY: `align` has been checked to be a power of 2 above.
1256            unsafe { ptr::align_offset(self.as_ptr(), align) }
1257        }
1258    }
1259
1260    /// Returns whether the pointer is properly aligned for `T`.
1261    ///
1262    /// # Examples
1263    ///
1264    /// ```
1265    /// use std::ptr::NonNull;
1266    ///
1267    /// // On some platforms, the alignment of i32 is less than 4.
1268    /// #[repr(align(4))]
1269    /// struct AlignedI32(i32);
1270    ///
1271    /// let data = AlignedI32(42);
1272    /// let ptr = NonNull::<AlignedI32>::from(&data);
1273    ///
1274    /// assert!(ptr.is_aligned());
1275    /// assert!(!NonNull::new(ptr.as_ptr().wrapping_byte_add(1)).unwrap().is_aligned());
1276    /// ```
1277    #[inline]
1278    #[must_use]
1279    #[stable(feature = "pointer_is_aligned", since = "1.79.0")]
1280    pub fn is_aligned(self) -> bool
1281    where
1282        T: Sized,
1283    {
1284        self.as_ptr().is_aligned()
1285    }
1286
1287    /// Returns whether the pointer is aligned to `align`.
1288    ///
1289    /// For non-`Sized` pointees this operation considers only the data pointer,
1290    /// ignoring the metadata.
1291    ///
1292    /// # Panics
1293    ///
1294    /// The function panics if `align` is not a power-of-two (this includes 0).
1295    ///
1296    /// # Examples
1297    ///
1298    /// ```
1299    /// #![feature(pointer_is_aligned_to)]
1300    ///
1301    /// // On some platforms, the alignment of i32 is less than 4.
1302    /// #[repr(align(4))]
1303    /// struct AlignedI32(i32);
1304    ///
1305    /// let data = AlignedI32(42);
1306    /// let ptr = &data as *const AlignedI32;
1307    ///
1308    /// assert!(ptr.is_aligned_to(1));
1309    /// assert!(ptr.is_aligned_to(2));
1310    /// assert!(ptr.is_aligned_to(4));
1311    ///
1312    /// assert!(ptr.wrapping_byte_add(2).is_aligned_to(2));
1313    /// assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4));
1314    ///
1315    /// assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8));
1316    /// ```
1317    #[inline]
1318    #[must_use]
1319    #[unstable(feature = "pointer_is_aligned_to", issue = "96284")]
1320    pub fn is_aligned_to(self, align: usize) -> bool {
1321        self.as_ptr().is_aligned_to(align)
1322    }
1323}
1324
1325impl<T> NonNull<[T]> {
1326    /// Creates a non-null raw slice from a thin pointer and a length.
1327    ///
1328    /// The `len` argument is the number of **elements**, not the number of bytes.
1329    ///
1330    /// This function is safe, but dereferencing the return value is unsafe.
1331    /// See the documentation of [`slice::from_raw_parts`] for slice safety requirements.
1332    ///
1333    /// # Examples
1334    ///
1335    /// ```rust
1336    /// use std::ptr::NonNull;
1337    ///
1338    /// // create a slice pointer when starting out with a pointer to the first element
1339    /// let mut x = [5, 6, 7];
1340    /// let nonnull_pointer = NonNull::new(x.as_mut_ptr()).unwrap();
1341    /// let slice = NonNull::slice_from_raw_parts(nonnull_pointer, 3);
1342    /// assert_eq!(unsafe { slice.as_ref()[2] }, 7);
1343    /// ```
1344    ///
1345    /// (Note that this example artificially demonstrates a use of this method,
1346    /// but `let slice = NonNull::from(&x[..]);` would be a better way to write code like this.)
1347    #[stable(feature = "nonnull_slice_from_raw_parts", since = "1.70.0")]
1348    #[rustc_const_stable(feature = "const_slice_from_raw_parts_mut", since = "1.83.0")]
1349    #[must_use]
1350    #[inline]
1351    pub const fn slice_from_raw_parts(data: NonNull<T>, len: usize) -> Self {
1352        // SAFETY: `data` is a `NonNull` pointer which is necessarily non-null
1353        unsafe { Self::new_unchecked(super::slice_from_raw_parts_mut(data.as_ptr(), len)) }
1354    }
1355
1356    /// Returns the length of a non-null raw slice.
1357    ///
1358    /// The returned value is the number of **elements**, not the number of bytes.
1359    ///
1360    /// This function is safe, even when the non-null raw slice cannot be dereferenced to a slice
1361    /// because the pointer does not have a valid address.
1362    ///
1363    /// # Examples
1364    ///
1365    /// ```rust
1366    /// use std::ptr::NonNull;
1367    ///
1368    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
1369    /// assert_eq!(slice.len(), 3);
1370    /// ```
1371    #[stable(feature = "slice_ptr_len_nonnull", since = "1.63.0")]
1372    #[rustc_const_stable(feature = "const_slice_ptr_len_nonnull", since = "1.63.0")]
1373    #[must_use]
1374    #[inline]
1375    pub const fn len(self) -> usize {
1376        self.as_ptr().len()
1377    }
1378
1379    /// Returns `true` if the non-null raw slice has a length of 0.
1380    ///
1381    /// # Examples
1382    ///
1383    /// ```rust
1384    /// use std::ptr::NonNull;
1385    ///
1386    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
1387    /// assert!(!slice.is_empty());
1388    /// ```
1389    #[stable(feature = "slice_ptr_is_empty_nonnull", since = "1.79.0")]
1390    #[rustc_const_stable(feature = "const_slice_ptr_is_empty_nonnull", since = "1.79.0")]
1391    #[must_use]
1392    #[inline]
1393    pub const fn is_empty(self) -> bool {
1394        self.len() == 0
1395    }
1396
1397    /// Returns a non-null pointer to the slice's buffer.
1398    ///
1399    /// # Examples
1400    ///
1401    /// ```rust
1402    /// #![feature(slice_ptr_get)]
1403    /// use std::ptr::NonNull;
1404    ///
1405    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
1406    /// assert_eq!(slice.as_non_null_ptr(), NonNull::<i8>::dangling());
1407    /// ```
1408    #[inline]
1409    #[must_use]
1410    #[unstable(feature = "slice_ptr_get", issue = "74265")]
1411    pub const fn as_non_null_ptr(self) -> NonNull<T> {
1412        self.cast()
1413    }
1414
1415    /// Returns a raw pointer to the slice's buffer.
1416    ///
1417    /// # Examples
1418    ///
1419    /// ```rust
1420    /// #![feature(slice_ptr_get)]
1421    /// use std::ptr::NonNull;
1422    ///
1423    /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3);
1424    /// assert_eq!(slice.as_mut_ptr(), NonNull::<i8>::dangling().as_ptr());
1425    /// ```
1426    #[inline]
1427    #[must_use]
1428    #[unstable(feature = "slice_ptr_get", issue = "74265")]
1429    #[rustc_never_returns_null_ptr]
1430    pub const fn as_mut_ptr(self) -> *mut T {
1431        self.as_non_null_ptr().as_ptr()
1432    }
1433
1434    /// Returns a shared reference to a slice of possibly uninitialized values. In contrast to
1435    /// [`as_ref`], this does not require that the value has to be initialized.
1436    ///
1437    /// For the mutable counterpart see [`as_uninit_slice_mut`].
1438    ///
1439    /// [`as_ref`]: NonNull::as_ref
1440    /// [`as_uninit_slice_mut`]: NonNull::as_uninit_slice_mut
1441    ///
1442    /// # Safety
1443    ///
1444    /// When calling this method, you have to ensure that all of the following is true:
1445    ///
1446    /// * The pointer must be [valid] for reads for `ptr.len() * mem::size_of::<T>()` many bytes,
1447    ///   and it must be properly aligned. This means in particular:
1448    ///
1449    ///     * The entire memory range of this slice must be contained within a single allocated object!
1450    ///       Slices can never span across multiple allocated objects.
1451    ///
1452    ///     * The pointer must be aligned even for zero-length slices. One
1453    ///       reason for this is that enum layout optimizations may rely on references
1454    ///       (including slices of any length) being aligned and non-null to distinguish
1455    ///       them from other data. You can obtain a pointer that is usable as `data`
1456    ///       for zero-length slices using [`NonNull::dangling()`].
1457    ///
1458    /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
1459    ///   See the safety documentation of [`pointer::offset`].
1460    ///
1461    /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
1462    ///   arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
1463    ///   In particular, while this reference exists, the memory the pointer points to must
1464    ///   not get mutated (except inside `UnsafeCell`).
1465    ///
1466    /// This applies even if the result of this method is unused!
1467    ///
1468    /// See also [`slice::from_raw_parts`].
1469    ///
1470    /// [valid]: crate::ptr#safety
1471    #[inline]
1472    #[must_use]
1473    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
1474    pub const unsafe fn as_uninit_slice<'a>(self) -> &'a [MaybeUninit<T>] {
1475        // SAFETY: the caller must uphold the safety contract for `as_uninit_slice`.
1476        unsafe { slice::from_raw_parts(self.cast().as_ptr(), self.len()) }
1477    }
1478
1479    /// Returns a unique reference to a slice of possibly uninitialized values. In contrast to
1480    /// [`as_mut`], this does not require that the value has to be initialized.
1481    ///
1482    /// For the shared counterpart see [`as_uninit_slice`].
1483    ///
1484    /// [`as_mut`]: NonNull::as_mut
1485    /// [`as_uninit_slice`]: NonNull::as_uninit_slice
1486    ///
1487    /// # Safety
1488    ///
1489    /// When calling this method, you have to ensure that all of the following is true:
1490    ///
1491    /// * The pointer must be [valid] for reads and writes for `ptr.len() * mem::size_of::<T>()`
1492    ///   many bytes, and it must be properly aligned. This means in particular:
1493    ///
1494    ///     * The entire memory range of this slice must be contained within a single allocated object!
1495    ///       Slices can never span across multiple allocated objects.
1496    ///
1497    ///     * The pointer must be aligned even for zero-length slices. One
1498    ///       reason for this is that enum layout optimizations may rely on references
1499    ///       (including slices of any length) being aligned and non-null to distinguish
1500    ///       them from other data. You can obtain a pointer that is usable as `data`
1501    ///       for zero-length slices using [`NonNull::dangling()`].
1502    ///
1503    /// * The total size `ptr.len() * mem::size_of::<T>()` of the slice must be no larger than `isize::MAX`.
1504    ///   See the safety documentation of [`pointer::offset`].
1505    ///
1506    /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is
1507    ///   arbitrarily chosen and does not necessarily reflect the actual lifetime of the data.
1508    ///   In particular, while this reference exists, the memory the pointer points to must
1509    ///   not get accessed (read or written) through any other pointer.
1510    ///
1511    /// This applies even if the result of this method is unused!
1512    ///
1513    /// See also [`slice::from_raw_parts_mut`].
1514    ///
1515    /// [valid]: crate::ptr#safety
1516    ///
1517    /// # Examples
1518    ///
1519    /// ```rust
1520    /// #![feature(allocator_api, ptr_as_uninit)]
1521    ///
1522    /// use std::alloc::{Allocator, Layout, Global};
1523    /// use std::mem::MaybeUninit;
1524    /// use std::ptr::NonNull;
1525    ///
1526    /// let memory: NonNull<[u8]> = Global.allocate(Layout::new::<[u8; 32]>())?;
1527    /// // This is safe as `memory` is valid for reads and writes for `memory.len()` many bytes.
1528    /// // Note that calling `memory.as_mut()` is not allowed here as the content may be uninitialized.
1529    /// # #[allow(unused_variables)]
1530    /// let slice: &mut [MaybeUninit<u8>] = unsafe { memory.as_uninit_slice_mut() };
1531    /// # // Prevent leaks for Miri.
1532    /// # unsafe { Global.deallocate(memory.cast(), Layout::new::<[u8; 32]>()); }
1533    /// # Ok::<_, std::alloc::AllocError>(())
1534    /// ```
1535    #[inline]
1536    #[must_use]
1537    #[unstable(feature = "ptr_as_uninit", issue = "75402")]
1538    pub const unsafe fn as_uninit_slice_mut<'a>(self) -> &'a mut [MaybeUninit<T>] {
1539        // SAFETY: the caller must uphold the safety contract for `as_uninit_slice_mut`.
1540        unsafe { slice::from_raw_parts_mut(self.cast().as_ptr(), self.len()) }
1541    }
1542
1543    /// Returns a raw pointer to an element or subslice, without doing bounds
1544    /// checking.
1545    ///
1546    /// Calling this method with an out-of-bounds index or when `self` is not dereferenceable
1547    /// is *[undefined behavior]* even if the resulting pointer is not used.
1548    ///
1549    /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
1550    ///
1551    /// # Examples
1552    ///
1553    /// ```
1554    /// #![feature(slice_ptr_get)]
1555    /// use std::ptr::NonNull;
1556    ///
1557    /// let x = &mut [1, 2, 4];
1558    /// let x = NonNull::slice_from_raw_parts(NonNull::new(x.as_mut_ptr()).unwrap(), x.len());
1559    ///
1560    /// unsafe {
1561    ///     assert_eq!(x.get_unchecked_mut(1).as_ptr(), x.as_non_null_ptr().as_ptr().add(1));
1562    /// }
1563    /// ```
1564    #[unstable(feature = "slice_ptr_get", issue = "74265")]
1565    #[inline]
1566    pub unsafe fn get_unchecked_mut<I>(self, index: I) -> NonNull<I::Output>
1567    where
1568        I: SliceIndex<[T]>,
1569    {
1570        // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds.
1571        // As a consequence, the resulting pointer cannot be null.
1572        unsafe { NonNull::new_unchecked(self.as_ptr().get_unchecked_mut(index)) }
1573    }
1574}
1575
1576#[stable(feature = "nonnull", since = "1.25.0")]
1577impl<T: ?Sized> Clone for NonNull<T> {
1578    #[inline(always)]
1579    fn clone(&self) -> Self {
1580        *self
1581    }
1582}
1583
1584#[stable(feature = "nonnull", since = "1.25.0")]
1585impl<T: ?Sized> Copy for NonNull<T> {}
1586
1587#[unstable(feature = "coerce_unsized", issue = "18598")]
1588impl<T: ?Sized, U: ?Sized> CoerceUnsized<NonNull<U>> for NonNull<T> where T: Unsize<U> {}
1589
1590#[unstable(feature = "dispatch_from_dyn", issue = "none")]
1591impl<T: ?Sized, U: ?Sized> DispatchFromDyn<NonNull<U>> for NonNull<T> where T: Unsize<U> {}
1592
1593#[stable(feature = "pin", since = "1.33.0")]
1594unsafe impl<T: ?Sized> PinCoerceUnsized for NonNull<T> {}
1595
1596#[unstable(feature = "pointer_like_trait", issue = "none")]
1597impl<T> core::marker::PointerLike for NonNull<T> {}
1598
1599#[stable(feature = "nonnull", since = "1.25.0")]
1600impl<T: ?Sized> fmt::Debug for NonNull<T> {
1601    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1602        fmt::Pointer::fmt(&self.as_ptr(), f)
1603    }
1604}
1605
1606#[stable(feature = "nonnull", since = "1.25.0")]
1607impl<T: ?Sized> fmt::Pointer for NonNull<T> {
1608    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1609        fmt::Pointer::fmt(&self.as_ptr(), f)
1610    }
1611}
1612
1613#[stable(feature = "nonnull", since = "1.25.0")]
1614impl<T: ?Sized> Eq for NonNull<T> {}
1615
1616#[stable(feature = "nonnull", since = "1.25.0")]
1617impl<T: ?Sized> PartialEq for NonNull<T> {
1618    #[inline]
1619    #[allow(ambiguous_wide_pointer_comparisons)]
1620    fn eq(&self, other: &Self) -> bool {
1621        self.as_ptr() == other.as_ptr()
1622    }
1623}
1624
1625#[stable(feature = "nonnull", since = "1.25.0")]
1626impl<T: ?Sized> Ord for NonNull<T> {
1627    #[inline]
1628    #[allow(ambiguous_wide_pointer_comparisons)]
1629    fn cmp(&self, other: &Self) -> Ordering {
1630        self.as_ptr().cmp(&other.as_ptr())
1631    }
1632}
1633
1634#[stable(feature = "nonnull", since = "1.25.0")]
1635impl<T: ?Sized> PartialOrd for NonNull<T> {
1636    #[inline]
1637    #[allow(ambiguous_wide_pointer_comparisons)]
1638    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
1639        self.as_ptr().partial_cmp(&other.as_ptr())
1640    }
1641}
1642
1643#[stable(feature = "nonnull", since = "1.25.0")]
1644impl<T: ?Sized> hash::Hash for NonNull<T> {
1645    #[inline]
1646    fn hash<H: hash::Hasher>(&self, state: &mut H) {
1647        self.as_ptr().hash(state)
1648    }
1649}
1650
1651#[unstable(feature = "ptr_internals", issue = "none")]
1652impl<T: ?Sized> From<Unique<T>> for NonNull<T> {
1653    #[inline]
1654    fn from(unique: Unique<T>) -> Self {
1655        unique.as_non_null_ptr()
1656    }
1657}
1658
1659#[stable(feature = "nonnull", since = "1.25.0")]
1660impl<T: ?Sized> From<&mut T> for NonNull<T> {
1661    /// Converts a `&mut T` to a `NonNull<T>`.
1662    ///
1663    /// This conversion is safe and infallible since references cannot be null.
1664    #[inline]
1665    fn from(r: &mut T) -> Self {
1666        NonNull::from_mut(r)
1667    }
1668}
1669
1670#[stable(feature = "nonnull", since = "1.25.0")]
1671impl<T: ?Sized> From<&T> for NonNull<T> {
1672    /// Converts a `&T` to a `NonNull<T>`.
1673    ///
1674    /// This conversion is safe and infallible since references cannot be null.
1675    #[inline]
1676    fn from(r: &T) -> Self {
1677        NonNull::from_ref(r)
1678    }
1679}