core/ptr/const_ptr.rs
1use super::*;
2use crate::cmp::Ordering::{Equal, Greater, Less};
3use crate::intrinsics::const_eval_select;
4use crate::mem::{self, SizedTypeProperties};
5use crate::slice::{self, SliceIndex};
6
7impl<T: PointeeSized> *const T {
8 #[doc = include_str!("docs/is_null.md")]
9 ///
10 /// # Examples
11 ///
12 /// ```
13 /// let s: &str = "Follow the rabbit";
14 /// let ptr: *const u8 = s.as_ptr();
15 /// assert!(!ptr.is_null());
16 /// ```
17 #[stable(feature = "rust1", since = "1.0.0")]
18 #[rustc_const_stable(feature = "const_ptr_is_null", since = "1.84.0")]
19 #[rustc_diagnostic_item = "ptr_const_is_null"]
20 #[inline]
21 #[rustc_allow_const_fn_unstable(const_eval_select)]
22 pub const fn is_null(self) -> bool {
23 // Compare via a cast to a thin pointer, so fat pointers are only
24 // considering their "data" part for null-ness.
25 let ptr = self as *const u8;
26 const_eval_select!(
27 @capture { ptr: *const u8 } -> bool:
28 // This use of `const_raw_ptr_comparison` has been explicitly blessed by t-lang.
29 if const #[rustc_allow_const_fn_unstable(const_raw_ptr_comparison)] {
30 match (ptr).guaranteed_eq(null_mut()) {
31 Some(res) => res,
32 // To remain maximally convervative, we stop execution when we don't
33 // know whether the pointer is null or not.
34 // We can *not* return `false` here, that would be unsound in `NonNull::new`!
35 None => panic!("null-ness of this pointer cannot be determined in const context"),
36 }
37 } else {
38 ptr.addr() == 0
39 }
40 )
41 }
42
43 /// Casts to a pointer of another type.
44 #[stable(feature = "ptr_cast", since = "1.38.0")]
45 #[rustc_const_stable(feature = "const_ptr_cast", since = "1.38.0")]
46 #[rustc_diagnostic_item = "const_ptr_cast"]
47 #[inline(always)]
48 pub const fn cast<U>(self) -> *const U {
49 self as _
50 }
51
52 /// Try to cast to a pointer of another type by checking aligment.
53 ///
54 /// If the pointer is properly aligned to the target type, it will be
55 /// cast to the target type. Otherwise, `None` is returned.
56 ///
57 /// # Examples
58 ///
59 /// ```rust
60 /// #![feature(pointer_try_cast_aligned)]
61 ///
62 /// let x = 0u64;
63 ///
64 /// let aligned: *const u64 = &x;
65 /// let unaligned = unsafe { aligned.byte_add(1) };
66 ///
67 /// assert!(aligned.try_cast_aligned::<u32>().is_some());
68 /// assert!(unaligned.try_cast_aligned::<u32>().is_none());
69 /// ```
70 #[unstable(feature = "pointer_try_cast_aligned", issue = "141221")]
71 #[must_use = "this returns the result of the operation, \
72 without modifying the original"]
73 #[inline]
74 pub fn try_cast_aligned<U>(self) -> Option<*const U> {
75 if self.is_aligned_to(align_of::<U>()) { Some(self.cast()) } else { None }
76 }
77
78 /// Uses the address value in a new pointer of another type.
79 ///
80 /// This operation will ignore the address part of its `meta` operand and discard existing
81 /// metadata of `self`. For pointers to a sized types (thin pointers), this has the same effect
82 /// as a simple cast. For pointers to an unsized type (fat pointers) this recombines the address
83 /// with new metadata such as slice lengths or `dyn`-vtable.
84 ///
85 /// The resulting pointer will have provenance of `self`. This operation is semantically the
86 /// same as creating a new pointer with the data pointer value of `self` but the metadata of
87 /// `meta`, being fat or thin depending on the `meta` operand.
88 ///
89 /// # Examples
90 ///
91 /// This function is primarily useful for enabling pointer arithmetic on potentially fat
92 /// pointers. The pointer is cast to a sized pointee to utilize offset operations and then
93 /// recombined with its own original metadata.
94 ///
95 /// ```
96 /// #![feature(set_ptr_value)]
97 /// # use core::fmt::Debug;
98 /// let arr: [i32; 3] = [1, 2, 3];
99 /// let mut ptr = arr.as_ptr() as *const dyn Debug;
100 /// let thin = ptr as *const u8;
101 /// unsafe {
102 /// ptr = thin.add(8).with_metadata_of(ptr);
103 /// # assert_eq!(*(ptr as *const i32), 3);
104 /// println!("{:?}", &*ptr); // will print "3"
105 /// }
106 /// ```
107 ///
108 /// # *Incorrect* usage
109 ///
110 /// The provenance from pointers is *not* combined. The result must only be used to refer to the
111 /// address allowed by `self`.
112 ///
113 /// ```rust,no_run
114 /// #![feature(set_ptr_value)]
115 /// let x = 0u32;
116 /// let y = 1u32;
117 ///
118 /// let x = (&x) as *const u32;
119 /// let y = (&y) as *const u32;
120 ///
121 /// let offset = (x as usize - y as usize) / 4;
122 /// let bad = x.wrapping_add(offset).with_metadata_of(y);
123 ///
124 /// // This dereference is UB. The pointer only has provenance for `x` but points to `y`.
125 /// println!("{:?}", unsafe { &*bad });
126 /// ```
127 #[unstable(feature = "set_ptr_value", issue = "75091")]
128 #[must_use = "returns a new pointer rather than modifying its argument"]
129 #[inline]
130 pub const fn with_metadata_of<U>(self, meta: *const U) -> *const U
131 where
132 U: PointeeSized,
133 {
134 from_raw_parts::<U>(self as *const (), metadata(meta))
135 }
136
137 /// Changes constness without changing the type.
138 ///
139 /// This is a bit safer than `as` because it wouldn't silently change the type if the code is
140 /// refactored.
141 #[stable(feature = "ptr_const_cast", since = "1.65.0")]
142 #[rustc_const_stable(feature = "ptr_const_cast", since = "1.65.0")]
143 #[rustc_diagnostic_item = "ptr_cast_mut"]
144 #[inline(always)]
145 pub const fn cast_mut(self) -> *mut T {
146 self as _
147 }
148
149 /// Gets the "address" portion of the pointer.
150 ///
151 /// This is similar to `self as usize`, except that the [provenance][crate::ptr#provenance] of
152 /// the pointer is discarded and not [exposed][crate::ptr#exposed-provenance]. This means that
153 /// casting the returned address back to a pointer yields a [pointer without
154 /// provenance][without_provenance], which is undefined behavior to dereference. To properly
155 /// restore the lost information and obtain a dereferenceable pointer, use
156 /// [`with_addr`][pointer::with_addr] or [`map_addr`][pointer::map_addr].
157 ///
158 /// If using those APIs is not possible because there is no way to preserve a pointer with the
159 /// required provenance, then Strict Provenance might not be for you. Use pointer-integer casts
160 /// or [`expose_provenance`][pointer::expose_provenance] and [`with_exposed_provenance`][with_exposed_provenance]
161 /// instead. However, note that this makes your code less portable and less amenable to tools
162 /// that check for compliance with the Rust memory model.
163 ///
164 /// On most platforms this will produce a value with the same bytes as the original
165 /// pointer, because all the bytes are dedicated to describing the address.
166 /// Platforms which need to store additional information in the pointer may
167 /// perform a change of representation to produce a value containing only the address
168 /// portion of the pointer. What that means is up to the platform to define.
169 ///
170 /// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
171 #[must_use]
172 #[inline(always)]
173 #[stable(feature = "strict_provenance", since = "1.84.0")]
174 pub fn addr(self) -> usize {
175 // A pointer-to-integer transmute currently has exactly the right semantics: it returns the
176 // address without exposing the provenance. Note that this is *not* a stable guarantee about
177 // transmute semantics, it relies on sysroot crates having special status.
178 // SAFETY: Pointer-to-integer transmutes are valid (if you are okay with losing the
179 // provenance).
180 unsafe { mem::transmute(self.cast::<()>()) }
181 }
182
183 /// Exposes the ["provenance"][crate::ptr#provenance] part of the pointer for future use in
184 /// [`with_exposed_provenance`] and returns the "address" portion.
185 ///
186 /// This is equivalent to `self as usize`, which semantically discards provenance information.
187 /// Furthermore, this (like the `as` cast) has the implicit side-effect of marking the
188 /// provenance as 'exposed', so on platforms that support it you can later call
189 /// [`with_exposed_provenance`] to reconstitute the original pointer including its provenance.
190 ///
191 /// Due to its inherent ambiguity, [`with_exposed_provenance`] may not be supported by tools
192 /// that help you to stay conformant with the Rust memory model. It is recommended to use
193 /// [Strict Provenance][crate::ptr#strict-provenance] APIs such as [`with_addr`][pointer::with_addr]
194 /// wherever possible, in which case [`addr`][pointer::addr] should be used instead of `expose_provenance`.
195 ///
196 /// On most platforms this will produce a value with the same bytes as the original pointer,
197 /// because all the bytes are dedicated to describing the address. Platforms which need to store
198 /// additional information in the pointer may not support this operation, since the 'expose'
199 /// side-effect which is required for [`with_exposed_provenance`] to work is typically not
200 /// available.
201 ///
202 /// This is an [Exposed Provenance][crate::ptr#exposed-provenance] API.
203 ///
204 /// [`with_exposed_provenance`]: with_exposed_provenance
205 #[inline(always)]
206 #[stable(feature = "exposed_provenance", since = "1.84.0")]
207 pub fn expose_provenance(self) -> usize {
208 self.cast::<()>() as usize
209 }
210
211 /// Creates a new pointer with the given address and the [provenance][crate::ptr#provenance] of
212 /// `self`.
213 ///
214 /// This is similar to a `addr as *const T` cast, but copies
215 /// the *provenance* of `self` to the new pointer.
216 /// This avoids the inherent ambiguity of the unary cast.
217 ///
218 /// This is equivalent to using [`wrapping_offset`][pointer::wrapping_offset] to offset
219 /// `self` to the given address, and therefore has all the same capabilities and restrictions.
220 ///
221 /// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
222 #[must_use]
223 #[inline]
224 #[stable(feature = "strict_provenance", since = "1.84.0")]
225 pub fn with_addr(self, addr: usize) -> Self {
226 // This should probably be an intrinsic to avoid doing any sort of arithmetic, but
227 // meanwhile, we can implement it with `wrapping_offset`, which preserves the pointer's
228 // provenance.
229 let self_addr = self.addr() as isize;
230 let dest_addr = addr as isize;
231 let offset = dest_addr.wrapping_sub(self_addr);
232 self.wrapping_byte_offset(offset)
233 }
234
235 /// Creates a new pointer by mapping `self`'s address to a new one, preserving the
236 /// [provenance][crate::ptr#provenance] of `self`.
237 ///
238 /// This is a convenience for [`with_addr`][pointer::with_addr], see that method for details.
239 ///
240 /// This is a [Strict Provenance][crate::ptr#strict-provenance] API.
241 #[must_use]
242 #[inline]
243 #[stable(feature = "strict_provenance", since = "1.84.0")]
244 pub fn map_addr(self, f: impl FnOnce(usize) -> usize) -> Self {
245 self.with_addr(f(self.addr()))
246 }
247
248 /// Decompose a (possibly wide) pointer into its data pointer and metadata components.
249 ///
250 /// The pointer can be later reconstructed with [`from_raw_parts`].
251 #[unstable(feature = "ptr_metadata", issue = "81513")]
252 #[inline]
253 pub const fn to_raw_parts(self) -> (*const (), <T as super::Pointee>::Metadata) {
254 (self.cast(), metadata(self))
255 }
256
257 /// Returns `None` if the pointer is null, or else returns a shared reference to
258 /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`]
259 /// must be used instead.
260 ///
261 /// [`as_uninit_ref`]: #method.as_uninit_ref
262 ///
263 /// # Safety
264 ///
265 /// When calling this method, you have to ensure that *either* the pointer is null *or*
266 /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
267 ///
268 /// # Panics during const evaluation
269 ///
270 /// This method will panic during const evaluation if the pointer cannot be
271 /// determined to be null or not. See [`is_null`] for more information.
272 ///
273 /// [`is_null`]: #method.is_null
274 ///
275 /// # Examples
276 ///
277 /// ```
278 /// let ptr: *const u8 = &10u8 as *const u8;
279 ///
280 /// unsafe {
281 /// if let Some(val_back) = ptr.as_ref() {
282 /// assert_eq!(val_back, &10);
283 /// }
284 /// }
285 /// ```
286 ///
287 /// # Null-unchecked version
288 ///
289 /// If you are sure the pointer can never be null and are looking for some kind of
290 /// `as_ref_unchecked` that returns the `&T` instead of `Option<&T>`, know that you can
291 /// dereference the pointer directly.
292 ///
293 /// ```
294 /// let ptr: *const u8 = &10u8 as *const u8;
295 ///
296 /// unsafe {
297 /// let val_back = &*ptr;
298 /// assert_eq!(val_back, &10);
299 /// }
300 /// ```
301 #[stable(feature = "ptr_as_ref", since = "1.9.0")]
302 #[rustc_const_stable(feature = "const_ptr_is_null", since = "1.84.0")]
303 #[inline]
304 pub const unsafe fn as_ref<'a>(self) -> Option<&'a T> {
305 // SAFETY: the caller must guarantee that `self` is valid
306 // for a reference if it isn't null.
307 if self.is_null() { None } else { unsafe { Some(&*self) } }
308 }
309
310 /// Returns a shared reference to the value behind the pointer.
311 /// If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead.
312 /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead.
313 ///
314 /// [`as_ref`]: #method.as_ref
315 /// [`as_uninit_ref`]: #method.as_uninit_ref
316 ///
317 /// # Safety
318 ///
319 /// When calling this method, you have to ensure that
320 /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
321 ///
322 /// # Examples
323 ///
324 /// ```
325 /// #![feature(ptr_as_ref_unchecked)]
326 /// let ptr: *const u8 = &10u8 as *const u8;
327 ///
328 /// unsafe {
329 /// assert_eq!(ptr.as_ref_unchecked(), &10);
330 /// }
331 /// ```
332 // FIXME: mention it in the docs for `as_ref` and `as_uninit_ref` once stabilized.
333 #[unstable(feature = "ptr_as_ref_unchecked", issue = "122034")]
334 #[inline]
335 #[must_use]
336 pub const unsafe fn as_ref_unchecked<'a>(self) -> &'a T {
337 // SAFETY: the caller must guarantee that `self` is valid for a reference
338 unsafe { &*self }
339 }
340
341 /// Returns `None` if the pointer is null, or else returns a shared reference to
342 /// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require
343 /// that the value has to be initialized.
344 ///
345 /// [`as_ref`]: #method.as_ref
346 ///
347 /// # Safety
348 ///
349 /// When calling this method, you have to ensure that *either* the pointer is null *or*
350 /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion).
351 ///
352 /// # Panics during const evaluation
353 ///
354 /// This method will panic during const evaluation if the pointer cannot be
355 /// determined to be null or not. See [`is_null`] for more information.
356 ///
357 /// [`is_null`]: #method.is_null
358 ///
359 /// # Examples
360 ///
361 /// ```
362 /// #![feature(ptr_as_uninit)]
363 ///
364 /// let ptr: *const u8 = &10u8 as *const u8;
365 ///
366 /// unsafe {
367 /// if let Some(val_back) = ptr.as_uninit_ref() {
368 /// assert_eq!(val_back.assume_init(), 10);
369 /// }
370 /// }
371 /// ```
372 #[inline]
373 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
374 pub const unsafe fn as_uninit_ref<'a>(self) -> Option<&'a MaybeUninit<T>>
375 where
376 T: Sized,
377 {
378 // SAFETY: the caller must guarantee that `self` meets all the
379 // requirements for a reference.
380 if self.is_null() { None } else { Some(unsafe { &*(self as *const MaybeUninit<T>) }) }
381 }
382
383 #[doc = include_str!("./docs/offset.md")]
384 ///
385 /// # Examples
386 ///
387 /// ```
388 /// let s: &str = "123";
389 /// let ptr: *const u8 = s.as_ptr();
390 ///
391 /// unsafe {
392 /// assert_eq!(*ptr.offset(1) as char, '2');
393 /// assert_eq!(*ptr.offset(2) as char, '3');
394 /// }
395 /// ```
396 #[stable(feature = "rust1", since = "1.0.0")]
397 #[must_use = "returns a new pointer rather than modifying its argument"]
398 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
399 #[inline(always)]
400 #[track_caller]
401 pub const unsafe fn offset(self, count: isize) -> *const T
402 where
403 T: Sized,
404 {
405 #[inline]
406 #[rustc_allow_const_fn_unstable(const_eval_select)]
407 const fn runtime_offset_nowrap(this: *const (), count: isize, size: usize) -> bool {
408 // We can use const_eval_select here because this is only for UB checks.
409 const_eval_select!(
410 @capture { this: *const (), count: isize, size: usize } -> bool:
411 if const {
412 true
413 } else {
414 // `size` is the size of a Rust type, so we know that
415 // `size <= isize::MAX` and thus `as` cast here is not lossy.
416 let Some(byte_offset) = count.checked_mul(size as isize) else {
417 return false;
418 };
419 let (_, overflow) = this.addr().overflowing_add_signed(byte_offset);
420 !overflow
421 }
422 )
423 }
424
425 ub_checks::assert_unsafe_precondition!(
426 check_language_ub,
427 "ptr::offset requires the address calculation to not overflow",
428 (
429 this: *const () = self as *const (),
430 count: isize = count,
431 size: usize = size_of::<T>(),
432 ) => runtime_offset_nowrap(this, count, size)
433 );
434
435 // SAFETY: the caller must uphold the safety contract for `offset`.
436 unsafe { intrinsics::offset(self, count) }
437 }
438
439 /// Adds a signed offset in bytes to a pointer.
440 ///
441 /// `count` is in units of **bytes**.
442 ///
443 /// This is purely a convenience for casting to a `u8` pointer and
444 /// using [offset][pointer::offset] on it. See that method for documentation
445 /// and safety requirements.
446 ///
447 /// For non-`Sized` pointees this operation changes only the data pointer,
448 /// leaving the metadata untouched.
449 #[must_use]
450 #[inline(always)]
451 #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
452 #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
453 #[track_caller]
454 pub const unsafe fn byte_offset(self, count: isize) -> Self {
455 // SAFETY: the caller must uphold the safety contract for `offset`.
456 unsafe { self.cast::<u8>().offset(count).with_metadata_of(self) }
457 }
458
459 /// Adds a signed offset to a pointer using wrapping arithmetic.
460 ///
461 /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
462 /// offset of `3 * size_of::<T>()` bytes.
463 ///
464 /// # Safety
465 ///
466 /// This operation itself is always safe, but using the resulting pointer is not.
467 ///
468 /// The resulting pointer "remembers" the [allocation] that `self` points to
469 /// (this is called "[Provenance](ptr/index.html#provenance)").
470 /// The pointer must not be used to read or write other allocations.
471 ///
472 /// In other words, `let z = x.wrapping_offset((y as isize) - (x as isize))` does *not* make `z`
473 /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
474 /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless
475 /// `x` and `y` point into the same allocation.
476 ///
477 /// Compared to [`offset`], this method basically delays the requirement of staying within the
478 /// same allocation: [`offset`] is immediate Undefined Behavior when crossing object
479 /// boundaries; `wrapping_offset` produces a pointer but still leads to Undefined Behavior if a
480 /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`offset`]
481 /// can be optimized better and is thus preferable in performance-sensitive code.
482 ///
483 /// The delayed check only considers the value of the pointer that was dereferenced, not the
484 /// intermediate values used during the computation of the final result. For example,
485 /// `x.wrapping_offset(o).wrapping_offset(o.wrapping_neg())` is always the same as `x`. In other
486 /// words, leaving the allocation and then re-entering it later is permitted.
487 ///
488 /// [`offset`]: #method.offset
489 /// [allocation]: crate::ptr#allocation
490 ///
491 /// # Examples
492 ///
493 /// ```
494 /// # use std::fmt::Write;
495 /// // Iterate using a raw pointer in increments of two elements
496 /// let data = [1u8, 2, 3, 4, 5];
497 /// let mut ptr: *const u8 = data.as_ptr();
498 /// let step = 2;
499 /// let end_rounded_up = ptr.wrapping_offset(6);
500 ///
501 /// let mut out = String::new();
502 /// while ptr != end_rounded_up {
503 /// unsafe {
504 /// write!(&mut out, "{}, ", *ptr)?;
505 /// }
506 /// ptr = ptr.wrapping_offset(step);
507 /// }
508 /// assert_eq!(out.as_str(), "1, 3, 5, ");
509 /// # std::fmt::Result::Ok(())
510 /// ```
511 #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
512 #[must_use = "returns a new pointer rather than modifying its argument"]
513 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
514 #[inline(always)]
515 pub const fn wrapping_offset(self, count: isize) -> *const T
516 where
517 T: Sized,
518 {
519 // SAFETY: the `arith_offset` intrinsic has no prerequisites to be called.
520 unsafe { intrinsics::arith_offset(self, count) }
521 }
522
523 /// Adds a signed offset in bytes to a pointer using wrapping arithmetic.
524 ///
525 /// `count` is in units of **bytes**.
526 ///
527 /// This is purely a convenience for casting to a `u8` pointer and
528 /// using [wrapping_offset][pointer::wrapping_offset] on it. See that method
529 /// for documentation.
530 ///
531 /// For non-`Sized` pointees this operation changes only the data pointer,
532 /// leaving the metadata untouched.
533 #[must_use]
534 #[inline(always)]
535 #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
536 #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
537 pub const fn wrapping_byte_offset(self, count: isize) -> Self {
538 self.cast::<u8>().wrapping_offset(count).with_metadata_of(self)
539 }
540
541 /// Masks out bits of the pointer according to a mask.
542 ///
543 /// This is convenience for `ptr.map_addr(|a| a & mask)`.
544 ///
545 /// For non-`Sized` pointees this operation changes only the data pointer,
546 /// leaving the metadata untouched.
547 ///
548 /// ## Examples
549 ///
550 /// ```
551 /// #![feature(ptr_mask)]
552 /// let v = 17_u32;
553 /// let ptr: *const u32 = &v;
554 ///
555 /// // `u32` is 4 bytes aligned,
556 /// // which means that lower 2 bits are always 0.
557 /// let tag_mask = 0b11;
558 /// let ptr_mask = !tag_mask;
559 ///
560 /// // We can store something in these lower bits
561 /// let tagged_ptr = ptr.map_addr(|a| a | 0b10);
562 ///
563 /// // Get the "tag" back
564 /// let tag = tagged_ptr.addr() & tag_mask;
565 /// assert_eq!(tag, 0b10);
566 ///
567 /// // Note that `tagged_ptr` is unaligned, it's UB to read from it.
568 /// // To get original pointer `mask` can be used:
569 /// let masked_ptr = tagged_ptr.mask(ptr_mask);
570 /// assert_eq!(unsafe { *masked_ptr }, 17);
571 /// ```
572 #[unstable(feature = "ptr_mask", issue = "98290")]
573 #[must_use = "returns a new pointer rather than modifying its argument"]
574 #[inline(always)]
575 pub fn mask(self, mask: usize) -> *const T {
576 intrinsics::ptr_mask(self.cast::<()>(), mask).with_metadata_of(self)
577 }
578
579 /// Calculates the distance between two pointers within the same allocation. The returned value is in
580 /// units of T: the distance in bytes divided by `size_of::<T>()`.
581 ///
582 /// This is equivalent to `(self as isize - origin as isize) / (size_of::<T>() as isize)`,
583 /// except that it has a lot more opportunities for UB, in exchange for the compiler
584 /// better understanding what you are doing.
585 ///
586 /// The primary motivation of this method is for computing the `len` of an array/slice
587 /// of `T` that you are currently representing as a "start" and "end" pointer
588 /// (and "end" is "one past the end" of the array).
589 /// In that case, `end.offset_from(start)` gets you the length of the array.
590 ///
591 /// All of the following safety requirements are trivially satisfied for this usecase.
592 ///
593 /// [`offset`]: #method.offset
594 ///
595 /// # Safety
596 ///
597 /// If any of the following conditions are violated, the result is Undefined Behavior:
598 ///
599 /// * `self` and `origin` must either
600 ///
601 /// * point to the same address, or
602 /// * both be [derived from][crate::ptr#provenance] a pointer to the same [allocation], and the memory range between
603 /// the two pointers must be in bounds of that object. (See below for an example.)
604 ///
605 /// * The distance between the pointers, in bytes, must be an exact multiple
606 /// of the size of `T`.
607 ///
608 /// As a consequence, the absolute distance between the pointers, in bytes, computed on
609 /// mathematical integers (without "wrapping around"), cannot overflow an `isize`. This is
610 /// implied by the in-bounds requirement, and the fact that no allocation can be larger
611 /// than `isize::MAX` bytes.
612 ///
613 /// The requirement for pointers to be derived from the same allocation is primarily
614 /// needed for `const`-compatibility: the distance between pointers into *different* allocated
615 /// objects is not known at compile-time. However, the requirement also exists at
616 /// runtime and may be exploited by optimizations. If you wish to compute the difference between
617 /// pointers that are not guaranteed to be from the same allocation, use `(self as isize -
618 /// origin as isize) / size_of::<T>()`.
619 // FIXME: recommend `addr()` instead of `as usize` once that is stable.
620 ///
621 /// [`add`]: #method.add
622 /// [allocation]: crate::ptr#allocation
623 ///
624 /// # Panics
625 ///
626 /// This function panics if `T` is a Zero-Sized Type ("ZST").
627 ///
628 /// # Examples
629 ///
630 /// Basic usage:
631 ///
632 /// ```
633 /// let a = [0; 5];
634 /// let ptr1: *const i32 = &a[1];
635 /// let ptr2: *const i32 = &a[3];
636 /// unsafe {
637 /// assert_eq!(ptr2.offset_from(ptr1), 2);
638 /// assert_eq!(ptr1.offset_from(ptr2), -2);
639 /// assert_eq!(ptr1.offset(2), ptr2);
640 /// assert_eq!(ptr2.offset(-2), ptr1);
641 /// }
642 /// ```
643 ///
644 /// *Incorrect* usage:
645 ///
646 /// ```rust,no_run
647 /// let ptr1 = Box::into_raw(Box::new(0u8)) as *const u8;
648 /// let ptr2 = Box::into_raw(Box::new(1u8)) as *const u8;
649 /// let diff = (ptr2 as isize).wrapping_sub(ptr1 as isize);
650 /// // Make ptr2_other an "alias" of ptr2.add(1), but derived from ptr1.
651 /// let ptr2_other = (ptr1 as *const u8).wrapping_offset(diff).wrapping_offset(1);
652 /// assert_eq!(ptr2 as usize, ptr2_other as usize);
653 /// // Since ptr2_other and ptr2 are derived from pointers to different objects,
654 /// // computing their offset is undefined behavior, even though
655 /// // they point to addresses that are in-bounds of the same object!
656 /// unsafe {
657 /// let one = ptr2_other.offset_from(ptr2); // Undefined Behavior! ⚠️
658 /// }
659 /// ```
660 #[stable(feature = "ptr_offset_from", since = "1.47.0")]
661 #[rustc_const_stable(feature = "const_ptr_offset_from", since = "1.65.0")]
662 #[inline]
663 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
664 pub const unsafe fn offset_from(self, origin: *const T) -> isize
665 where
666 T: Sized,
667 {
668 let pointee_size = size_of::<T>();
669 assert!(0 < pointee_size && pointee_size <= isize::MAX as usize);
670 // SAFETY: the caller must uphold the safety contract for `ptr_offset_from`.
671 unsafe { intrinsics::ptr_offset_from(self, origin) }
672 }
673
674 /// Calculates the distance between two pointers within the same allocation. The returned value is in
675 /// units of **bytes**.
676 ///
677 /// This is purely a convenience for casting to a `u8` pointer and
678 /// using [`offset_from`][pointer::offset_from] on it. See that method for
679 /// documentation and safety requirements.
680 ///
681 /// For non-`Sized` pointees this operation considers only the data pointers,
682 /// ignoring the metadata.
683 #[inline(always)]
684 #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
685 #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
686 #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces
687 pub const unsafe fn byte_offset_from<U: ?Sized>(self, origin: *const U) -> isize {
688 // SAFETY: the caller must uphold the safety contract for `offset_from`.
689 unsafe { self.cast::<u8>().offset_from(origin.cast::<u8>()) }
690 }
691
692 /// Calculates the distance between two pointers within the same allocation, *where it's known that
693 /// `self` is equal to or greater than `origin`*. The returned value is in
694 /// units of T: the distance in bytes is divided by `size_of::<T>()`.
695 ///
696 /// This computes the same value that [`offset_from`](#method.offset_from)
697 /// would compute, but with the added precondition that the offset is
698 /// guaranteed to be non-negative. This method is equivalent to
699 /// `usize::try_from(self.offset_from(origin)).unwrap_unchecked()`,
700 /// but it provides slightly more information to the optimizer, which can
701 /// sometimes allow it to optimize slightly better with some backends.
702 ///
703 /// This method can be thought of as recovering the `count` that was passed
704 /// to [`add`](#method.add) (or, with the parameters in the other order,
705 /// to [`sub`](#method.sub)). The following are all equivalent, assuming
706 /// that their safety preconditions are met:
707 /// ```rust
708 /// # unsafe fn blah(ptr: *const i32, origin: *const i32, count: usize) -> bool { unsafe {
709 /// ptr.offset_from_unsigned(origin) == count
710 /// # &&
711 /// origin.add(count) == ptr
712 /// # &&
713 /// ptr.sub(count) == origin
714 /// # } }
715 /// ```
716 ///
717 /// # Safety
718 ///
719 /// - The distance between the pointers must be non-negative (`self >= origin`)
720 ///
721 /// - *All* the safety conditions of [`offset_from`](#method.offset_from)
722 /// apply to this method as well; see it for the full details.
723 ///
724 /// Importantly, despite the return type of this method being able to represent
725 /// a larger offset, it's still *not permitted* to pass pointers which differ
726 /// by more than `isize::MAX` *bytes*. As such, the result of this method will
727 /// always be less than or equal to `isize::MAX as usize`.
728 ///
729 /// # Panics
730 ///
731 /// This function panics if `T` is a Zero-Sized Type ("ZST").
732 ///
733 /// # Examples
734 ///
735 /// ```
736 /// let a = [0; 5];
737 /// let ptr1: *const i32 = &a[1];
738 /// let ptr2: *const i32 = &a[3];
739 /// unsafe {
740 /// assert_eq!(ptr2.offset_from_unsigned(ptr1), 2);
741 /// assert_eq!(ptr1.add(2), ptr2);
742 /// assert_eq!(ptr2.sub(2), ptr1);
743 /// assert_eq!(ptr2.offset_from_unsigned(ptr2), 0);
744 /// }
745 ///
746 /// // This would be incorrect, as the pointers are not correctly ordered:
747 /// // ptr1.offset_from_unsigned(ptr2)
748 /// ```
749 #[stable(feature = "ptr_sub_ptr", since = "1.87.0")]
750 #[rustc_const_stable(feature = "const_ptr_sub_ptr", since = "1.87.0")]
751 #[inline]
752 #[track_caller]
753 pub const unsafe fn offset_from_unsigned(self, origin: *const T) -> usize
754 where
755 T: Sized,
756 {
757 #[rustc_allow_const_fn_unstable(const_eval_select)]
758 const fn runtime_ptr_ge(this: *const (), origin: *const ()) -> bool {
759 const_eval_select!(
760 @capture { this: *const (), origin: *const () } -> bool:
761 if const {
762 true
763 } else {
764 this >= origin
765 }
766 )
767 }
768
769 ub_checks::assert_unsafe_precondition!(
770 check_language_ub,
771 "ptr::offset_from_unsigned requires `self >= origin`",
772 (
773 this: *const () = self as *const (),
774 origin: *const () = origin as *const (),
775 ) => runtime_ptr_ge(this, origin)
776 );
777
778 let pointee_size = size_of::<T>();
779 assert!(0 < pointee_size && pointee_size <= isize::MAX as usize);
780 // SAFETY: the caller must uphold the safety contract for `ptr_offset_from_unsigned`.
781 unsafe { intrinsics::ptr_offset_from_unsigned(self, origin) }
782 }
783
784 /// Calculates the distance between two pointers within the same allocation, *where it's known that
785 /// `self` is equal to or greater than `origin`*. The returned value is in
786 /// units of **bytes**.
787 ///
788 /// This is purely a convenience for casting to a `u8` pointer and
789 /// using [`offset_from_unsigned`][pointer::offset_from_unsigned] on it.
790 /// See that method for documentation and safety requirements.
791 ///
792 /// For non-`Sized` pointees this operation considers only the data pointers,
793 /// ignoring the metadata.
794 #[stable(feature = "ptr_sub_ptr", since = "1.87.0")]
795 #[rustc_const_stable(feature = "const_ptr_sub_ptr", since = "1.87.0")]
796 #[inline]
797 #[track_caller]
798 pub const unsafe fn byte_offset_from_unsigned<U: ?Sized>(self, origin: *const U) -> usize {
799 // SAFETY: the caller must uphold the safety contract for `offset_from_unsigned`.
800 unsafe { self.cast::<u8>().offset_from_unsigned(origin.cast::<u8>()) }
801 }
802
803 /// Returns whether two pointers are guaranteed to be equal.
804 ///
805 /// At runtime this function behaves like `Some(self == other)`.
806 /// However, in some contexts (e.g., compile-time evaluation),
807 /// it is not always possible to determine equality of two pointers, so this function may
808 /// spuriously return `None` for pointers that later actually turn out to have its equality known.
809 /// But when it returns `Some`, the pointers' equality is guaranteed to be known.
810 ///
811 /// The return value may change from `Some` to `None` and vice versa depending on the compiler
812 /// version and unsafe code must not
813 /// rely on the result of this function for soundness. It is suggested to only use this function
814 /// for performance optimizations where spurious `None` return values by this function do not
815 /// affect the outcome, but just the performance.
816 /// The consequences of using this method to make runtime and compile-time code behave
817 /// differently have not been explored. This method should not be used to introduce such
818 /// differences, and it should also not be stabilized before we have a better understanding
819 /// of this issue.
820 #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
821 #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
822 #[inline]
823 pub const fn guaranteed_eq(self, other: *const T) -> Option<bool>
824 where
825 T: Sized,
826 {
827 match intrinsics::ptr_guaranteed_cmp(self, other) {
828 2 => None,
829 other => Some(other == 1),
830 }
831 }
832
833 /// Returns whether two pointers are guaranteed to be inequal.
834 ///
835 /// At runtime this function behaves like `Some(self != other)`.
836 /// However, in some contexts (e.g., compile-time evaluation),
837 /// it is not always possible to determine inequality of two pointers, so this function may
838 /// spuriously return `None` for pointers that later actually turn out to have its inequality known.
839 /// But when it returns `Some`, the pointers' inequality is guaranteed to be known.
840 ///
841 /// The return value may change from `Some` to `None` and vice versa depending on the compiler
842 /// version and unsafe code must not
843 /// rely on the result of this function for soundness. It is suggested to only use this function
844 /// for performance optimizations where spurious `None` return values by this function do not
845 /// affect the outcome, but just the performance.
846 /// The consequences of using this method to make runtime and compile-time code behave
847 /// differently have not been explored. This method should not be used to introduce such
848 /// differences, and it should also not be stabilized before we have a better understanding
849 /// of this issue.
850 #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
851 #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")]
852 #[inline]
853 pub const fn guaranteed_ne(self, other: *const T) -> Option<bool>
854 where
855 T: Sized,
856 {
857 match self.guaranteed_eq(other) {
858 None => None,
859 Some(eq) => Some(!eq),
860 }
861 }
862
863 #[doc = include_str!("./docs/add.md")]
864 ///
865 /// # Examples
866 ///
867 /// ```
868 /// let s: &str = "123";
869 /// let ptr: *const u8 = s.as_ptr();
870 ///
871 /// unsafe {
872 /// assert_eq!(*ptr.add(1), b'2');
873 /// assert_eq!(*ptr.add(2), b'3');
874 /// }
875 /// ```
876 #[stable(feature = "pointer_methods", since = "1.26.0")]
877 #[must_use = "returns a new pointer rather than modifying its argument"]
878 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
879 #[inline(always)]
880 #[track_caller]
881 pub const unsafe fn add(self, count: usize) -> Self
882 where
883 T: Sized,
884 {
885 #[cfg(debug_assertions)]
886 #[inline]
887 #[rustc_allow_const_fn_unstable(const_eval_select)]
888 const fn runtime_add_nowrap(this: *const (), count: usize, size: usize) -> bool {
889 const_eval_select!(
890 @capture { this: *const (), count: usize, size: usize } -> bool:
891 if const {
892 true
893 } else {
894 let Some(byte_offset) = count.checked_mul(size) else {
895 return false;
896 };
897 let (_, overflow) = this.addr().overflowing_add(byte_offset);
898 byte_offset <= (isize::MAX as usize) && !overflow
899 }
900 )
901 }
902
903 #[cfg(debug_assertions)] // Expensive, and doesn't catch much in the wild.
904 ub_checks::assert_unsafe_precondition!(
905 check_language_ub,
906 "ptr::add requires that the address calculation does not overflow",
907 (
908 this: *const () = self as *const (),
909 count: usize = count,
910 size: usize = size_of::<T>(),
911 ) => runtime_add_nowrap(this, count, size)
912 );
913
914 // SAFETY: the caller must uphold the safety contract for `offset`.
915 unsafe { intrinsics::offset(self, count) }
916 }
917
918 /// Adds an unsigned offset in bytes to a pointer.
919 ///
920 /// `count` is in units of bytes.
921 ///
922 /// This is purely a convenience for casting to a `u8` pointer and
923 /// using [add][pointer::add] on it. See that method for documentation
924 /// and safety requirements.
925 ///
926 /// For non-`Sized` pointees this operation changes only the data pointer,
927 /// leaving the metadata untouched.
928 #[must_use]
929 #[inline(always)]
930 #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
931 #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
932 #[track_caller]
933 pub const unsafe fn byte_add(self, count: usize) -> Self {
934 // SAFETY: the caller must uphold the safety contract for `add`.
935 unsafe { self.cast::<u8>().add(count).with_metadata_of(self) }
936 }
937
938 /// Subtracts an unsigned offset from a pointer.
939 ///
940 /// This can only move the pointer backward (or not move it). If you need to move forward or
941 /// backward depending on the value, then you might want [`offset`](#method.offset) instead
942 /// which takes a signed offset.
943 ///
944 /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
945 /// offset of `3 * size_of::<T>()` bytes.
946 ///
947 /// # Safety
948 ///
949 /// If any of the following conditions are violated, the result is Undefined Behavior:
950 ///
951 /// * The offset in bytes, `count * size_of::<T>()`, computed on mathematical integers (without
952 /// "wrapping around"), must fit in an `isize`.
953 ///
954 /// * If the computed offset is non-zero, then `self` must be [derived from][crate::ptr#provenance] a pointer to some
955 /// [allocation], and the entire memory range between `self` and the result must be in
956 /// bounds of that allocation. In particular, this range must not "wrap around" the edge
957 /// of the address space.
958 ///
959 /// Allocations can never be larger than `isize::MAX` bytes, so if the computed offset
960 /// stays in bounds of the allocation, it is guaranteed to satisfy the first requirement.
961 /// This implies, for instance, that `vec.as_ptr().add(vec.len())` (for `vec: Vec<T>`) is always
962 /// safe.
963 ///
964 /// Consider using [`wrapping_sub`] instead if these constraints are
965 /// difficult to satisfy. The only advantage of this method is that it
966 /// enables more aggressive compiler optimizations.
967 ///
968 /// [`wrapping_sub`]: #method.wrapping_sub
969 /// [allocation]: crate::ptr#allocation
970 ///
971 /// # Examples
972 ///
973 /// ```
974 /// let s: &str = "123";
975 ///
976 /// unsafe {
977 /// let end: *const u8 = s.as_ptr().add(3);
978 /// assert_eq!(*end.sub(1), b'3');
979 /// assert_eq!(*end.sub(2), b'2');
980 /// }
981 /// ```
982 #[stable(feature = "pointer_methods", since = "1.26.0")]
983 #[must_use = "returns a new pointer rather than modifying its argument"]
984 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
985 #[inline(always)]
986 #[track_caller]
987 pub const unsafe fn sub(self, count: usize) -> Self
988 where
989 T: Sized,
990 {
991 #[cfg(debug_assertions)]
992 #[inline]
993 #[rustc_allow_const_fn_unstable(const_eval_select)]
994 const fn runtime_sub_nowrap(this: *const (), count: usize, size: usize) -> bool {
995 const_eval_select!(
996 @capture { this: *const (), count: usize, size: usize } -> bool:
997 if const {
998 true
999 } else {
1000 let Some(byte_offset) = count.checked_mul(size) else {
1001 return false;
1002 };
1003 byte_offset <= (isize::MAX as usize) && this.addr() >= byte_offset
1004 }
1005 )
1006 }
1007
1008 #[cfg(debug_assertions)] // Expensive, and doesn't catch much in the wild.
1009 ub_checks::assert_unsafe_precondition!(
1010 check_language_ub,
1011 "ptr::sub requires that the address calculation does not overflow",
1012 (
1013 this: *const () = self as *const (),
1014 count: usize = count,
1015 size: usize = size_of::<T>(),
1016 ) => runtime_sub_nowrap(this, count, size)
1017 );
1018
1019 if T::IS_ZST {
1020 // Pointer arithmetic does nothing when the pointee is a ZST.
1021 self
1022 } else {
1023 // SAFETY: the caller must uphold the safety contract for `offset`.
1024 // Because the pointee is *not* a ZST, that means that `count` is
1025 // at most `isize::MAX`, and thus the negation cannot overflow.
1026 unsafe { intrinsics::offset(self, intrinsics::unchecked_sub(0, count as isize)) }
1027 }
1028 }
1029
1030 /// Subtracts an unsigned offset in bytes from a pointer.
1031 ///
1032 /// `count` is in units of bytes.
1033 ///
1034 /// This is purely a convenience for casting to a `u8` pointer and
1035 /// using [sub][pointer::sub] on it. See that method for documentation
1036 /// and safety requirements.
1037 ///
1038 /// For non-`Sized` pointees this operation changes only the data pointer,
1039 /// leaving the metadata untouched.
1040 #[must_use]
1041 #[inline(always)]
1042 #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
1043 #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
1044 #[track_caller]
1045 pub const unsafe fn byte_sub(self, count: usize) -> Self {
1046 // SAFETY: the caller must uphold the safety contract for `sub`.
1047 unsafe { self.cast::<u8>().sub(count).with_metadata_of(self) }
1048 }
1049
1050 /// Adds an unsigned offset to a pointer using wrapping arithmetic.
1051 ///
1052 /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
1053 /// offset of `3 * size_of::<T>()` bytes.
1054 ///
1055 /// # Safety
1056 ///
1057 /// This operation itself is always safe, but using the resulting pointer is not.
1058 ///
1059 /// The resulting pointer "remembers" the [allocation] that `self` points to; it must not
1060 /// be used to read or write other allocations.
1061 ///
1062 /// In other words, `let z = x.wrapping_add((y as usize) - (x as usize))` does *not* make `z`
1063 /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
1064 /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless
1065 /// `x` and `y` point into the same allocation.
1066 ///
1067 /// Compared to [`add`], this method basically delays the requirement of staying within the
1068 /// same allocation: [`add`] is immediate Undefined Behavior when crossing object
1069 /// boundaries; `wrapping_add` produces a pointer but still leads to Undefined Behavior if a
1070 /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`add`]
1071 /// can be optimized better and is thus preferable in performance-sensitive code.
1072 ///
1073 /// The delayed check only considers the value of the pointer that was dereferenced, not the
1074 /// intermediate values used during the computation of the final result. For example,
1075 /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the
1076 /// allocation and then re-entering it later is permitted.
1077 ///
1078 /// [`add`]: #method.add
1079 /// [allocation]: crate::ptr#allocation
1080 ///
1081 /// # Examples
1082 ///
1083 /// ```
1084 /// # use std::fmt::Write;
1085 /// // Iterate using a raw pointer in increments of two elements
1086 /// let data = [1u8, 2, 3, 4, 5];
1087 /// let mut ptr: *const u8 = data.as_ptr();
1088 /// let step = 2;
1089 /// let end_rounded_up = ptr.wrapping_add(6);
1090 ///
1091 /// let mut out = String::new();
1092 /// while ptr != end_rounded_up {
1093 /// unsafe {
1094 /// write!(&mut out, "{}, ", *ptr)?;
1095 /// }
1096 /// ptr = ptr.wrapping_add(step);
1097 /// }
1098 /// assert_eq!(out, "1, 3, 5, ");
1099 /// # std::fmt::Result::Ok(())
1100 /// ```
1101 #[stable(feature = "pointer_methods", since = "1.26.0")]
1102 #[must_use = "returns a new pointer rather than modifying its argument"]
1103 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
1104 #[inline(always)]
1105 pub const fn wrapping_add(self, count: usize) -> Self
1106 where
1107 T: Sized,
1108 {
1109 self.wrapping_offset(count as isize)
1110 }
1111
1112 /// Adds an unsigned offset in bytes to a pointer using wrapping arithmetic.
1113 ///
1114 /// `count` is in units of bytes.
1115 ///
1116 /// This is purely a convenience for casting to a `u8` pointer and
1117 /// using [wrapping_add][pointer::wrapping_add] on it. See that method for documentation.
1118 ///
1119 /// For non-`Sized` pointees this operation changes only the data pointer,
1120 /// leaving the metadata untouched.
1121 #[must_use]
1122 #[inline(always)]
1123 #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
1124 #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
1125 pub const fn wrapping_byte_add(self, count: usize) -> Self {
1126 self.cast::<u8>().wrapping_add(count).with_metadata_of(self)
1127 }
1128
1129 /// Subtracts an unsigned offset from a pointer using wrapping arithmetic.
1130 ///
1131 /// `count` is in units of T; e.g., a `count` of 3 represents a pointer
1132 /// offset of `3 * size_of::<T>()` bytes.
1133 ///
1134 /// # Safety
1135 ///
1136 /// This operation itself is always safe, but using the resulting pointer is not.
1137 ///
1138 /// The resulting pointer "remembers" the [allocation] that `self` points to; it must not
1139 /// be used to read or write other allocations.
1140 ///
1141 /// In other words, `let z = x.wrapping_sub((x as usize) - (y as usize))` does *not* make `z`
1142 /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still
1143 /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless
1144 /// `x` and `y` point into the same allocation.
1145 ///
1146 /// Compared to [`sub`], this method basically delays the requirement of staying within the
1147 /// same allocation: [`sub`] is immediate Undefined Behavior when crossing object
1148 /// boundaries; `wrapping_sub` produces a pointer but still leads to Undefined Behavior if a
1149 /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`sub`]
1150 /// can be optimized better and is thus preferable in performance-sensitive code.
1151 ///
1152 /// The delayed check only considers the value of the pointer that was dereferenced, not the
1153 /// intermediate values used during the computation of the final result. For example,
1154 /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the
1155 /// allocation and then re-entering it later is permitted.
1156 ///
1157 /// [`sub`]: #method.sub
1158 /// [allocation]: crate::ptr#allocation
1159 ///
1160 /// # Examples
1161 ///
1162 /// ```
1163 /// # use std::fmt::Write;
1164 /// // Iterate using a raw pointer in increments of two elements (backwards)
1165 /// let data = [1u8, 2, 3, 4, 5];
1166 /// let mut ptr: *const u8 = data.as_ptr();
1167 /// let start_rounded_down = ptr.wrapping_sub(2);
1168 /// ptr = ptr.wrapping_add(4);
1169 /// let step = 2;
1170 /// let mut out = String::new();
1171 /// while ptr != start_rounded_down {
1172 /// unsafe {
1173 /// write!(&mut out, "{}, ", *ptr)?;
1174 /// }
1175 /// ptr = ptr.wrapping_sub(step);
1176 /// }
1177 /// assert_eq!(out, "5, 3, 1, ");
1178 /// # std::fmt::Result::Ok(())
1179 /// ```
1180 #[stable(feature = "pointer_methods", since = "1.26.0")]
1181 #[must_use = "returns a new pointer rather than modifying its argument"]
1182 #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")]
1183 #[inline(always)]
1184 pub const fn wrapping_sub(self, count: usize) -> Self
1185 where
1186 T: Sized,
1187 {
1188 self.wrapping_offset((count as isize).wrapping_neg())
1189 }
1190
1191 /// Subtracts an unsigned offset in bytes from a pointer using wrapping arithmetic.
1192 ///
1193 /// `count` is in units of bytes.
1194 ///
1195 /// This is purely a convenience for casting to a `u8` pointer and
1196 /// using [wrapping_sub][pointer::wrapping_sub] on it. See that method for documentation.
1197 ///
1198 /// For non-`Sized` pointees this operation changes only the data pointer,
1199 /// leaving the metadata untouched.
1200 #[must_use]
1201 #[inline(always)]
1202 #[stable(feature = "pointer_byte_offsets", since = "1.75.0")]
1203 #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")]
1204 pub const fn wrapping_byte_sub(self, count: usize) -> Self {
1205 self.cast::<u8>().wrapping_sub(count).with_metadata_of(self)
1206 }
1207
1208 /// Reads the value from `self` without moving it. This leaves the
1209 /// memory in `self` unchanged.
1210 ///
1211 /// See [`ptr::read`] for safety concerns and examples.
1212 ///
1213 /// [`ptr::read`]: crate::ptr::read()
1214 #[stable(feature = "pointer_methods", since = "1.26.0")]
1215 #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]
1216 #[inline]
1217 #[track_caller]
1218 pub const unsafe fn read(self) -> T
1219 where
1220 T: Sized,
1221 {
1222 // SAFETY: the caller must uphold the safety contract for `read`.
1223 unsafe { read(self) }
1224 }
1225
1226 /// Performs a volatile read of the value from `self` without moving it. This
1227 /// leaves the memory in `self` unchanged.
1228 ///
1229 /// Volatile operations are intended to act on I/O memory, and are guaranteed
1230 /// to not be elided or reordered by the compiler across other volatile
1231 /// operations.
1232 ///
1233 /// See [`ptr::read_volatile`] for safety concerns and examples.
1234 ///
1235 /// [`ptr::read_volatile`]: crate::ptr::read_volatile()
1236 #[stable(feature = "pointer_methods", since = "1.26.0")]
1237 #[inline]
1238 #[track_caller]
1239 pub unsafe fn read_volatile(self) -> T
1240 where
1241 T: Sized,
1242 {
1243 // SAFETY: the caller must uphold the safety contract for `read_volatile`.
1244 unsafe { read_volatile(self) }
1245 }
1246
1247 /// Reads the value from `self` without moving it. This leaves the
1248 /// memory in `self` unchanged.
1249 ///
1250 /// Unlike `read`, the pointer may be unaligned.
1251 ///
1252 /// See [`ptr::read_unaligned`] for safety concerns and examples.
1253 ///
1254 /// [`ptr::read_unaligned`]: crate::ptr::read_unaligned()
1255 #[stable(feature = "pointer_methods", since = "1.26.0")]
1256 #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")]
1257 #[inline]
1258 #[track_caller]
1259 pub const unsafe fn read_unaligned(self) -> T
1260 where
1261 T: Sized,
1262 {
1263 // SAFETY: the caller must uphold the safety contract for `read_unaligned`.
1264 unsafe { read_unaligned(self) }
1265 }
1266
1267 /// Copies `count * size_of::<T>()` bytes from `self` to `dest`. The source
1268 /// and destination may overlap.
1269 ///
1270 /// NOTE: this has the *same* argument order as [`ptr::copy`].
1271 ///
1272 /// See [`ptr::copy`] for safety concerns and examples.
1273 ///
1274 /// [`ptr::copy`]: crate::ptr::copy()
1275 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1276 #[stable(feature = "pointer_methods", since = "1.26.0")]
1277 #[inline]
1278 #[track_caller]
1279 pub const unsafe fn copy_to(self, dest: *mut T, count: usize)
1280 where
1281 T: Sized,
1282 {
1283 // SAFETY: the caller must uphold the safety contract for `copy`.
1284 unsafe { copy(self, dest, count) }
1285 }
1286
1287 /// Copies `count * size_of::<T>()` bytes from `self` to `dest`. The source
1288 /// and destination may *not* overlap.
1289 ///
1290 /// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`].
1291 ///
1292 /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples.
1293 ///
1294 /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping()
1295 #[rustc_const_stable(feature = "const_intrinsic_copy", since = "1.83.0")]
1296 #[stable(feature = "pointer_methods", since = "1.26.0")]
1297 #[inline]
1298 #[track_caller]
1299 pub const unsafe fn copy_to_nonoverlapping(self, dest: *mut T, count: usize)
1300 where
1301 T: Sized,
1302 {
1303 // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`.
1304 unsafe { copy_nonoverlapping(self, dest, count) }
1305 }
1306
1307 /// Computes the offset that needs to be applied to the pointer in order to make it aligned to
1308 /// `align`.
1309 ///
1310 /// If it is not possible to align the pointer, the implementation returns
1311 /// `usize::MAX`.
1312 ///
1313 /// The offset is expressed in number of `T` elements, and not bytes. The value returned can be
1314 /// used with the `wrapping_add` method.
1315 ///
1316 /// There are no guarantees whatsoever that offsetting the pointer will not overflow or go
1317 /// beyond the allocation that the pointer points into. It is up to the caller to ensure that
1318 /// the returned offset is correct in all terms other than alignment.
1319 ///
1320 /// # Panics
1321 ///
1322 /// The function panics if `align` is not a power-of-two.
1323 ///
1324 /// # Examples
1325 ///
1326 /// Accessing adjacent `u8` as `u16`
1327 ///
1328 /// ```
1329 /// # unsafe {
1330 /// let x = [5_u8, 6, 7, 8, 9];
1331 /// let ptr = x.as_ptr();
1332 /// let offset = ptr.align_offset(align_of::<u16>());
1333 ///
1334 /// if offset < x.len() - 1 {
1335 /// let u16_ptr = ptr.add(offset).cast::<u16>();
1336 /// assert!(*u16_ptr == u16::from_ne_bytes([5, 6]) || *u16_ptr == u16::from_ne_bytes([6, 7]));
1337 /// } else {
1338 /// // while the pointer can be aligned via `offset`, it would point
1339 /// // outside the allocation
1340 /// }
1341 /// # }
1342 /// ```
1343 #[must_use]
1344 #[inline]
1345 #[stable(feature = "align_offset", since = "1.36.0")]
1346 pub fn align_offset(self, align: usize) -> usize
1347 where
1348 T: Sized,
1349 {
1350 if !align.is_power_of_two() {
1351 panic!("align_offset: align is not a power-of-two");
1352 }
1353
1354 // SAFETY: `align` has been checked to be a power of 2 above
1355 let ret = unsafe { align_offset(self, align) };
1356
1357 // Inform Miri that we want to consider the resulting pointer to be suitably aligned.
1358 #[cfg(miri)]
1359 if ret != usize::MAX {
1360 intrinsics::miri_promise_symbolic_alignment(self.wrapping_add(ret).cast(), align);
1361 }
1362
1363 ret
1364 }
1365
1366 /// Returns whether the pointer is properly aligned for `T`.
1367 ///
1368 /// # Examples
1369 ///
1370 /// ```
1371 /// // On some platforms, the alignment of i32 is less than 4.
1372 /// #[repr(align(4))]
1373 /// struct AlignedI32(i32);
1374 ///
1375 /// let data = AlignedI32(42);
1376 /// let ptr = &data as *const AlignedI32;
1377 ///
1378 /// assert!(ptr.is_aligned());
1379 /// assert!(!ptr.wrapping_byte_add(1).is_aligned());
1380 /// ```
1381 #[must_use]
1382 #[inline]
1383 #[stable(feature = "pointer_is_aligned", since = "1.79.0")]
1384 pub fn is_aligned(self) -> bool
1385 where
1386 T: Sized,
1387 {
1388 self.is_aligned_to(align_of::<T>())
1389 }
1390
1391 /// Returns whether the pointer is aligned to `align`.
1392 ///
1393 /// For non-`Sized` pointees this operation considers only the data pointer,
1394 /// ignoring the metadata.
1395 ///
1396 /// # Panics
1397 ///
1398 /// The function panics if `align` is not a power-of-two (this includes 0).
1399 ///
1400 /// # Examples
1401 ///
1402 /// ```
1403 /// #![feature(pointer_is_aligned_to)]
1404 ///
1405 /// // On some platforms, the alignment of i32 is less than 4.
1406 /// #[repr(align(4))]
1407 /// struct AlignedI32(i32);
1408 ///
1409 /// let data = AlignedI32(42);
1410 /// let ptr = &data as *const AlignedI32;
1411 ///
1412 /// assert!(ptr.is_aligned_to(1));
1413 /// assert!(ptr.is_aligned_to(2));
1414 /// assert!(ptr.is_aligned_to(4));
1415 ///
1416 /// assert!(ptr.wrapping_byte_add(2).is_aligned_to(2));
1417 /// assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4));
1418 ///
1419 /// assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8));
1420 /// ```
1421 #[must_use]
1422 #[inline]
1423 #[unstable(feature = "pointer_is_aligned_to", issue = "96284")]
1424 pub fn is_aligned_to(self, align: usize) -> bool {
1425 if !align.is_power_of_two() {
1426 panic!("is_aligned_to: align is not a power-of-two");
1427 }
1428
1429 self.addr() & (align - 1) == 0
1430 }
1431}
1432
1433impl<T> *const [T] {
1434 /// Returns the length of a raw slice.
1435 ///
1436 /// The returned value is the number of **elements**, not the number of bytes.
1437 ///
1438 /// This function is safe, even when the raw slice cannot be cast to a slice
1439 /// reference because the pointer is null or unaligned.
1440 ///
1441 /// # Examples
1442 ///
1443 /// ```rust
1444 /// use std::ptr;
1445 ///
1446 /// let slice: *const [i8] = ptr::slice_from_raw_parts(ptr::null(), 3);
1447 /// assert_eq!(slice.len(), 3);
1448 /// ```
1449 #[inline]
1450 #[stable(feature = "slice_ptr_len", since = "1.79.0")]
1451 #[rustc_const_stable(feature = "const_slice_ptr_len", since = "1.79.0")]
1452 pub const fn len(self) -> usize {
1453 metadata(self)
1454 }
1455
1456 /// Returns `true` if the raw slice has a length of 0.
1457 ///
1458 /// # Examples
1459 ///
1460 /// ```
1461 /// use std::ptr;
1462 ///
1463 /// let slice: *const [i8] = ptr::slice_from_raw_parts(ptr::null(), 3);
1464 /// assert!(!slice.is_empty());
1465 /// ```
1466 #[inline(always)]
1467 #[stable(feature = "slice_ptr_len", since = "1.79.0")]
1468 #[rustc_const_stable(feature = "const_slice_ptr_len", since = "1.79.0")]
1469 pub const fn is_empty(self) -> bool {
1470 self.len() == 0
1471 }
1472
1473 /// Returns a raw pointer to the slice's buffer.
1474 ///
1475 /// This is equivalent to casting `self` to `*const T`, but more type-safe.
1476 ///
1477 /// # Examples
1478 ///
1479 /// ```rust
1480 /// #![feature(slice_ptr_get)]
1481 /// use std::ptr;
1482 ///
1483 /// let slice: *const [i8] = ptr::slice_from_raw_parts(ptr::null(), 3);
1484 /// assert_eq!(slice.as_ptr(), ptr::null());
1485 /// ```
1486 #[inline]
1487 #[unstable(feature = "slice_ptr_get", issue = "74265")]
1488 pub const fn as_ptr(self) -> *const T {
1489 self as *const T
1490 }
1491
1492 /// Gets a raw pointer to the underlying array.
1493 ///
1494 /// If `N` is not exactly equal to the length of `self`, then this method returns `None`.
1495 #[unstable(feature = "slice_as_array", issue = "133508")]
1496 #[inline]
1497 #[must_use]
1498 pub const fn as_array<const N: usize>(self) -> Option<*const [T; N]> {
1499 if self.len() == N {
1500 let me = self.as_ptr() as *const [T; N];
1501 Some(me)
1502 } else {
1503 None
1504 }
1505 }
1506
1507 /// Returns a raw pointer to an element or subslice, without doing bounds
1508 /// checking.
1509 ///
1510 /// Calling this method with an out-of-bounds index or when `self` is not dereferenceable
1511 /// is *[undefined behavior]* even if the resulting pointer is not used.
1512 ///
1513 /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
1514 ///
1515 /// # Examples
1516 ///
1517 /// ```
1518 /// #![feature(slice_ptr_get)]
1519 ///
1520 /// let x = &[1, 2, 4] as *const [i32];
1521 ///
1522 /// unsafe {
1523 /// assert_eq!(x.get_unchecked(1), x.as_ptr().add(1));
1524 /// }
1525 /// ```
1526 #[unstable(feature = "slice_ptr_get", issue = "74265")]
1527 #[inline]
1528 pub unsafe fn get_unchecked<I>(self, index: I) -> *const I::Output
1529 where
1530 I: SliceIndex<[T]>,
1531 {
1532 // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds.
1533 unsafe { index.get_unchecked(self) }
1534 }
1535
1536 #[doc = include_str!("docs/as_uninit_slice.md")]
1537 #[inline]
1538 #[unstable(feature = "ptr_as_uninit", issue = "75402")]
1539 pub const unsafe fn as_uninit_slice<'a>(self) -> Option<&'a [MaybeUninit<T>]> {
1540 if self.is_null() {
1541 None
1542 } else {
1543 // SAFETY: the caller must uphold the safety contract for `as_uninit_slice`.
1544 Some(unsafe { slice::from_raw_parts(self as *const MaybeUninit<T>, self.len()) })
1545 }
1546 }
1547}
1548
1549impl<T, const N: usize> *const [T; N] {
1550 /// Returns a raw pointer to the array's buffer.
1551 ///
1552 /// This is equivalent to casting `self` to `*const T`, but more type-safe.
1553 ///
1554 /// # Examples
1555 ///
1556 /// ```rust
1557 /// #![feature(array_ptr_get)]
1558 /// use std::ptr;
1559 ///
1560 /// let arr: *const [i8; 3] = ptr::null();
1561 /// assert_eq!(arr.as_ptr(), ptr::null());
1562 /// ```
1563 #[inline]
1564 #[unstable(feature = "array_ptr_get", issue = "119834")]
1565 pub const fn as_ptr(self) -> *const T {
1566 self as *const T
1567 }
1568
1569 /// Returns a raw pointer to a slice containing the entire array.
1570 ///
1571 /// # Examples
1572 ///
1573 /// ```
1574 /// #![feature(array_ptr_get)]
1575 ///
1576 /// let arr: *const [i32; 3] = &[1, 2, 4] as *const [i32; 3];
1577 /// let slice: *const [i32] = arr.as_slice();
1578 /// assert_eq!(slice.len(), 3);
1579 /// ```
1580 #[inline]
1581 #[unstable(feature = "array_ptr_get", issue = "119834")]
1582 pub const fn as_slice(self) -> *const [T] {
1583 self
1584 }
1585}
1586
1587/// Pointer equality is by address, as produced by the [`<*const T>::addr`](pointer::addr) method.
1588#[stable(feature = "rust1", since = "1.0.0")]
1589impl<T: PointeeSized> PartialEq for *const T {
1590 #[inline]
1591 #[allow(ambiguous_wide_pointer_comparisons)]
1592 fn eq(&self, other: &*const T) -> bool {
1593 *self == *other
1594 }
1595}
1596
1597/// Pointer equality is an equivalence relation.
1598#[stable(feature = "rust1", since = "1.0.0")]
1599impl<T: PointeeSized> Eq for *const T {}
1600
1601/// Pointer comparison is by address, as produced by the `[`<*const T>::addr`](pointer::addr)` method.
1602#[stable(feature = "rust1", since = "1.0.0")]
1603impl<T: PointeeSized> Ord for *const T {
1604 #[inline]
1605 #[allow(ambiguous_wide_pointer_comparisons)]
1606 fn cmp(&self, other: &*const T) -> Ordering {
1607 if self < other {
1608 Less
1609 } else if self == other {
1610 Equal
1611 } else {
1612 Greater
1613 }
1614 }
1615}
1616
1617/// Pointer comparison is by address, as produced by the `[`<*const T>::addr`](pointer::addr)` method.
1618#[stable(feature = "rust1", since = "1.0.0")]
1619impl<T: PointeeSized> PartialOrd for *const T {
1620 #[inline]
1621 #[allow(ambiguous_wide_pointer_comparisons)]
1622 fn partial_cmp(&self, other: &*const T) -> Option<Ordering> {
1623 Some(self.cmp(other))
1624 }
1625
1626 #[inline]
1627 #[allow(ambiguous_wide_pointer_comparisons)]
1628 fn lt(&self, other: &*const T) -> bool {
1629 *self < *other
1630 }
1631
1632 #[inline]
1633 #[allow(ambiguous_wide_pointer_comparisons)]
1634 fn le(&self, other: &*const T) -> bool {
1635 *self <= *other
1636 }
1637
1638 #[inline]
1639 #[allow(ambiguous_wide_pointer_comparisons)]
1640 fn gt(&self, other: &*const T) -> bool {
1641 *self > *other
1642 }
1643
1644 #[inline]
1645 #[allow(ambiguous_wide_pointer_comparisons)]
1646 fn ge(&self, other: &*const T) -> bool {
1647 *self >= *other
1648 }
1649}
1650
1651#[stable(feature = "raw_ptr_default", since = "1.88.0")]
1652impl<T: ?Sized + Thin> Default for *const T {
1653 /// Returns the default value of [`null()`][crate::ptr::null].
1654 fn default() -> Self {
1655 crate::ptr::null()
1656 }
1657}