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