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}