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