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