const_ptr.rs source code [crates/core/src/ptr/const_ptr.rs]

1	use super::*;
2	use crate::cmp::Ordering::{Equal, Greater, Less};
3	use crate::intrinsics::const_eval_select;
4	use crate::mem::{self, SizedTypeProperties};
5	use crate::slice::{self, SliceIndex};
6
7	impl<T: ?Sized> *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: ?Sized,
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
1433	impl<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
1549	impl<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")]
1589	impl<T: ?Sized> 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")]
1599	impl<T: ?Sized> 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")]
1603	impl<T: ?Sized> 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")]
1619	impl<T: ?Sized> 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")]
1652	impl<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	}
1658