src/libcore/ptr.rs

   1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 // FIXME: talk about offset, copy_memory, copy_nonoverlapping_memory
  12
  13 //! Raw, unsafe pointers, `*const T`, and `*mut T`.
  14 //!
  15 //! *[See also the pointer primitive types](../../std/primitive.pointer.html).*
  16
  17 #![stable(feature = "rust1", since = "1.0.0")]
  18
  19 use convert::From;
  20 use intrinsics;
  21 use ops::CoerceUnsized;
  22 use fmt;
  23 use hash;
  24 use marker::{PhantomData, Unsize};
  25 use mem;
  26 use nonzero::NonZero;
  27
  28 use cmp::Ordering::{self, Less, Equal, Greater};
  29
  30 #[stable(feature = "rust1", since = "1.0.0")]
  31 pub use intrinsics::copy_nonoverlapping;
  32
  33 #[stable(feature = "rust1", since = "1.0.0")]
  34 pub use intrinsics::copy;
  35
  36 #[stable(feature = "rust1", since = "1.0.0")]
  37 pub use intrinsics::write_bytes;
  38
  39 /// Executes the destructor (if any) of the pointed-to value.
  40 ///
  41 /// This has two use cases:
  42 ///
  43 /// * It is *required* to use `drop_in_place` to drop unsized types like
  44 ///   trait objects, because they can't be read out onto the stack and
  45 ///   dropped normally.
  46 ///
  47 /// * It is friendlier to the optimizer to do this over `ptr::read` when
  48 ///   dropping manually allocated memory (e.g. when writing Box/Rc/Vec),
  49 ///   as the compiler doesn't need to prove that it's sound to elide the
  50 ///   copy.
  51 ///
  52 /// # Safety
  53 ///
  54 /// This has all the same safety problems as `ptr::read` with respect to
  55 /// invalid pointers, types, and double drops.
  56 #[stable(feature = "drop_in_place", since = "1.8.0")]
  57 #[lang = "drop_in_place"]
  58 #[allow(unconditional_recursion)]
  59 pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T) {
  60     // Code here does not matter - this is replaced by the
  61     // real drop glue by the compiler.
  62     drop_in_place(to_drop);
  63 }
  64
  65 /// Creates a null raw pointer.
  66 ///
  67 /// # Examples
  68 ///
  69 /// ```
  70 /// use std::ptr;
  71 ///
  72 /// let p: *const i32 = ptr::null();
  73 /// assert!(p.is_null());
  74 /// ```
  75 #[inline]
  76 #[stable(feature = "rust1", since = "1.0.0")]
  77 pub const fn null<T>() -> *const T { 0 as *const T }
  78
  79 /// Creates a null mutable raw pointer.
  80 ///
  81 /// # Examples
  82 ///
  83 /// ```
  84 /// use std::ptr;
  85 ///
  86 /// let p: *mut i32 = ptr::null_mut();
  87 /// assert!(p.is_null());
  88 /// ```
  89 #[inline]
  90 #[stable(feature = "rust1", since = "1.0.0")]
  91 pub const fn null_mut<T>() -> *mut T { 0 as *mut T }
  92
  93 /// Swaps the values at two mutable locations of the same type, without
  94 /// deinitializing either.
  95 ///
  96 /// The values pointed at by `x` and `y` may overlap, unlike `mem::swap` which
  97 /// is otherwise equivalent. If the values do overlap, then the overlapping
  98 /// region of memory from `x` will be used. This is demonstrated in the
  99 /// examples section below.
 100 ///
 101 /// # Safety
 102 ///
 103 /// This function copies the memory through the raw pointers passed to it
 104 /// as arguments.
 105 ///
 106 /// Ensure that these pointers are valid before calling `swap`.
 107 ///
 108 /// # Examples
 109 ///
 110 /// Swapping two non-overlapping regions:
 111 ///
 112 /// ```
 113 /// use std::ptr;
 114 ///
 115 /// let mut array = [0, 1, 2, 3];
 116 ///
 117 /// let x = array[0..].as_mut_ptr() as *mut [u32; 2];
 118 /// let y = array[2..].as_mut_ptr() as *mut [u32; 2];
 119 ///
 120 /// unsafe {
 121 ///     ptr::swap(x, y);
 122 ///     assert_eq!([2, 3, 0, 1], array);
 123 /// }
 124 /// ```
 125 ///
 126 /// Swapping two overlapping regions:
 127 ///
 128 /// ```
 129 /// use std::ptr;
 130 ///
 131 /// let mut array = [0, 1, 2, 3];
 132 ///
 133 /// let x = array[0..].as_mut_ptr() as *mut [u32; 3];
 134 /// let y = array[1..].as_mut_ptr() as *mut [u32; 3];
 135 ///
 136 /// unsafe {
 137 ///     ptr::swap(x, y);
 138 ///     assert_eq!([1, 0, 1, 2], array);
 139 /// }
 140 /// ```
 141 #[inline]
 142 #[stable(feature = "rust1", since = "1.0.0")]
 143 pub unsafe fn swap<T>(x: *mut T, y: *mut T) {
 144     // Give ourselves some scratch space to work with
 145     let mut tmp: T = mem::uninitialized();
 146
 147     // Perform the swap
 148     copy_nonoverlapping(x, &mut tmp, 1);
 149     copy(y, x, 1); // `x` and `y` may overlap
 150     copy_nonoverlapping(&tmp, y, 1);
 151
 152     // y and t now point to the same thing, but we need to completely forget `tmp`
 153     // because it's no longer relevant.
 154     mem::forget(tmp);
 155 }
 156
 157 /// Swaps a sequence of values at two mutable locations of the same type.
 158 ///
 159 /// # Safety
 160 ///
 161 /// The two arguments must each point to the beginning of `count` locations
 162 /// of valid memory, and the two memory ranges must not overlap.
 163 ///
 164 /// # Examples
 165 ///
 166 /// Basic usage:
 167 ///
 168 /// ```
 169 /// use std::ptr;
 170 ///
 171 /// let mut x = [1, 2, 3, 4];
 172 /// let mut y = [7, 8, 9];
 173 ///
 174 /// unsafe {
 175 ///     ptr::swap_nonoverlapping(x.as_mut_ptr(), y.as_mut_ptr(), 2);
 176 /// }
 177 ///
 178 /// assert_eq!(x, [7, 8, 3, 4]);
 179 /// assert_eq!(y, [1, 2, 9]);
 180 /// ```
 181 #[inline]
 182 #[stable(feature = "swap_nonoverlapping", since = "1.27.0")]
 183 pub unsafe fn swap_nonoverlapping<T>(x: *mut T, y: *mut T, count: usize) {
 184     let x = x as *mut u8;
 185     let y = y as *mut u8;
 186     let len = mem::size_of::<T>() * count;
 187     swap_nonoverlapping_bytes(x, y, len)
 188 }
 189
 190 #[inline]
 191 unsafe fn swap_nonoverlapping_bytes(x: *mut u8, y: *mut u8, len: usize) {
 192     // The approach here is to utilize simd to swap x & y efficiently. Testing reveals
 193     // that swapping either 32 bytes or 64 bytes at a time is most efficient for intel
 194     // Haswell E processors. LLVM is more able to optimize if we give a struct a
 195     // #[repr(simd)], even if we don't actually use this struct directly.
 196     //
 197     // FIXME repr(simd) broken on emscripten and redox
 198     // It's also broken on big-endian powerpc64 and s390x.  #42778
 199     #[cfg_attr(not(any(target_os = "emscripten", target_os = "redox",
 200                        target_endian = "big")),
 201                repr(simd))]
 202     struct Block(u64, u64, u64, u64);
 203     struct UnalignedBlock(u64, u64, u64, u64);
 204
 205     let block_size = mem::size_of::<Block>();
 206
 207     // Loop through x & y, copying them `Block` at a time
 208     // The optimizer should unroll the loop fully for most types
 209     // N.B. We can't use a for loop as the `range` impl calls `mem::swap` recursively
 210     let mut i = 0;
 211     while i + block_size <= len {
 212         // Create some uninitialized memory as scratch space
 213         // Declaring `t` here avoids aligning the stack when this loop is unused
 214         let mut t: Block = mem::uninitialized();
 215         let t = &mut t as *mut _ as *mut u8;
 216         let x = x.offset(i as isize);
 217         let y = y.offset(i as isize);
 218
 219         // Swap a block of bytes of x & y, using t as a temporary buffer
 220         // This should be optimized into efficient SIMD operations where available
 221         copy_nonoverlapping(x, t, block_size);
 222         copy_nonoverlapping(y, x, block_size);
 223         copy_nonoverlapping(t, y, block_size);
 224         i += block_size;
 225     }
 226
 227     if i < len {
 228         // Swap any remaining bytes
 229         let mut t: UnalignedBlock = mem::uninitialized();
 230         let rem = len - i;
 231
 232         let t = &mut t as *mut _ as *mut u8;
 233         let x = x.offset(i as isize);
 234         let y = y.offset(i as isize);
 235
 236         copy_nonoverlapping(x, t, rem);
 237         copy_nonoverlapping(y, x, rem);
 238         copy_nonoverlapping(t, y, rem);
 239     }
 240 }
 241
 242 /// Replaces the value at `dest` with `src`, returning the old
 243 /// value, without dropping either.
 244 ///
 245 /// # Safety
 246 ///
 247 /// This is only unsafe because it accepts a raw pointer.
 248 /// Otherwise, this operation is identical to `mem::replace`.
 249 #[inline]
 250 #[stable(feature = "rust1", since = "1.0.0")]
 251 pub unsafe fn replace<T>(dest: *mut T, mut src: T) -> T {
 252     mem::swap(&mut *dest, &mut src); // cannot overlap
 253     src
 254 }
 255
 256 /// Reads the value from `src` without moving it. This leaves the
 257 /// memory in `src` unchanged.
 258 ///
 259 /// # Safety
 260 ///
 261 /// Beyond accepting a raw pointer, this is unsafe because it semantically
 262 /// moves the value out of `src` without preventing further usage of `src`.
 263 /// If `T` is not `Copy`, then care must be taken to ensure that the value at
 264 /// `src` is not used before the data is overwritten again (e.g. with `write`,
 265 /// `write_bytes`, or `copy`). Note that `*src = foo` counts as a use
 266 /// because it will attempt to drop the value previously at `*src`.
 267 ///
 268 /// The pointer must be aligned; use `read_unaligned` if that is not the case.
 269 ///
 270 /// # Examples
 271 ///
 272 /// Basic usage:
 273 ///
 274 /// ```
 275 /// let x = 12;
 276 /// let y = &x as *const i32;
 277 ///
 278 /// unsafe {
 279 ///     assert_eq!(std::ptr::read(y), 12);
 280 /// }
 281 /// ```
 282 #[inline]
 283 #[stable(feature = "rust1", since = "1.0.0")]
 284 pub unsafe fn read<T>(src: *const T) -> T {
 285     let mut tmp: T = mem::uninitialized();
 286     copy_nonoverlapping(src, &mut tmp, 1);
 287     tmp
 288 }
 289
 290 /// Reads the value from `src` without moving it. This leaves the
 291 /// memory in `src` unchanged.
 292 ///
 293 /// Unlike `read`, the pointer may be unaligned.
 294 ///
 295 /// # Safety
 296 ///
 297 /// Beyond accepting a raw pointer, this is unsafe because it semantically
 298 /// moves the value out of `src` without preventing further usage of `src`.
 299 /// If `T` is not `Copy`, then care must be taken to ensure that the value at
 300 /// `src` is not used before the data is overwritten again (e.g. with `write`,
 301 /// `write_bytes`, or `copy`). Note that `*src = foo` counts as a use
 302 /// because it will attempt to drop the value previously at `*src`.
 303 ///
 304 /// # Examples
 305 ///
 306 /// Basic usage:
 307 ///
 308 /// ```
 309 /// let x = 12;
 310 /// let y = &x as *const i32;
 311 ///
 312 /// unsafe {
 313 ///     assert_eq!(std::ptr::read_unaligned(y), 12);
 314 /// }
 315 /// ```
 316 #[inline]
 317 #[stable(feature = "ptr_unaligned", since = "1.17.0")]
 318 pub unsafe fn read_unaligned<T>(src: *const T) -> T {
 319     let mut tmp: T = mem::uninitialized();
 320     copy_nonoverlapping(src as *const u8,
 321                         &mut tmp as *mut T as *mut u8,
 322                         mem::size_of::<T>());
 323     tmp
 324 }
 325
 326 /// Overwrites a memory location with the given value without reading or
 327 /// dropping the old value.
 328 ///
 329 /// # Safety
 330 ///
 331 /// This operation is marked unsafe because it accepts a raw pointer.
 332 ///
 333 /// It does not drop the contents of `dst`. This is safe, but it could leak
 334 /// allocations or resources, so care must be taken not to overwrite an object
 335 /// that should be dropped.
 336 ///
 337 /// Additionally, it does not drop `src`. Semantically, `src` is moved into the
 338 /// location pointed to by `dst`.
 339 ///
 340 /// This is appropriate for initializing uninitialized memory, or overwriting
 341 /// memory that has previously been `read` from.
 342 ///
 343 /// The pointer must be aligned; use `write_unaligned` if that is not the case.
 344 ///
 345 /// # Examples
 346 ///
 347 /// Basic usage:
 348 ///
 349 /// ```
 350 /// let mut x = 0;
 351 /// let y = &mut x as *mut i32;
 352 /// let z = 12;
 353 ///
 354 /// unsafe {
 355 ///     std::ptr::write(y, z);
 356 ///     assert_eq!(std::ptr::read(y), 12);
 357 /// }
 358 /// ```
 359 #[inline]
 360 #[stable(feature = "rust1", since = "1.0.0")]
 361 pub unsafe fn write<T>(dst: *mut T, src: T) {
 362     intrinsics::move_val_init(&mut *dst, src)
 363 }
 364
 365 /// Overwrites a memory location with the given value without reading or
 366 /// dropping the old value.
 367 ///
 368 /// Unlike `write`, the pointer may be unaligned.
 369 ///
 370 /// # Safety
 371 ///
 372 /// This operation is marked unsafe because it accepts a raw pointer.
 373 ///
 374 /// It does not drop the contents of `dst`. This is safe, but it could leak
 375 /// allocations or resources, so care must be taken not to overwrite an object
 376 /// that should be dropped.
 377 ///
 378 /// Additionally, it does not drop `src`. Semantically, `src` is moved into the
 379 /// location pointed to by `dst`.
 380 ///
 381 /// This is appropriate for initializing uninitialized memory, or overwriting
 382 /// memory that has previously been `read` from.
 383 ///
 384 /// # Examples
 385 ///
 386 /// Basic usage:
 387 ///
 388 /// ```
 389 /// let mut x = 0;
 390 /// let y = &mut x as *mut i32;
 391 /// let z = 12;
 392 ///
 393 /// unsafe {
 394 ///     std::ptr::write_unaligned(y, z);
 395 ///     assert_eq!(std::ptr::read_unaligned(y), 12);
 396 /// }
 397 /// ```
 398 #[inline]
 399 #[stable(feature = "ptr_unaligned", since = "1.17.0")]
 400 pub unsafe fn write_unaligned<T>(dst: *mut T, src: T) {
 401     copy_nonoverlapping(&src as *const T as *const u8,
 402                         dst as *mut u8,
 403                         mem::size_of::<T>());
 404     mem::forget(src);
 405 }
 406
 407 /// Performs a volatile read of the value from `src` without moving it. This
 408 /// leaves the memory in `src` unchanged.
 409 ///
 410 /// Volatile operations are intended to act on I/O memory, and are guaranteed
 411 /// to not be elided or reordered by the compiler across other volatile
 412 /// operations.
 413 ///
 414 /// # Notes
 415 ///
 416 /// Rust does not currently have a rigorously and formally defined memory model,
 417 /// so the precise semantics of what "volatile" means here is subject to change
 418 /// over time. That being said, the semantics will almost always end up pretty
 419 /// similar to [C11's definition of volatile][c11].
 420 ///
 421 /// The compiler shouldn't change the relative order or number of volatile
 422 /// memory operations. However, volatile memory operations on zero-sized types
 423 /// (e.g. if a zero-sized type is passed to `read_volatile`) are no-ops
 424 /// and may be ignored.
 425 ///
 426 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
 427 ///
 428 /// # Safety
 429 ///
 430 /// Beyond accepting a raw pointer, this is unsafe because it semantically
 431 /// moves the value out of `src` without preventing further usage of `src`.
 432 /// If `T` is not `Copy`, then care must be taken to ensure that the value at
 433 /// `src` is not used before the data is overwritten again (e.g. with `write`,
 434 /// `write_bytes`, or `copy`). Note that `*src = foo` counts as a use
 435 /// because it will attempt to drop the value previously at `*src`.
 436 ///
 437 /// # Examples
 438 ///
 439 /// Basic usage:
 440 ///
 441 /// ```
 442 /// let x = 12;
 443 /// let y = &x as *const i32;
 444 ///
 445 /// unsafe {
 446 ///     assert_eq!(std::ptr::read_volatile(y), 12);
 447 /// }
 448 /// ```
 449 #[inline]
 450 #[stable(feature = "volatile", since = "1.9.0")]
 451 pub unsafe fn read_volatile<T>(src: *const T) -> T {
 452     intrinsics::volatile_load(src)
 453 }
 454
 455 /// Performs a volatile write of a memory location with the given value without
 456 /// reading or dropping the old value.
 457 ///
 458 /// Volatile operations are intended to act on I/O memory, and are guaranteed
 459 /// to not be elided or reordered by the compiler across other volatile
 460 /// operations.
 461 ///
 462 /// # Notes
 463 ///
 464 /// Rust does not currently have a rigorously and formally defined memory model,
 465 /// so the precise semantics of what "volatile" means here is subject to change
 466 /// over time. That being said, the semantics will almost always end up pretty
 467 /// similar to [C11's definition of volatile][c11].
 468 ///
 469 /// The compiler shouldn't change the relative order or number of volatile
 470 /// memory operations. However, volatile memory operations on zero-sized types
 471 /// (e.g. if a zero-sized type is passed to `write_volatile`) are no-ops
 472 /// and may be ignored.
 473 ///
 474 /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
 475 ///
 476 /// # Safety
 477 ///
 478 /// This operation is marked unsafe because it accepts a raw pointer.
 479 ///
 480 /// It does not drop the contents of `dst`. This is safe, but it could leak
 481 /// allocations or resources, so care must be taken not to overwrite an object
 482 /// that should be dropped.
 483 ///
 484 /// This is appropriate for initializing uninitialized memory, or overwriting
 485 /// memory that has previously been `read` from.
 486 ///
 487 /// # Examples
 488 ///
 489 /// Basic usage:
 490 ///
 491 /// ```
 492 /// let mut x = 0;
 493 /// let y = &mut x as *mut i32;
 494 /// let z = 12;
 495 ///
 496 /// unsafe {
 497 ///     std::ptr::write_volatile(y, z);
 498 ///     assert_eq!(std::ptr::read_volatile(y), 12);
 499 /// }
 500 /// ```
 501 #[inline]
 502 #[stable(feature = "volatile", since = "1.9.0")]
 503 pub unsafe fn write_volatile<T>(dst: *mut T, src: T) {
 504     intrinsics::volatile_store(dst, src);
 505 }
 506
 507 #[lang = "const_ptr"]
 508 impl<T: ?Sized> *const T {
 509     /// Returns `true` if the pointer is null.
 510     ///
 511     /// Note that unsized types have many possible null pointers, as only the
 512     /// raw data pointer is considered, not their length, vtable, etc.
 513     /// Therefore, two pointers that are null may still not compare equal to
 514     /// each other.
 515     ///
 516     /// # Examples
 517     ///
 518     /// Basic usage:
 519     ///
 520     /// ```
 521     /// let s: &str = "Follow the rabbit";
 522     /// let ptr: *const u8 = s.as_ptr();
 523     /// assert!(!ptr.is_null());
 524     /// ```
 525     #[stable(feature = "rust1", since = "1.0.0")]
 526     #[inline]
 527     pub fn is_null(self) -> bool {
 528         // Compare via a cast to a thin pointer, so fat pointers are only
 529         // considering their "data" part for null-ness.
 530         (self as *const u8) == null()
 531     }
 532
 533     /// Returns `None` if the pointer is null, or else returns a reference to
 534     /// the value wrapped in `Some`.
 535     ///
 536     /// # Safety
 537     ///
 538     /// While this method and its mutable counterpart are useful for
 539     /// null-safety, it is important to note that this is still an unsafe
 540     /// operation because the returned value could be pointing to invalid
 541     /// memory.
 542     ///
 543     /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does
 544     /// not necessarily reflect the actual lifetime of the data.
 545     ///
 546     /// # Examples
 547     ///
 548     /// Basic usage:
 549     ///
 550     /// ```
 551     /// let ptr: *const u8 = &10u8 as *const u8;
 552     ///
 553     /// unsafe {
 554     ///     if let Some(val_back) = ptr.as_ref() {
 555     ///         println!("We got back the value: {}!", val_back);
 556     ///     }
 557     /// }
 558     /// ```
 559     #[stable(feature = "ptr_as_ref", since = "1.9.0")]
 560     #[inline]
 561     pub unsafe fn as_ref<'a>(self) -> Option<&'a T> {
 562         if self.is_null() {
 563             None
 564         } else {
 565             Some(&*self)
 566         }
 567     }
 568
 569     /// Calculates the offset from a pointer.
 570     ///
 571     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
 572     /// offset of `3 * size_of::<T>()` bytes.
 573     ///
 574     /// # Safety
 575     ///
 576     /// If any of the following conditions are violated, the result is Undefined
 577     /// Behavior:
 578     ///
 579     /// * Both the starting and resulting pointer must be either in bounds or one
 580     ///   byte past the end of an allocated object.
 581     ///
 582     /// * The computed offset, **in bytes**, cannot overflow an `isize`.
 583     ///
 584     /// * The offset being in bounds cannot rely on "wrapping around" the address
 585     ///   space. That is, the infinite-precision sum, **in bytes** must fit in a usize.
 586     ///
 587     /// The compiler and standard library generally tries to ensure allocations
 588     /// never reach a size where an offset is a concern. For instance, `Vec`
 589     /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so
 590     /// `vec.as_ptr().offset(vec.len() as isize)` is always safe.
 591     ///
 592     /// Most platforms fundamentally can't even construct such an allocation.
 593     /// For instance, no known 64-bit platform can ever serve a request
 594     /// for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
 595     /// However, some 32-bit and 16-bit platforms may successfully serve a request for
 596     /// more than `isize::MAX` bytes with things like Physical Address
 597     /// Extension. As such, memory acquired directly from allocators or memory
 598     /// mapped files *may* be too large to handle with this function.
 599     ///
 600     /// Consider using `wrapping_offset` instead if these constraints are
 601     /// difficult to satisfy. The only advantage of this method is that it
 602     /// enables more aggressive compiler optimizations.
 603     ///
 604     /// # Examples
 605     ///
 606     /// Basic usage:
 607     ///
 608     /// ```
 609     /// let s: &str = "123";
 610     /// let ptr: *const u8 = s.as_ptr();
 611     ///
 612     /// unsafe {
 613     ///     println!("{}", *ptr.offset(1) as char);
 614     ///     println!("{}", *ptr.offset(2) as char);
 615     /// }
 616     /// ```
 617     #[stable(feature = "rust1", since = "1.0.0")]
 618     #[inline]
 619     pub unsafe fn offset(self, count: isize) -> *const T where T: Sized {
 620         intrinsics::offset(self, count)
 621     }
 622
 623     /// Calculates the offset from a pointer using wrapping arithmetic.
 624     ///
 625     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
 626     /// offset of `3 * size_of::<T>()` bytes.
 627     ///
 628     /// # Safety
 629     ///
 630     /// The resulting pointer does not need to be in bounds, but it is
 631     /// potentially hazardous to dereference (which requires `unsafe`).
 632     ///
 633     /// Always use `.offset(count)` instead when possible, because `offset`
 634     /// allows the compiler to optimize better.
 635     ///
 636     /// # Examples
 637     ///
 638     /// Basic usage:
 639     ///
 640     /// ```
 641     /// // Iterate using a raw pointer in increments of two elements
 642     /// let data = [1u8, 2, 3, 4, 5];
 643     /// let mut ptr: *const u8 = data.as_ptr();
 644     /// let step = 2;
 645     /// let end_rounded_up = ptr.wrapping_offset(6);
 646     ///
 647     /// // This loop prints "1, 3, 5, "
 648     /// while ptr != end_rounded_up {
 649     ///     unsafe {
 650     ///         print!("{}, ", *ptr);
 651     ///     }
 652     ///     ptr = ptr.wrapping_offset(step);
 653     /// }
 654     /// ```
 655     #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
 656     #[inline]
 657     pub fn wrapping_offset(self, count: isize) -> *const T where T: Sized {
 658         unsafe {
 659             intrinsics::arith_offset(self, count)
 660         }
 661     }
 662
 663     /// Calculates the distance between two pointers. The returned value is in
 664     /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
 665     ///
 666     /// If the address different between the two pointers ia not a multiple of
 667     /// `mem::size_of::<T>()` then the result of the division is rounded towards
 668     /// zero.
 669     ///
 670     /// This function returns `None` if `T` is a zero-sized type.
 671     ///
 672     /// # Examples
 673     ///
 674     /// Basic usage:
 675     ///
 676     /// ```
 677     /// #![feature(offset_to)]
 678     /// #![allow(deprecated)]
 679     ///
 680     /// fn main() {
 681     ///     let a = [0; 5];
 682     ///     let ptr1: *const i32 = &a[1];
 683     ///     let ptr2: *const i32 = &a[3];
 684     ///     assert_eq!(ptr1.offset_to(ptr2), Some(2));
 685     ///     assert_eq!(ptr2.offset_to(ptr1), Some(-2));
 686     ///     assert_eq!(unsafe { ptr1.offset(2) }, ptr2);
 687     ///     assert_eq!(unsafe { ptr2.offset(-2) }, ptr1);
 688     /// }
 689     /// ```
 690     #[unstable(feature = "offset_to", issue = "41079")]
 691     #[rustc_deprecated(since = "1.27.0", reason = "Replaced by `wrapping_offset_from`, with the \
 692         opposite argument order.  If you're writing unsafe code, consider `offset_from`.")]
 693     #[inline]
 694     pub fn offset_to(self, other: *const T) -> Option<isize> where T: Sized {
 695         let size = mem::size_of::<T>();
 696         if size == 0 {
 697             None
 698         } else {
 699             Some(other.wrapping_offset_from(self))
 700         }
 701     }
 702
 703     /// Calculates the distance between two pointers. The returned value is in
 704     /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
 705     ///
 706     /// This function is the inverse of [`offset`].
 707     ///
 708     /// [`offset`]: #method.offset
 709     /// [`wrapping_offset_from`]: #method.wrapping_offset_from
 710     ///
 711     /// # Safety
 712     ///
 713     /// If any of the following conditions are violated, the result is Undefined
 714     /// Behavior:
 715     ///
 716     /// * Both the starting and other pointer must be either in bounds or one
 717     ///   byte past the end of the same allocated object.
 718     ///
 719     /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`.
 720     ///
 721     /// * The distance between the pointers, in bytes, must be an exact multiple
 722     ///   of the size of `T`.
 723     ///
 724     /// * The distance being in bounds cannot rely on "wrapping around" the address space.
 725     ///
 726     /// The compiler and standard library generally try to ensure allocations
 727     /// never reach a size where an offset is a concern. For instance, `Vec`
 728     /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so
 729     /// `ptr_into_vec.offset_from(vec.as_ptr())` is always safe.
 730     ///
 731     /// Most platforms fundamentally can't even construct such an allocation.
 732     /// For instance, no known 64-bit platform can ever serve a request
 733     /// for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
 734     /// However, some 32-bit and 16-bit platforms may successfully serve a request for
 735     /// more than `isize::MAX` bytes with things like Physical Address
 736     /// Extension. As such, memory acquired directly from allocators or memory
 737     /// mapped files *may* be too large to handle with this function.
 738     ///
 739     /// Consider using [`wrapping_offset_from`] instead if these constraints are
 740     /// difficult to satisfy. The only advantage of this method is that it
 741     /// enables more aggressive compiler optimizations.
 742     ///
 743     /// # Panics
 744     ///
 745     /// This function panics if `T` is a Zero-Sized Type ("ZST").
 746     ///
 747     /// # Examples
 748     ///
 749     /// Basic usage:
 750     ///
 751     /// ```
 752     /// #![feature(ptr_offset_from)]
 753     ///
 754     /// let a = [0; 5];
 755     /// let ptr1: *const i32 = &a[1];
 756     /// let ptr2: *const i32 = &a[3];
 757     /// unsafe {
 758     ///     assert_eq!(ptr2.offset_from(ptr1), 2);
 759     ///     assert_eq!(ptr1.offset_from(ptr2), -2);
 760     ///     assert_eq!(ptr1.offset(2), ptr2);
 761     ///     assert_eq!(ptr2.offset(-2), ptr1);
 762     /// }
 763     /// ```
 764     #[unstable(feature = "ptr_offset_from", issue = "41079")]
 765     #[inline]
 766     pub unsafe fn offset_from(self, origin: *const T) -> isize where T: Sized {
 767         let pointee_size = mem::size_of::<T>();
 768         assert!(0 < pointee_size && pointee_size <= isize::max_value() as usize);
 769
 770         // This is the same sequence that Clang emits for pointer subtraction.
 771         // It can be neither `nsw` nor `nuw` because the input is treated as
 772         // unsigned but then the output is treated as signed, so neither works.
 773         let d = isize::wrapping_sub(self as _, origin as _);
 774         intrinsics::exact_div(d, pointee_size as _)
 775     }
 776
 777     /// Calculates the distance between two pointers. The returned value is in
 778     /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
 779     ///
 780     /// If the address different between the two pointers is not a multiple of
 781     /// `mem::size_of::<T>()` then the result of the division is rounded towards
 782     /// zero.
 783     ///
 784     /// Though this method is safe for any two pointers, note that its result
 785     /// will be mostly useless if the two pointers aren't into the same allocated
 786     /// object, for example if they point to two different local variables.
 787     ///
 788     /// # Panics
 789     ///
 790     /// This function panics if `T` is a zero-sized type.
 791     ///
 792     /// # Examples
 793     ///
 794     /// Basic usage:
 795     ///
 796     /// ```
 797     /// #![feature(ptr_wrapping_offset_from)]
 798     ///
 799     /// let a = [0; 5];
 800     /// let ptr1: *const i32 = &a[1];
 801     /// let ptr2: *const i32 = &a[3];
 802     /// assert_eq!(ptr2.wrapping_offset_from(ptr1), 2);
 803     /// assert_eq!(ptr1.wrapping_offset_from(ptr2), -2);
 804     /// assert_eq!(ptr1.wrapping_offset(2), ptr2);
 805     /// assert_eq!(ptr2.wrapping_offset(-2), ptr1);
 806     ///
 807     /// let ptr1: *const i32 = 3 as _;
 808     /// let ptr2: *const i32 = 13 as _;
 809     /// assert_eq!(ptr2.wrapping_offset_from(ptr1), 2);
 810     /// ```
 811     #[unstable(feature = "ptr_wrapping_offset_from", issue = "41079")]
 812     #[inline]
 813     pub fn wrapping_offset_from(self, origin: *const T) -> isize where T: Sized {
 814         let pointee_size = mem::size_of::<T>();
 815         assert!(0 < pointee_size && pointee_size <= isize::max_value() as usize);
 816
 817         let d = isize::wrapping_sub(self as _, origin as _);
 818         d.wrapping_div(pointee_size as _)
 819     }
 820
 821     /// Calculates the offset from a pointer (convenience for `.offset(count as isize)`).
 822     ///
 823     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
 824     /// offset of `3 * size_of::<T>()` bytes.
 825     ///
 826     /// # Safety
 827     ///
 828     /// If any of the following conditions are violated, the result is Undefined
 829     /// Behavior:
 830     ///
 831     /// * Both the starting and resulting pointer must be either in bounds or one
 832     ///   byte past the end of an allocated object.
 833     ///
 834     /// * The computed offset, **in bytes**, cannot overflow an `isize`.
 835     ///
 836     /// * The offset being in bounds cannot rely on "wrapping around" the address
 837     ///   space. That is, the infinite-precision sum must fit in a `usize`.
 838     ///
 839     /// The compiler and standard library generally tries to ensure allocations
 840     /// never reach a size where an offset is a concern. For instance, `Vec`
 841     /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so
 842     /// `vec.as_ptr().add(vec.len())` is always safe.
 843     ///
 844     /// Most platforms fundamentally can't even construct such an allocation.
 845     /// For instance, no known 64-bit platform can ever serve a request
 846     /// for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
 847     /// However, some 32-bit and 16-bit platforms may successfully serve a request for
 848     /// more than `isize::MAX` bytes with things like Physical Address
 849     /// Extension. As such, memory acquired directly from allocators or memory
 850     /// mapped files *may* be too large to handle with this function.
 851     ///
 852     /// Consider using `wrapping_offset` instead if these constraints are
 853     /// difficult to satisfy. The only advantage of this method is that it
 854     /// enables more aggressive compiler optimizations.
 855     ///
 856     /// # Examples
 857     ///
 858     /// Basic usage:
 859     ///
 860     /// ```
 861     /// let s: &str = "123";
 862     /// let ptr: *const u8 = s.as_ptr();
 863     ///
 864     /// unsafe {
 865     ///     println!("{}", *ptr.add(1) as char);
 866     ///     println!("{}", *ptr.add(2) as char);
 867     /// }
 868     /// ```
 869     #[stable(feature = "pointer_methods", since = "1.26.0")]
 870     #[inline]
 871     pub unsafe fn add(self, count: usize) -> Self
 872         where T: Sized,
 873     {
 874         self.offset(count as isize)
 875     }
 876
 877     /// Calculates the offset from a pointer (convenience for
 878     /// `.offset((count as isize).wrapping_neg())`).
 879     ///
 880     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
 881     /// offset of `3 * size_of::<T>()` bytes.
 882     ///
 883     /// # Safety
 884     ///
 885     /// If any of the following conditions are violated, the result is Undefined
 886     /// Behavior:
 887     ///
 888     /// * Both the starting and resulting pointer must be either in bounds or one
 889     ///   byte past the end of an allocated object.
 890     ///
 891     /// * The computed offset cannot exceed `isize::MAX` **bytes**.
 892     ///
 893     /// * The offset being in bounds cannot rely on "wrapping around" the address
 894     ///   space. That is, the infinite-precision sum must fit in a usize.
 895     ///
 896     /// The compiler and standard library generally tries to ensure allocations
 897     /// never reach a size where an offset is a concern. For instance, `Vec`
 898     /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so
 899     /// `vec.as_ptr().add(vec.len()).sub(vec.len())` is always safe.
 900     ///
 901     /// Most platforms fundamentally can't even construct such an allocation.
 902     /// For instance, no known 64-bit platform can ever serve a request
 903     /// for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
 904     /// However, some 32-bit and 16-bit platforms may successfully serve a request for
 905     /// more than `isize::MAX` bytes with things like Physical Address
 906     /// Extension. As such, memory acquired directly from allocators or memory
 907     /// mapped files *may* be too large to handle with this function.
 908     ///
 909     /// Consider using `wrapping_offset` instead if these constraints are
 910     /// difficult to satisfy. The only advantage of this method is that it
 911     /// enables more aggressive compiler optimizations.
 912     ///
 913     /// # Examples
 914     ///
 915     /// Basic usage:
 916     ///
 917     /// ```
 918     /// let s: &str = "123";
 919     ///
 920     /// unsafe {
 921     ///     let end: *const u8 = s.as_ptr().add(3);
 922     ///     println!("{}", *end.sub(1) as char);
 923     ///     println!("{}", *end.sub(2) as char);
 924     /// }
 925     /// ```
 926     #[stable(feature = "pointer_methods", since = "1.26.0")]
 927     #[inline]
 928     pub unsafe fn sub(self, count: usize) -> Self
 929         where T: Sized,
 930     {
 931         self.offset((count as isize).wrapping_neg())
 932     }
 933
 934     /// Calculates the offset from a pointer using wrapping arithmetic.
 935     /// (convenience for `.wrapping_offset(count as isize)`)
 936     ///
 937     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
 938     /// offset of `3 * size_of::<T>()` bytes.
 939     ///
 940     /// # Safety
 941     ///
 942     /// The resulting pointer does not need to be in bounds, but it is
 943     /// potentially hazardous to dereference (which requires `unsafe`).
 944     ///
 945     /// Always use `.add(count)` instead when possible, because `add`
 946     /// allows the compiler to optimize better.
 947     ///
 948     /// # Examples
 949     ///
 950     /// Basic usage:
 951     ///
 952     /// ```
 953     /// // Iterate using a raw pointer in increments of two elements
 954     /// let data = [1u8, 2, 3, 4, 5];
 955     /// let mut ptr: *const u8 = data.as_ptr();
 956     /// let step = 2;
 957     /// let end_rounded_up = ptr.wrapping_add(6);
 958     ///
 959     /// // This loop prints "1, 3, 5, "
 960     /// while ptr != end_rounded_up {
 961     ///     unsafe {
 962     ///         print!("{}, ", *ptr);
 963     ///     }
 964     ///     ptr = ptr.wrapping_add(step);
 965     /// }
 966     /// ```
 967     #[stable(feature = "pointer_methods", since = "1.26.0")]
 968     #[inline]
 969     pub fn wrapping_add(self, count: usize) -> Self
 970         where T: Sized,
 971     {
 972         self.wrapping_offset(count as isize)
 973     }
 974
 975     /// Calculates the offset from a pointer using wrapping arithmetic.
 976     /// (convenience for `.wrapping_offset((count as isize).wrapping_sub())`)
 977     ///
 978     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
 979     /// offset of `3 * size_of::<T>()` bytes.
 980     ///
 981     /// # Safety
 982     ///
 983     /// The resulting pointer does not need to be in bounds, but it is
 984     /// potentially hazardous to dereference (which requires `unsafe`).
 985     ///
 986     /// Always use `.sub(count)` instead when possible, because `sub`
 987     /// allows the compiler to optimize better.
 988     ///
 989     /// # Examples
 990     ///
 991     /// Basic usage:
 992     ///
 993     /// ```
 994     /// // Iterate using a raw pointer in increments of two elements (backwards)
 995     /// let data = [1u8, 2, 3, 4, 5];
 996     /// let mut ptr: *const u8 = data.as_ptr();
 997     /// let start_rounded_down = ptr.wrapping_sub(2);
 998     /// ptr = ptr.wrapping_add(4);
 999     /// let step = 2;
1000     /// // This loop prints "5, 3, 1, "
1001     /// while ptr != start_rounded_down {
1002     ///     unsafe {
1003     ///         print!("{}, ", *ptr);
1004     ///     }
1005     ///     ptr = ptr.wrapping_sub(step);
1006     /// }
1007     /// ```
1008     #[stable(feature = "pointer_methods", since = "1.26.0")]
1009     #[inline]
1010     pub fn wrapping_sub(self, count: usize) -> Self
1011         where T: Sized,
1012     {
1013         self.wrapping_offset((count as isize).wrapping_neg())
1014     }
1015
1016     /// Reads the value from `self` without moving it. This leaves the
1017     /// memory in `self` unchanged.
1018     ///
1019     /// # Safety
1020     ///
1021     /// Beyond accepting a raw pointer, this is unsafe because it semantically
1022     /// moves the value out of `self` without preventing further usage of `self`.
1023     /// If `T` is not `Copy`, then care must be taken to ensure that the value at
1024     /// `self` is not used before the data is overwritten again (e.g. with `write`,
1025     /// `write_bytes`, or `copy`). Note that `*self = foo` counts as a use
1026     /// because it will attempt to drop the value previously at `*self`.
1027     ///
1028     /// The pointer must be aligned; use `read_unaligned` if that is not the case.
1029     ///
1030     /// # Examples
1031     ///
1032     /// Basic usage:
1033     ///
1034     /// ```
1035     /// let x = 12;
1036     /// let y = &x as *const i32;
1037     ///
1038     /// unsafe {
1039     ///     assert_eq!(y.read(), 12);
1040     /// }
1041     /// ```
1042     #[stable(feature = "pointer_methods", since = "1.26.0")]
1043     #[inline]
1044     pub unsafe fn read(self) -> T
1045         where T: Sized,
1046     {
1047         read(self)
1048     }
1049
1050     /// Performs a volatile read of the value from `self` without moving it. This
1051     /// leaves the memory in `self` unchanged.
1052     ///
1053     /// Volatile operations are intended to act on I/O memory, and are guaranteed
1054     /// to not be elided or reordered by the compiler across other volatile
1055     /// operations.
1056     ///
1057     /// # Notes
1058     ///
1059     /// Rust does not currently have a rigorously and formally defined memory model,
1060     /// so the precise semantics of what "volatile" means here is subject to change
1061     /// over time. That being said, the semantics will almost always end up pretty
1062     /// similar to [C11's definition of volatile][c11].
1063     ///
1064     /// The compiler shouldn't change the relative order or number of volatile
1065     /// memory operations. However, volatile memory operations on zero-sized types
1066     /// (e.g. if a zero-sized type is passed to `read_volatile`) are no-ops
1067     /// and may be ignored.
1068     ///
1069     /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
1070     ///
1071     /// # Safety
1072     ///
1073     /// Beyond accepting a raw pointer, this is unsafe because it semantically
1074     /// moves the value out of `self` without preventing further usage of `self`.
1075     /// If `T` is not `Copy`, then care must be taken to ensure that the value at
1076     /// `self` is not used before the data is overwritten again (e.g. with `write`,
1077     /// `write_bytes`, or `copy`). Note that `*self = foo` counts as a use
1078     /// because it will attempt to drop the value previously at `*self`.
1079     ///
1080     /// # Examples
1081     ///
1082     /// Basic usage:
1083     ///
1084     /// ```
1085     /// let x = 12;
1086     /// let y = &x as *const i32;
1087     ///
1088     /// unsafe {
1089     ///     assert_eq!(y.read_volatile(), 12);
1090     /// }
1091     /// ```
1092     #[stable(feature = "pointer_methods", since = "1.26.0")]
1093     #[inline]
1094     pub unsafe fn read_volatile(self) -> T
1095         where T: Sized,
1096     {
1097         read_volatile(self)
1098     }
1099
1100     /// Reads the value from `self` without moving it. This leaves the
1101     /// memory in `self` unchanged.
1102     ///
1103     /// Unlike `read`, the pointer may be unaligned.
1104     ///
1105     /// # Safety
1106     ///
1107     /// Beyond accepting a raw pointer, this is unsafe because it semantically
1108     /// moves the value out of `self` without preventing further usage of `self`.
1109     /// If `T` is not `Copy`, then care must be taken to ensure that the value at
1110     /// `self` is not used before the data is overwritten again (e.g. with `write`,
1111     /// `write_bytes`, or `copy`). Note that `*self = foo` counts as a use
1112     /// because it will attempt to drop the value previously at `*self`.
1113     ///
1114     /// # Examples
1115     ///
1116     /// Basic usage:
1117     ///
1118     /// ```
1119     /// let x = 12;
1120     /// let y = &x as *const i32;
1121     ///
1122     /// unsafe {
1123     ///     assert_eq!(y.read_unaligned(), 12);
1124     /// }
1125     /// ```
1126     #[stable(feature = "pointer_methods", since = "1.26.0")]
1127     #[inline]
1128     pub unsafe fn read_unaligned(self) -> T
1129         where T: Sized,
1130     {
1131         read_unaligned(self)
1132     }
1133
1134     /// Copies `count * size_of<T>` bytes from `self` to `dest`. The source
1135     /// and destination may overlap.
1136     ///
1137     /// NOTE: this has the *same* argument order as `ptr::copy`.
1138     ///
1139     /// This is semantically equivalent to C's `memmove`.
1140     ///
1141     /// # Safety
1142     ///
1143     /// Care must be taken with the ownership of `self` and `dest`.
1144     /// This method semantically moves the values of `self` into `dest`.
1145     /// However it does not drop the contents of `self`, or prevent the contents
1146     /// of `dest` from being dropped or used.
1147     ///
1148     /// # Examples
1149     ///
1150     /// Efficiently create a Rust vector from an unsafe buffer:
1151     ///
1152     /// ```
1153     /// # #[allow(dead_code)]
1154     /// unsafe fn from_buf_raw<T: Copy>(ptr: *const T, elts: usize) -> Vec<T> {
1155     ///     let mut dst = Vec::with_capacity(elts);
1156     ///     dst.set_len(elts);
1157     ///     ptr.copy_to(dst.as_mut_ptr(), elts);
1158     ///     dst
1159     /// }
1160     /// ```
1161     #[stable(feature = "pointer_methods", since = "1.26.0")]
1162     #[inline]
1163     pub unsafe fn copy_to(self, dest: *mut T, count: usize)
1164         where T: Sized,
1165     {
1166         copy(self, dest, count)
1167     }
1168
1169     /// Copies `count * size_of<T>` bytes from `self` to `dest`. The source
1170     /// and destination may *not* overlap.
1171     ///
1172     /// NOTE: this has the *same* argument order as `ptr::copy_nonoverlapping`.
1173     ///
1174     /// `copy_nonoverlapping` is semantically equivalent to C's `memcpy`.
1175     ///
1176     /// # Safety
1177     ///
1178     /// Beyond requiring that the program must be allowed to access both regions
1179     /// of memory, it is Undefined Behavior for source and destination to
1180     /// overlap. Care must also be taken with the ownership of `self` and
1181     /// `self`. This method semantically moves the values of `self` into `dest`.
1182     /// However it does not drop the contents of `dest`, or prevent the contents
1183     /// of `self` from being dropped or used.
1184     ///
1185     /// # Examples
1186     ///
1187     /// Efficiently create a Rust vector from an unsafe buffer:
1188     ///
1189     /// ```
1190     /// # #[allow(dead_code)]
1191     /// unsafe fn from_buf_raw<T: Copy>(ptr: *const T, elts: usize) -> Vec<T> {
1192     ///     let mut dst = Vec::with_capacity(elts);
1193     ///     dst.set_len(elts);
1194     ///     ptr.copy_to_nonoverlapping(dst.as_mut_ptr(), elts);
1195     ///     dst
1196     /// }
1197     /// ```
1198     #[stable(feature = "pointer_methods", since = "1.26.0")]
1199     #[inline]
1200     pub unsafe fn copy_to_nonoverlapping(self, dest: *mut T, count: usize)
1201         where T: Sized,
1202     {
1203         copy_nonoverlapping(self, dest, count)
1204     }
1205
1206     /// Computes the offset that needs to be applied to the pointer in order to make it aligned to
1207     /// `align`.
1208     ///
1209     /// If it is not possible to align the pointer, the implementation returns
1210     /// `usize::max_value()`.
1211     ///
1212     /// The offset is expressed in number of `T` elements, and not bytes. The value returned can be
1213     /// used with the `offset` or `offset_to` methods.
1214     ///
1215     /// There are no guarantees whatsover that offsetting the pointer will not overflow or go
1216     /// beyond the allocation that the pointer points into. It is up to the caller to ensure that
1217     /// the returned offset is correct in all terms other than alignment.
1218     ///
1219     /// # Panics
1220     ///
1221     /// The function panics if `align` is not a power-of-two.
1222     ///
1223     /// # Examples
1224     ///
1225     /// Accessing adjacent `u8` as `u16`
1226     ///
1227     /// ```
1228     /// # #![feature(align_offset)]
1229     /// # fn foo(n: usize) {
1230     /// # use std::mem::align_of;
1231     /// # unsafe {
1232     /// let x = [5u8, 6u8, 7u8, 8u8, 9u8];
1233     /// let ptr = &x[n] as *const u8;
1234     /// let offset = ptr.align_offset(align_of::<u16>());
1235     /// if offset < x.len() - n - 1 {
1236     ///     let u16_ptr = ptr.offset(offset as isize) as *const u16;
1237     ///     assert_ne!(*u16_ptr, 500);
1238     /// } else {
1239     ///     // while the pointer can be aligned via `offset`, it would point
1240     ///     // outside the allocation
1241     /// }
1242     /// # } }
1243     /// ```
1244     #[unstable(feature = "align_offset", issue = "44488")]
1245     #[cfg(not(stage0))]
1246     pub fn align_offset(self, align: usize) -> usize where T: Sized {
1247         if !align.is_power_of_two() {
1248             panic!("align_offset: align is not a power-of-two");
1249         }
1250         unsafe {
1251             align_offset(self, align)
1252         }
1253     }
1254
1255     /// definitely docs.
1256     #[unstable(feature = "align_offset", issue = "44488")]
1257     #[cfg(stage0)]
1258     pub fn align_offset(self, align: usize) -> usize where T: Sized {
1259         if !align.is_power_of_two() {
1260             panic!("align_offset: align is not a power-of-two");
1261         }
1262         unsafe {
1263             intrinsics::align_offset(self as *const (), align)
1264         }
1265     }
1266 }
1267
1268
1269 #[lang = "mut_ptr"]
1270 impl<T: ?Sized> *mut T {
1271     /// Returns `true` if the pointer is null.
1272     ///
1273     /// Note that unsized types have many possible null pointers, as only the
1274     /// raw data pointer is considered, not their length, vtable, etc.
1275     /// Therefore, two pointers that are null may still not compare equal to
1276     /// each other.
1277     ///
1278     /// # Examples
1279     ///
1280     /// Basic usage:
1281     ///
1282     /// ```
1283     /// let mut s = [1, 2, 3];
1284     /// let ptr: *mut u32 = s.as_mut_ptr();
1285     /// assert!(!ptr.is_null());
1286     /// ```
1287     #[stable(feature = "rust1", since = "1.0.0")]
1288     #[inline]
1289     pub fn is_null(self) -> bool {
1290         // Compare via a cast to a thin pointer, so fat pointers are only
1291         // considering their "data" part for null-ness.
1292         (self as *mut u8) == null_mut()
1293     }
1294
1295     /// Returns `None` if the pointer is null, or else returns a reference to
1296     /// the value wrapped in `Some`.
1297     ///
1298     /// # Safety
1299     ///
1300     /// While this method and its mutable counterpart are useful for
1301     /// null-safety, it is important to note that this is still an unsafe
1302     /// operation because the returned value could be pointing to invalid
1303     /// memory.
1304     ///
1305     /// Additionally, the lifetime `'a` returned is arbitrarily chosen and does
1306     /// not necessarily reflect the actual lifetime of the data.
1307     ///
1308     /// # Examples
1309     ///
1310     /// Basic usage:
1311     ///
1312     /// ```
1313     /// let ptr: *mut u8 = &mut 10u8 as *mut u8;
1314     ///
1315     /// unsafe {
1316     ///     if let Some(val_back) = ptr.as_ref() {
1317     ///         println!("We got back the value: {}!", val_back);
1318     ///     }
1319     /// }
1320     /// ```
1321     #[stable(feature = "ptr_as_ref", since = "1.9.0")]
1322     #[inline]
1323     pub unsafe fn as_ref<'a>(self) -> Option<&'a T> {
1324         if self.is_null() {
1325             None
1326         } else {
1327             Some(&*self)
1328         }
1329     }
1330
1331     /// Calculates the offset from a pointer.
1332     ///
1333     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
1334     /// offset of `3 * size_of::<T>()` bytes.
1335     ///
1336     /// # Safety
1337     ///
1338     /// If any of the following conditions are violated, the result is Undefined
1339     /// Behavior:
1340     ///
1341     /// * Both the starting and resulting pointer must be either in bounds or one
1342     ///   byte past the end of an allocated object.
1343     ///
1344     /// * The computed offset, **in bytes**, cannot overflow an `isize`.
1345     ///
1346     /// * The offset being in bounds cannot rely on "wrapping around" the address
1347     ///   space. That is, the infinite-precision sum, **in bytes** must fit in a usize.
1348     ///
1349     /// The compiler and standard library generally tries to ensure allocations
1350     /// never reach a size where an offset is a concern. For instance, `Vec`
1351     /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so
1352     /// `vec.as_ptr().offset(vec.len() as isize)` is always safe.
1353     ///
1354     /// Most platforms fundamentally can't even construct such an allocation.
1355     /// For instance, no known 64-bit platform can ever serve a request
1356     /// for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
1357     /// However, some 32-bit and 16-bit platforms may successfully serve a request for
1358     /// more than `isize::MAX` bytes with things like Physical Address
1359     /// Extension. As such, memory acquired directly from allocators or memory
1360     /// mapped files *may* be too large to handle with this function.
1361     ///
1362     /// Consider using `wrapping_offset` instead if these constraints are
1363     /// difficult to satisfy. The only advantage of this method is that it
1364     /// enables more aggressive compiler optimizations.
1365     ///
1366     /// # Examples
1367     ///
1368     /// Basic usage:
1369     ///
1370     /// ```
1371     /// let mut s = [1, 2, 3];
1372     /// let ptr: *mut u32 = s.as_mut_ptr();
1373     ///
1374     /// unsafe {
1375     ///     println!("{}", *ptr.offset(1));
1376     ///     println!("{}", *ptr.offset(2));
1377     /// }
1378     /// ```
1379     #[stable(feature = "rust1", since = "1.0.0")]
1380     #[inline]
1381     pub unsafe fn offset(self, count: isize) -> *mut T where T: Sized {
1382         intrinsics::offset(self, count) as *mut T
1383     }
1384
1385     /// Calculates the offset from a pointer using wrapping arithmetic.
1386     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
1387     /// offset of `3 * size_of::<T>()` bytes.
1388     ///
1389     /// # Safety
1390     ///
1391     /// The resulting pointer does not need to be in bounds, but it is
1392     /// potentially hazardous to dereference (which requires `unsafe`).
1393     ///
1394     /// Always use `.offset(count)` instead when possible, because `offset`
1395     /// allows the compiler to optimize better.
1396     ///
1397     /// # Examples
1398     ///
1399     /// Basic usage:
1400     ///
1401     /// ```
1402     /// // Iterate using a raw pointer in increments of two elements
1403     /// let mut data = [1u8, 2, 3, 4, 5];
1404     /// let mut ptr: *mut u8 = data.as_mut_ptr();
1405     /// let step = 2;
1406     /// let end_rounded_up = ptr.wrapping_offset(6);
1407     ///
1408     /// while ptr != end_rounded_up {
1409     ///     unsafe {
1410     ///         *ptr = 0;
1411     ///     }
1412     ///     ptr = ptr.wrapping_offset(step);
1413     /// }
1414     /// assert_eq!(&data, &[0, 2, 0, 4, 0]);
1415     /// ```
1416     #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")]
1417     #[inline]
1418     pub fn wrapping_offset(self, count: isize) -> *mut T where T: Sized {
1419         unsafe {
1420             intrinsics::arith_offset(self, count) as *mut T
1421         }
1422     }
1423
1424     /// Returns `None` if the pointer is null, or else returns a mutable
1425     /// reference to the value wrapped in `Some`.
1426     ///
1427     /// # Safety
1428     ///
1429     /// As with `as_ref`, this is unsafe because it cannot verify the validity
1430     /// of the returned pointer, nor can it ensure that the lifetime `'a`
1431     /// returned is indeed a valid lifetime for the contained data.
1432     ///
1433     /// # Examples
1434     ///
1435     /// Basic usage:
1436     ///
1437     /// ```
1438     /// let mut s = [1, 2, 3];
1439     /// let ptr: *mut u32 = s.as_mut_ptr();
1440     /// let first_value = unsafe { ptr.as_mut().unwrap() };
1441     /// *first_value = 4;
1442     /// println!("{:?}", s); // It'll print: "[4, 2, 3]".
1443     /// ```
1444     #[stable(feature = "ptr_as_ref", since = "1.9.0")]
1445     #[inline]
1446     pub unsafe fn as_mut<'a>(self) -> Option<&'a mut T> {
1447         if self.is_null() {
1448             None
1449         } else {
1450             Some(&mut *self)
1451         }
1452     }
1453
1454     /// Calculates the distance between two pointers. The returned value is in
1455     /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
1456     ///
1457     /// If the address different between the two pointers ia not a multiple of
1458     /// `mem::size_of::<T>()` then the result of the division is rounded towards
1459     /// zero.
1460     ///
1461     /// This function returns `None` if `T` is a zero-sized type.
1462     ///
1463     /// # Examples
1464     ///
1465     /// Basic usage:
1466     ///
1467     /// ```
1468     /// #![feature(offset_to)]
1469     /// #![allow(deprecated)]
1470     ///
1471     /// fn main() {
1472     ///     let mut a = [0; 5];
1473     ///     let ptr1: *mut i32 = &mut a[1];
1474     ///     let ptr2: *mut i32 = &mut a[3];
1475     ///     assert_eq!(ptr1.offset_to(ptr2), Some(2));
1476     ///     assert_eq!(ptr2.offset_to(ptr1), Some(-2));
1477     ///     assert_eq!(unsafe { ptr1.offset(2) }, ptr2);
1478     ///     assert_eq!(unsafe { ptr2.offset(-2) }, ptr1);
1479     /// }
1480     /// ```
1481     #[unstable(feature = "offset_to", issue = "41079")]
1482     #[rustc_deprecated(since = "1.27.0", reason = "Replaced by `wrapping_offset_from`, with the \
1483         opposite argument order.  If you're writing unsafe code, consider `offset_from`.")]
1484     #[inline]
1485     pub fn offset_to(self, other: *const T) -> Option<isize> where T: Sized {
1486         let size = mem::size_of::<T>();
1487         if size == 0 {
1488             None
1489         } else {
1490             Some(other.wrapping_offset_from(self))
1491         }
1492     }
1493
1494     /// Calculates the distance between two pointers. The returned value is in
1495     /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
1496     ///
1497     /// This function is the inverse of [`offset`].
1498     ///
1499     /// [`offset`]: #method.offset-1
1500     /// [`wrapping_offset_from`]: #method.wrapping_offset_from-1
1501     ///
1502     /// # Safety
1503     ///
1504     /// If any of the following conditions are violated, the result is Undefined
1505     /// Behavior:
1506     ///
1507     /// * Both the starting and other pointer must be either in bounds or one
1508     ///   byte past the end of the same allocated object.
1509     ///
1510     /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`.
1511     ///
1512     /// * The distance between the pointers, in bytes, must be an exact multiple
1513     ///   of the size of `T`.
1514     ///
1515     /// * The distance being in bounds cannot rely on "wrapping around" the address space.
1516     ///
1517     /// The compiler and standard library generally try to ensure allocations
1518     /// never reach a size where an offset is a concern. For instance, `Vec`
1519     /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so
1520     /// `ptr_into_vec.offset_from(vec.as_ptr())` is always safe.
1521     ///
1522     /// Most platforms fundamentally can't even construct such an allocation.
1523     /// For instance, no known 64-bit platform can ever serve a request
1524     /// for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
1525     /// However, some 32-bit and 16-bit platforms may successfully serve a request for
1526     /// more than `isize::MAX` bytes with things like Physical Address
1527     /// Extension. As such, memory acquired directly from allocators or memory
1528     /// mapped files *may* be too large to handle with this function.
1529     ///
1530     /// Consider using [`wrapping_offset_from`] instead if these constraints are
1531     /// difficult to satisfy. The only advantage of this method is that it
1532     /// enables more aggressive compiler optimizations.
1533     ///
1534     /// # Panics
1535     ///
1536     /// This function panics if `T` is a Zero-Sized Type ("ZST").
1537     ///
1538     /// # Examples
1539     ///
1540     /// Basic usage:
1541     ///
1542     /// ```
1543     /// #![feature(ptr_offset_from)]
1544     ///
1545     /// let mut a = [0; 5];
1546     /// let ptr1: *mut i32 = &mut a[1];
1547     /// let ptr2: *mut i32 = &mut a[3];
1548     /// unsafe {
1549     ///     assert_eq!(ptr2.offset_from(ptr1), 2);
1550     ///     assert_eq!(ptr1.offset_from(ptr2), -2);
1551     ///     assert_eq!(ptr1.offset(2), ptr2);
1552     ///     assert_eq!(ptr2.offset(-2), ptr1);
1553     /// }
1554     /// ```
1555     #[unstable(feature = "ptr_offset_from", issue = "41079")]
1556     #[inline]
1557     pub unsafe fn offset_from(self, origin: *const T) -> isize where T: Sized {
1558         (self as *const T).offset_from(origin)
1559     }
1560
1561     /// Calculates the distance between two pointers. The returned value is in
1562     /// units of T: the distance in bytes is divided by `mem::size_of::<T>()`.
1563     ///
1564     /// If the address different between the two pointers is not a multiple of
1565     /// `mem::size_of::<T>()` then the result of the division is rounded towards
1566     /// zero.
1567     ///
1568     /// Though this method is safe for any two pointers, note that its result
1569     /// will be mostly useless if the two pointers aren't into the same allocated
1570     /// object, for example if they point to two different local variables.
1571     ///
1572     /// # Panics
1573     ///
1574     /// This function panics if `T` is a zero-sized type.
1575     ///
1576     /// # Examples
1577     ///
1578     /// Basic usage:
1579     ///
1580     /// ```
1581     /// #![feature(ptr_wrapping_offset_from)]
1582     ///
1583     /// let mut a = [0; 5];
1584     /// let ptr1: *mut i32 = &mut a[1];
1585     /// let ptr2: *mut i32 = &mut a[3];
1586     /// assert_eq!(ptr2.wrapping_offset_from(ptr1), 2);
1587     /// assert_eq!(ptr1.wrapping_offset_from(ptr2), -2);
1588     /// assert_eq!(ptr1.wrapping_offset(2), ptr2);
1589     /// assert_eq!(ptr2.wrapping_offset(-2), ptr1);
1590     ///
1591     /// let ptr1: *mut i32 = 3 as _;
1592     /// let ptr2: *mut i32 = 13 as _;
1593     /// assert_eq!(ptr2.wrapping_offset_from(ptr1), 2);
1594     /// ```
1595     #[unstable(feature = "ptr_wrapping_offset_from", issue = "41079")]
1596     #[inline]
1597     pub fn wrapping_offset_from(self, origin: *const T) -> isize where T: Sized {
1598         (self as *const T).wrapping_offset_from(origin)
1599     }
1600
1601     /// Calculates the offset from a pointer (convenience for `.offset(count as isize)`).
1602     ///
1603     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
1604     /// offset of `3 * size_of::<T>()` bytes.
1605     ///
1606     /// # Safety
1607     ///
1608     /// If any of the following conditions are violated, the result is Undefined
1609     /// Behavior:
1610     ///
1611     /// * Both the starting and resulting pointer must be either in bounds or one
1612     ///   byte past the end of an allocated object.
1613     ///
1614     /// * The computed offset, **in bytes**, cannot overflow an `isize`.
1615     ///
1616     /// * The offset being in bounds cannot rely on "wrapping around" the address
1617     ///   space. That is, the infinite-precision sum must fit in a `usize`.
1618     ///
1619     /// The compiler and standard library generally tries to ensure allocations
1620     /// never reach a size where an offset is a concern. For instance, `Vec`
1621     /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so
1622     /// `vec.as_ptr().add(vec.len())` is always safe.
1623     ///
1624     /// Most platforms fundamentally can't even construct such an allocation.
1625     /// For instance, no known 64-bit platform can ever serve a request
1626     /// for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
1627     /// However, some 32-bit and 16-bit platforms may successfully serve a request for
1628     /// more than `isize::MAX` bytes with things like Physical Address
1629     /// Extension. As such, memory acquired directly from allocators or memory
1630     /// mapped files *may* be too large to handle with this function.
1631     ///
1632     /// Consider using `wrapping_offset` instead if these constraints are
1633     /// difficult to satisfy. The only advantage of this method is that it
1634     /// enables more aggressive compiler optimizations.
1635     ///
1636     /// # Examples
1637     ///
1638     /// Basic usage:
1639     ///
1640     /// ```
1641     /// let s: &str = "123";
1642     /// let ptr: *const u8 = s.as_ptr();
1643     ///
1644     /// unsafe {
1645     ///     println!("{}", *ptr.add(1) as char);
1646     ///     println!("{}", *ptr.add(2) as char);
1647     /// }
1648     /// ```
1649     #[stable(feature = "pointer_methods", since = "1.26.0")]
1650     #[inline]
1651     pub unsafe fn add(self, count: usize) -> Self
1652         where T: Sized,
1653     {
1654         self.offset(count as isize)
1655     }
1656
1657     /// Calculates the offset from a pointer (convenience for
1658     /// `.offset((count as isize).wrapping_neg())`).
1659     ///
1660     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
1661     /// offset of `3 * size_of::<T>()` bytes.
1662     ///
1663     /// # Safety
1664     ///
1665     /// If any of the following conditions are violated, the result is Undefined
1666     /// Behavior:
1667     ///
1668     /// * Both the starting and resulting pointer must be either in bounds or one
1669     ///   byte past the end of an allocated object.
1670     ///
1671     /// * The computed offset cannot exceed `isize::MAX` **bytes**.
1672     ///
1673     /// * The offset being in bounds cannot rely on "wrapping around" the address
1674     ///   space. That is, the infinite-precision sum must fit in a usize.
1675     ///
1676     /// The compiler and standard library generally tries to ensure allocations
1677     /// never reach a size where an offset is a concern. For instance, `Vec`
1678     /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so
1679     /// `vec.as_ptr().add(vec.len()).sub(vec.len())` is always safe.
1680     ///
1681     /// Most platforms fundamentally can't even construct such an allocation.
1682     /// For instance, no known 64-bit platform can ever serve a request
1683     /// for 2<sup>63</sup> bytes due to page-table limitations or splitting the address space.
1684     /// However, some 32-bit and 16-bit platforms may successfully serve a request for
1685     /// more than `isize::MAX` bytes with things like Physical Address
1686     /// Extension. As such, memory acquired directly from allocators or memory
1687     /// mapped files *may* be too large to handle with this function.
1688     ///
1689     /// Consider using `wrapping_offset` instead if these constraints are
1690     /// difficult to satisfy. The only advantage of this method is that it
1691     /// enables more aggressive compiler optimizations.
1692     ///
1693     /// # Examples
1694     ///
1695     /// Basic usage:
1696     ///
1697     /// ```
1698     /// let s: &str = "123";
1699     ///
1700     /// unsafe {
1701     ///     let end: *const u8 = s.as_ptr().add(3);
1702     ///     println!("{}", *end.sub(1) as char);
1703     ///     println!("{}", *end.sub(2) as char);
1704     /// }
1705     /// ```
1706     #[stable(feature = "pointer_methods", since = "1.26.0")]
1707     #[inline]
1708     pub unsafe fn sub(self, count: usize) -> Self
1709         where T: Sized,
1710     {
1711         self.offset((count as isize).wrapping_neg())
1712     }
1713
1714     /// Calculates the offset from a pointer using wrapping arithmetic.
1715     /// (convenience for `.wrapping_offset(count as isize)`)
1716     ///
1717     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
1718     /// offset of `3 * size_of::<T>()` bytes.
1719     ///
1720     /// # Safety
1721     ///
1722     /// The resulting pointer does not need to be in bounds, but it is
1723     /// potentially hazardous to dereference (which requires `unsafe`).
1724     ///
1725     /// Always use `.add(count)` instead when possible, because `add`
1726     /// allows the compiler to optimize better.
1727     ///
1728     /// # Examples
1729     ///
1730     /// Basic usage:
1731     ///
1732     /// ```
1733     /// // Iterate using a raw pointer in increments of two elements
1734     /// let data = [1u8, 2, 3, 4, 5];
1735     /// let mut ptr: *const u8 = data.as_ptr();
1736     /// let step = 2;
1737     /// let end_rounded_up = ptr.wrapping_add(6);
1738     ///
1739     /// // This loop prints "1, 3, 5, "
1740     /// while ptr != end_rounded_up {
1741     ///     unsafe {
1742     ///         print!("{}, ", *ptr);
1743     ///     }
1744     ///     ptr = ptr.wrapping_add(step);
1745     /// }
1746     /// ```
1747     #[stable(feature = "pointer_methods", since = "1.26.0")]
1748     #[inline]
1749     pub fn wrapping_add(self, count: usize) -> Self
1750         where T: Sized,
1751     {
1752         self.wrapping_offset(count as isize)
1753     }
1754
1755     /// Calculates the offset from a pointer using wrapping arithmetic.
1756     /// (convenience for `.wrapping_offset((count as isize).wrapping_sub())`)
1757     ///
1758     /// `count` is in units of T; e.g. a `count` of 3 represents a pointer
1759     /// offset of `3 * size_of::<T>()` bytes.
1760     ///
1761     /// # Safety
1762     ///
1763     /// The resulting pointer does not need to be in bounds, but it is
1764     /// potentially hazardous to dereference (which requires `unsafe`).
1765     ///
1766     /// Always use `.sub(count)` instead when possible, because `sub`
1767     /// allows the compiler to optimize better.
1768     ///
1769     /// # Examples
1770     ///
1771     /// Basic usage:
1772     ///
1773     /// ```
1774     /// // Iterate using a raw pointer in increments of two elements (backwards)
1775     /// let data = [1u8, 2, 3, 4, 5];
1776     /// let mut ptr: *const u8 = data.as_ptr();
1777     /// let start_rounded_down = ptr.wrapping_sub(2);
1778     /// ptr = ptr.wrapping_add(4);
1779     /// let step = 2;
1780     /// // This loop prints "5, 3, 1, "
1781     /// while ptr != start_rounded_down {
1782     ///     unsafe {
1783     ///         print!("{}, ", *ptr);
1784     ///     }
1785     ///     ptr = ptr.wrapping_sub(step);
1786     /// }
1787     /// ```
1788     #[stable(feature = "pointer_methods", since = "1.26.0")]
1789     #[inline]
1790     pub fn wrapping_sub(self, count: usize) -> Self
1791         where T: Sized,
1792     {
1793         self.wrapping_offset((count as isize).wrapping_neg())
1794     }
1795
1796     /// Reads the value from `self` without moving it. This leaves the
1797     /// memory in `self` unchanged.
1798     ///
1799     /// # Safety
1800     ///
1801     /// Beyond accepting a raw pointer, this is unsafe because it semantically
1802     /// moves the value out of `self` without preventing further usage of `self`.
1803     /// If `T` is not `Copy`, then care must be taken to ensure that the value at
1804     /// `self` is not used before the data is overwritten again (e.g. with `write`,
1805     /// `write_bytes`, or `copy`). Note that `*self = foo` counts as a use
1806     /// because it will attempt to drop the value previously at `*self`.
1807     ///
1808     /// The pointer must be aligned; use `read_unaligned` if that is not the case.
1809     ///
1810     /// # Examples
1811     ///
1812     /// Basic usage:
1813     ///
1814     /// ```
1815     /// let x = 12;
1816     /// let y = &x as *const i32;
1817     ///
1818     /// unsafe {
1819     ///     assert_eq!(y.read(), 12);
1820     /// }
1821     /// ```
1822     #[stable(feature = "pointer_methods", since = "1.26.0")]
1823     #[inline]
1824     pub unsafe fn read(self) -> T
1825         where T: Sized,
1826     {
1827         read(self)
1828     }
1829
1830     /// Performs a volatile read of the value from `self` without moving it. This
1831     /// leaves the memory in `self` unchanged.
1832     ///
1833     /// Volatile operations are intended to act on I/O memory, and are guaranteed
1834     /// to not be elided or reordered by the compiler across other volatile
1835     /// operations.
1836     ///
1837     /// # Notes
1838     ///
1839     /// Rust does not currently have a rigorously and formally defined memory model,
1840     /// so the precise semantics of what "volatile" means here is subject to change
1841     /// over time. That being said, the semantics will almost always end up pretty
1842     /// similar to [C11's definition of volatile][c11].
1843     ///
1844     /// The compiler shouldn't change the relative order or number of volatile
1845     /// memory operations. However, volatile memory operations on zero-sized types
1846     /// (e.g. if a zero-sized type is passed to `read_volatile`) are no-ops
1847     /// and may be ignored.
1848     ///
1849     /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
1850     ///
1851     /// # Safety
1852     ///
1853     /// Beyond accepting a raw pointer, this is unsafe because it semantically
1854     /// moves the value out of `self` without preventing further usage of `self`.
1855     /// If `T` is not `Copy`, then care must be taken to ensure that the value at
1856     /// `self` is not used before the data is overwritten again (e.g. with `write`,
1857     /// `write_bytes`, or `copy`). Note that `*self = foo` counts as a use
1858     /// because it will attempt to drop the value previously at `*self`.
1859     ///
1860     /// # Examples
1861     ///
1862     /// Basic usage:
1863     ///
1864     /// ```
1865     /// let x = 12;
1866     /// let y = &x as *const i32;
1867     ///
1868     /// unsafe {
1869     ///     assert_eq!(y.read_volatile(), 12);
1870     /// }
1871     /// ```
1872     #[stable(feature = "pointer_methods", since = "1.26.0")]
1873     #[inline]
1874     pub unsafe fn read_volatile(self) -> T
1875         where T: Sized,
1876     {
1877         read_volatile(self)
1878     }
1879
1880     /// Reads the value from `self` without moving it. This leaves the
1881     /// memory in `self` unchanged.
1882     ///
1883     /// Unlike `read`, the pointer may be unaligned.
1884     ///
1885     /// # Safety
1886     ///
1887     /// Beyond accepting a raw pointer, this is unsafe because it semantically
1888     /// moves the value out of `self` without preventing further usage of `self`.
1889     /// If `T` is not `Copy`, then care must be taken to ensure that the value at
1890     /// `self` is not used before the data is overwritten again (e.g. with `write`,
1891     /// `write_bytes`, or `copy`). Note that `*self = foo` counts as a use
1892     /// because it will attempt to drop the value previously at `*self`.
1893     ///
1894     /// # Examples
1895     ///
1896     /// Basic usage:
1897     ///
1898     /// ```
1899     /// let x = 12;
1900     /// let y = &x as *const i32;
1901     ///
1902     /// unsafe {
1903     ///     assert_eq!(y.read_unaligned(), 12);
1904     /// }
1905     /// ```
1906     #[stable(feature = "pointer_methods", since = "1.26.0")]
1907     #[inline]
1908     pub unsafe fn read_unaligned(self) -> T
1909         where T: Sized,
1910     {
1911         read_unaligned(self)
1912     }
1913
1914     /// Copies `count * size_of<T>` bytes from `self` to `dest`. The source
1915     /// and destination may overlap.
1916     ///
1917     /// NOTE: this has the *same* argument order as `ptr::copy`.
1918     ///
1919     /// This is semantically equivalent to C's `memmove`.
1920     ///
1921     /// # Safety
1922     ///
1923     /// Care must be taken with the ownership of `self` and `dest`.
1924     /// This method semantically moves the values of `self` into `dest`.
1925     /// However it does not drop the contents of `self`, or prevent the contents
1926     /// of `dest` from being dropped or used.
1927     ///
1928     /// # Examples
1929     ///
1930     /// Efficiently create a Rust vector from an unsafe buffer:
1931     ///
1932     /// ```
1933     /// # #[allow(dead_code)]
1934     /// unsafe fn from_buf_raw<T: Copy>(ptr: *const T, elts: usize) -> Vec<T> {
1935     ///     let mut dst = Vec::with_capacity(elts);
1936     ///     dst.set_len(elts);
1937     ///     ptr.copy_to(dst.as_mut_ptr(), elts);
1938     ///     dst
1939     /// }
1940     /// ```
1941     #[stable(feature = "pointer_methods", since = "1.26.0")]
1942     #[inline]
1943     pub unsafe fn copy_to(self, dest: *mut T, count: usize)
1944         where T: Sized,
1945     {
1946         copy(self, dest, count)
1947     }
1948
1949     /// Copies `count * size_of<T>` bytes from `self` to `dest`. The source
1950     /// and destination may *not* overlap.
1951     ///
1952     /// NOTE: this has the *same* argument order as `ptr::copy_nonoverlapping`.
1953     ///
1954     /// `copy_nonoverlapping` is semantically equivalent to C's `memcpy`.
1955     ///
1956     /// # Safety
1957     ///
1958     /// Beyond requiring that the program must be allowed to access both regions
1959     /// of memory, it is Undefined Behavior for source and destination to
1960     /// overlap. Care must also be taken with the ownership of `self` and
1961     /// `self`. This method semantically moves the values of `self` into `dest`.
1962     /// However it does not drop the contents of `dest`, or prevent the contents
1963     /// of `self` from being dropped or used.
1964     ///
1965     /// # Examples
1966     ///
1967     /// Efficiently create a Rust vector from an unsafe buffer:
1968     ///
1969     /// ```
1970     /// # #[allow(dead_code)]
1971     /// unsafe fn from_buf_raw<T: Copy>(ptr: *const T, elts: usize) -> Vec<T> {
1972     ///     let mut dst = Vec::with_capacity(elts);
1973     ///     dst.set_len(elts);
1974     ///     ptr.copy_to_nonoverlapping(dst.as_mut_ptr(), elts);
1975     ///     dst
1976     /// }
1977     /// ```
1978     #[stable(feature = "pointer_methods", since = "1.26.0")]
1979     #[inline]
1980     pub unsafe fn copy_to_nonoverlapping(self, dest: *mut T, count: usize)
1981         where T: Sized,
1982     {
1983         copy_nonoverlapping(self, dest, count)
1984     }
1985
1986     /// Copies `count * size_of<T>` bytes from `src` to `self`. The source
1987     /// and destination may overlap.
1988     ///
1989     /// NOTE: this has the *opposite* argument order of `ptr::copy`.
1990     ///
1991     /// This is semantically equivalent to C's `memmove`.
1992     ///
1993     /// # Safety
1994     ///
1995     /// Care must be taken with the ownership of `src` and `self`.
1996     /// This method semantically moves the values of `src` into `self`.
1997     /// However it does not drop the contents of `self`, or prevent the contents
1998     /// of `src` from being dropped or used.
1999     ///
2000     /// # Examples
2001     ///
2002     /// Efficiently create a Rust vector from an unsafe buffer:
2003     ///
2004     /// ```
2005     /// # #[allow(dead_code)]
2006     /// unsafe fn from_buf_raw<T: Copy>(ptr: *const T, elts: usize) -> Vec<T> {
2007     ///     let mut dst: Vec<T> = Vec::with_capacity(elts);
2008     ///     dst.set_len(elts);
2009     ///     dst.as_mut_ptr().copy_from(ptr, elts);
2010     ///     dst
2011     /// }
2012     /// ```
2013     #[stable(feature = "pointer_methods", since = "1.26.0")]
2014     #[inline]
2015     pub unsafe fn copy_from(self, src: *const T, count: usize)
2016         where T: Sized,
2017     {
2018         copy(src, self, count)
2019     }
2020
2021     /// Copies `count * size_of<T>` bytes from `src` to `self`. The source
2022     /// and destination may *not* overlap.
2023     ///
2024     /// NOTE: this has the *opposite* argument order of `ptr::copy_nonoverlapping`.
2025     ///
2026     /// `copy_nonoverlapping` is semantically equivalent to C's `memcpy`.
2027     ///
2028     /// # Safety
2029     ///
2030     /// Beyond requiring that the program must be allowed to access both regions
2031     /// of memory, it is Undefined Behavior for source and destination to
2032     /// overlap. Care must also be taken with the ownership of `src` and
2033     /// `self`. This method semantically moves the values of `src` into `self`.
2034     /// However it does not drop the contents of `self`, or prevent the contents
2035     /// of `src` from being dropped or used.
2036     ///
2037     /// # Examples
2038     ///
2039     /// Efficiently create a Rust vector from an unsafe buffer:
2040     ///
2041     /// ```
2042     /// # #[allow(dead_code)]
2043     /// unsafe fn from_buf_raw<T: Copy>(ptr: *const T, elts: usize) -> Vec<T> {
2044     ///     let mut dst: Vec<T> = Vec::with_capacity(elts);
2045     ///     dst.set_len(elts);
2046     ///     dst.as_mut_ptr().copy_from_nonoverlapping(ptr, elts);
2047     ///     dst
2048     /// }
2049     /// ```
2050     #[stable(feature = "pointer_methods", since = "1.26.0")]
2051     #[inline]
2052     pub unsafe fn copy_from_nonoverlapping(self, src: *const T, count: usize)
2053         where T: Sized,
2054     {
2055         copy_nonoverlapping(src, self, count)
2056     }
2057
2058     /// Executes the destructor (if any) of the pointed-to value.
2059     ///
2060     /// This has two use cases:
2061     ///
2062     /// * It is *required* to use `drop_in_place` to drop unsized types like
2063     ///   trait objects, because they can't be read out onto the stack and
2064     ///   dropped normally.
2065     ///
2066     /// * It is friendlier to the optimizer to do this over `ptr::read` when
2067     ///   dropping manually allocated memory (e.g. when writing Box/Rc/Vec),
2068     ///   as the compiler doesn't need to prove that it's sound to elide the
2069     ///   copy.
2070     ///
2071     /// # Safety
2072     ///
2073     /// This has all the same safety problems as `ptr::read` with respect to
2074     /// invalid pointers, types, and double drops.
2075     #[stable(feature = "pointer_methods", since = "1.26.0")]
2076     #[inline]
2077     pub unsafe fn drop_in_place(self) {
2078         drop_in_place(self)
2079     }
2080
2081     /// Overwrites a memory location with the given value without reading or
2082     /// dropping the old value.
2083     ///
2084     /// # Safety
2085     ///
2086     /// This operation is marked unsafe because it writes through a raw pointer.
2087     ///
2088     /// It does not drop the contents of `self`. This is safe, but it could leak
2089     /// allocations or resources, so care must be taken not to overwrite an object
2090     /// that should be dropped.
2091     ///
2092     /// Additionally, it does not drop `val`. Semantically, `val` is moved into the
2093     /// location pointed to by `self`.
2094     ///
2095     /// This is appropriate for initializing uninitialized memory, or overwriting
2096     /// memory that has previously been `read` from.
2097     ///
2098     /// The pointer must be aligned; use `write_unaligned` if that is not the case.
2099     ///
2100     /// # Examples
2101     ///
2102     /// Basic usage:
2103     ///
2104     /// ```
2105     /// let mut x = 0;
2106     /// let y = &mut x as *mut i32;
2107     /// let z = 12;
2108     ///
2109     /// unsafe {
2110     ///     y.write(z);
2111     ///     assert_eq!(y.read(), 12);
2112     /// }
2113     /// ```
2114     #[stable(feature = "pointer_methods", since = "1.26.0")]
2115     #[inline]
2116     pub unsafe fn write(self, val: T)
2117         where T: Sized,
2118     {
2119         write(self, val)
2120     }
2121
2122     /// Invokes memset on the specified pointer, setting `count * size_of::<T>()`
2123     /// bytes of memory starting at `self` to `val`.
2124     ///
2125     /// # Examples
2126     ///
2127     /// ```
2128     /// let mut vec = vec![0; 4];
2129     /// unsafe {
2130     ///     let vec_ptr = vec.as_mut_ptr();
2131     ///     vec_ptr.write_bytes(b'a', 2);
2132     /// }
2133     /// assert_eq!(vec, [b'a', b'a', 0, 0]);
2134     /// ```
2135     #[stable(feature = "pointer_methods", since = "1.26.0")]
2136     #[inline]
2137     pub unsafe fn write_bytes(self, val: u8, count: usize)
2138         where T: Sized,
2139     {
2140         write_bytes(self, val, count)
2141     }
2142
2143     /// Performs a volatile write of a memory location with the given value without
2144     /// reading or dropping the old value.
2145     ///
2146     /// Volatile operations are intended to act on I/O memory, and are guaranteed
2147     /// to not be elided or reordered by the compiler across other volatile
2148     /// operations.
2149     ///
2150     /// # Notes
2151     ///
2152     /// Rust does not currently have a rigorously and formally defined memory model,
2153     /// so the precise semantics of what "volatile" means here is subject to change
2154     /// over time. That being said, the semantics will almost always end up pretty
2155     /// similar to [C11's definition of volatile][c11].
2156     ///
2157     /// The compiler shouldn't change the relative order or number of volatile
2158     /// memory operations. However, volatile memory operations on zero-sized types
2159     /// (e.g. if a zero-sized type is passed to `write_volatile`) are no-ops
2160     /// and may be ignored.
2161     ///
2162     /// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf
2163     ///
2164     /// # Safety
2165     ///
2166     /// This operation is marked unsafe because it accepts a raw pointer.
2167     ///
2168     /// It does not drop the contents of `self`. This is safe, but it could leak
2169     /// allocations or resources, so care must be taken not to overwrite an object
2170     /// that should be dropped.
2171     ///
2172     /// This is appropriate for initializing uninitialized memory, or overwriting
2173     /// memory that has previously been `read` from.
2174     ///
2175     /// # Examples
2176     ///
2177     /// Basic usage:
2178     ///
2179     /// ```
2180     /// let mut x = 0;
2181     /// let y = &mut x as *mut i32;
2182     /// let z = 12;
2183     ///
2184     /// unsafe {
2185     ///     y.write_volatile(z);
2186     ///     assert_eq!(y.read_volatile(), 12);
2187     /// }
2188     /// ```
2189     #[stable(feature = "pointer_methods", since = "1.26.0")]
2190     #[inline]
2191     pub unsafe fn write_volatile(self, val: T)
2192         where T: Sized,
2193     {
2194         write_volatile(self, val)
2195     }
2196
2197     /// Overwrites a memory location with the given value without reading or
2198     /// dropping the old value.
2199     ///
2200     /// Unlike `write`, the pointer may be unaligned.
2201     ///
2202     /// # Safety
2203     ///
2204     /// This operation is marked unsafe because it writes through a raw pointer.
2205     ///
2206     /// It does not drop the contents of `self`. This is safe, but it could leak
2207     /// allocations or resources, so care must be taken not to overwrite an object
2208     /// that should be dropped.
2209     ///
2210     /// Additionally, it does not drop `self`. Semantically, `self` is moved into the
2211     /// location pointed to by `val`.
2212     ///
2213     /// This is appropriate for initializing uninitialized memory, or overwriting
2214     /// memory that has previously been `read` from.
2215     ///
2216     /// # Examples
2217     ///
2218     /// Basic usage:
2219     ///
2220     /// ```
2221     /// let mut x = 0;
2222     /// let y = &mut x as *mut i32;
2223     /// let z = 12;
2224     ///
2225     /// unsafe {
2226     ///     y.write_unaligned(z);
2227     ///     assert_eq!(y.read_unaligned(), 12);
2228     /// }
2229     /// ```
2230     #[stable(feature = "pointer_methods", since = "1.26.0")]
2231     #[inline]
2232     pub unsafe fn write_unaligned(self, val: T)
2233         where T: Sized,
2234     {
2235         write_unaligned(self, val)
2236     }
2237
2238     /// Replaces the value at `self` with `src`, returning the old
2239     /// value, without dropping either.
2240     ///
2241     /// # Safety
2242     ///
2243     /// This is only unsafe because it accepts a raw pointer.
2244     /// Otherwise, this operation is identical to `mem::replace`.
2245     #[stable(feature = "pointer_methods", since = "1.26.0")]
2246     #[inline]
2247     pub unsafe fn replace(self, src: T) -> T
2248         where T: Sized,
2249     {
2250         replace(self, src)
2251     }
2252
2253     /// Swaps the values at two mutable locations of the same type, without
2254     /// deinitializing either. They may overlap, unlike `mem::swap` which is
2255     /// otherwise equivalent.
2256     ///
2257     /// # Safety
2258     ///
2259     /// This function copies the memory through the raw pointers passed to it
2260     /// as arguments.
2261     ///
2262     /// Ensure that these pointers are valid before calling `swap`.
2263     #[stable(feature = "pointer_methods", since = "1.26.0")]
2264     #[inline]
2265     pub unsafe fn swap(self, with: *mut T)
2266         where T: Sized,
2267     {
2268         swap(self, with)
2269     }
2270
2271     /// Computes the offset that needs to be applied to the pointer in order to make it aligned to
2272     /// `align`.
2273     ///
2274     /// If it is not possible to align the pointer, the implementation returns
2275     /// `usize::max_value()`.
2276     ///
2277     /// The offset is expressed in number of `T` elements, and not bytes. The value returned can be
2278     /// used with the `offset` or `offset_to` methods.
2279     ///
2280     /// There are no guarantees whatsover that offsetting the pointer will not overflow or go
2281     /// beyond the allocation that the pointer points into. It is up to the caller to ensure that
2282     /// the returned offset is correct in all terms other than alignment.
2283     ///
2284     /// # Panics
2285     ///
2286     /// The function panics if `align` is not a power-of-two.
2287     ///
2288     /// # Examples
2289     ///
2290     /// Accessing adjacent `u8` as `u16`
2291     ///
2292     /// ```
2293     /// # #![feature(align_offset)]
2294     /// # fn foo(n: usize) {
2295     /// # use std::mem::align_of;
2296     /// # unsafe {
2297     /// let x = [5u8, 6u8, 7u8, 8u8, 9u8];
2298     /// let ptr = &x[n] as *const u8;
2299     /// let offset = ptr.align_offset(align_of::<u16>());
2300     /// if offset < x.len() - n - 1 {
2301     ///     let u16_ptr = ptr.offset(offset as isize) as *const u16;
2302     ///     assert_ne!(*u16_ptr, 500);
2303     /// } else {
2304     ///     // while the pointer can be aligned via `offset`, it would point
2305     ///     // outside the allocation
2306     /// }
2307     /// # } }
2308     /// ```
2309     #[unstable(feature = "align_offset", issue = "44488")]
2310     #[cfg(not(stage0))]
2311     pub fn align_offset(self, align: usize) -> usize where T: Sized {
2312         if !align.is_power_of_two() {
2313             panic!("align_offset: align is not a power-of-two");
2314         }
2315         unsafe {
2316             align_offset(self, align)
2317         }
2318     }
2319
2320     /// definitely docs.
2321     #[unstable(feature = "align_offset", issue = "44488")]
2322     #[cfg(stage0)]
2323     pub fn align_offset(self, align: usize) -> usize where T: Sized {
2324         if !align.is_power_of_two() {
2325             panic!("align_offset: align is not a power-of-two");
2326         }
2327         unsafe {
2328             intrinsics::align_offset(self as *const (), align)
2329         }
2330     }
2331 }
2332
2333 /// Align pointer `p`.
2334 ///
2335 /// Calculate offset (in terms of elements of `stride` stride) that has to be applied
2336 /// to pointer `p` so that pointer `p` would get aligned to `a`.
2337 ///
2338 /// Note: This implementation has been carefully tailored to not panic. It is UB for this to panic.
2339 /// The only real change that can be made here is change of `INV_TABLE_MOD_16` and associated
2340 /// constants.
2341 ///
2342 /// If we ever decide to make it possible to call the intrinsic with `a` that is not a
2343 /// power-of-two, it will probably be more prudent to just change to a naive implementation rather
2344 /// than trying to adapt this to accomodate that change.
2345 ///
2346 /// Any questions go to @nagisa.
2347 #[lang="align_offset"]
2348 #[cfg(not(stage0))]
2349 pub(crate) unsafe fn align_offset<T: Sized>(p: *const T, a: usize) -> usize {
2350     /// Calculate multiplicative modular inverse of `x` modulo `m`.
2351     ///
2352     /// This implementation is tailored for align_offset and has following preconditions:
2353     ///
2354     /// * `m` is a power-of-two;
2355     /// * `x < m`; (if `x ≥ m`, pass in `x % m` instead)
2356     ///
2357     /// Implementation of this function shall not panic. Ever.
2358     #[inline]
2359     fn mod_inv(x: usize, m: usize) -> usize {
2360         /// Multiplicative modular inverse table modulo 2⁴ = 16.
2361         ///
2362         /// Note, that this table does not contain values where inverse does not exist (i.e. for
2363         /// `0⁻¹ mod 16`, `2⁻¹ mod 16`, etc.)
2364         const INV_TABLE_MOD_16: [usize; 8] = [1, 11, 13, 7, 9, 3, 5, 15];
2365         /// Modulo for which the `INV_TABLE_MOD_16` is intended.
2366         const INV_TABLE_MOD: usize = 16;
2367         /// INV_TABLE_MOD²
2368         const INV_TABLE_MOD_SQUARED: usize = INV_TABLE_MOD * INV_TABLE_MOD;
2369
2370         let table_inverse = INV_TABLE_MOD_16[(x & (INV_TABLE_MOD - 1)) >> 1];
2371         if m <= INV_TABLE_MOD {
2372             return table_inverse & (m - 1);
2373         } else {
2374             // We iterate "up" using the following formula:
2375             //
2376             // $$ xy ≡ 1 (mod 2ⁿ) → xy (2 - xy) ≡ 1 (mod 2²ⁿ) $$
2377             //
2378             // until 2²ⁿ ≥ m. Then we can reduce to our desired `m` by taking the result `mod m`.
2379             let mut inverse = table_inverse;
2380             let mut going_mod = INV_TABLE_MOD_SQUARED;
2381             loop {
2382                 // y = y * (2 - xy) mod n
2383                 //
2384                 // Note, that we use wrapping operations here intentionally – the original formula
2385                 // uses e.g. subtraction `mod n`. It is entirely fine to do them `mod
2386                 // usize::max_value()` instead, because we take the result `mod n` at the end
2387                 // anyway.
2388                 inverse = inverse.wrapping_mul(
2389                     2usize.wrapping_sub(x.wrapping_mul(inverse))
2390                 ) & (going_mod - 1);
2391                 if going_mod > m {
2392                     return inverse & (m - 1);
2393                 }
2394                 going_mod = going_mod.wrapping_mul(going_mod);
2395             }
2396         }
2397     }
2398
2399     let stride = ::mem::size_of::<T>();
2400     let a_minus_one = a.wrapping_sub(1);
2401     let pmoda = p as usize & a_minus_one;
2402
2403     if pmoda == 0 {
2404         // Already aligned. Yay!
2405         return 0;
2406     }
2407
2408     if stride <= 1 {
2409         return if stride == 0 {
2410             // If the pointer is not aligned, and the element is zero-sized, then no amount of
2411             // elements will ever align the pointer.
2412             !0
2413         } else {
2414             a.wrapping_sub(pmoda)
2415         };
2416     }
2417
2418     let smoda = stride & a_minus_one;
2419     // a is power-of-two so cannot be 0. stride = 0 is handled above.
2420     let gcdpow = intrinsics::cttz_nonzero(stride).min(intrinsics::cttz_nonzero(a));
2421     let gcd = 1usize << gcdpow;
2422
2423     if gcd == 1 {
2424         // This branch solves for the variable $o$ in following linear congruence equation:
2425         //
2426         // ⎰ p + o ≡ 0 (mod a)   # $p + o$ must be aligned to specified alignment $a$
2427         // ⎱     o ≡ 0 (mod s)   # offset $o$ must be a multiple of stride $s$
2428         //
2429         // where
2430         //
2431         // * a, s are co-prime
2432         //
2433         // This gives us the formula below:
2434         //
2435         // o = (a - (p mod a)) * (s⁻¹ mod a) * s
2436         //
2437         // The first term is “the relative alignment of p to a”, the second term is “how does
2438         // incrementing p by one s change the relative alignment of p”, the third term is
2439         // translating change in units of s to a byte count.
2440         //
2441         // Furthermore, the result produced by this solution is not “minimal”, so it is necessary
2442         // to take the result $o mod lcm(s, a)$. Since $s$ and $a$ are co-prime (i.e. $gcd(s, a) =
2443         // 1$) and $lcm(s, a) = s * a / gcd(s, a)$, we can replace $lcm(s, a)$ with just a $s * a$.
2444         //
2445         // (Author note: we decided later on to express the offset in "elements" rather than bytes,
2446         // which drops the multiplication by `s` on both sides of the modulo.)
2447         return intrinsics::unchecked_rem(a.wrapping_sub(pmoda).wrapping_mul(mod_inv(smoda, a)), a);
2448     }
2449
2450     if p as usize & (gcd - 1) == 0 {
2451         // This can be aligned, but `a` and `stride` are not co-prime, so a somewhat adapted
2452         // formula is used.
2453         let j = a.wrapping_sub(pmoda) >> gcdpow;
2454         let k = smoda >> gcdpow;
2455         return intrinsics::unchecked_rem(j.wrapping_mul(mod_inv(k, a)), a >> gcdpow);
2456     }
2457
2458     // Cannot be aligned at all.
2459     return usize::max_value();
2460 }
2461
2462
2463
2464 // Equality for pointers
2465 #[stable(feature = "rust1", since = "1.0.0")]
2466 impl<T: ?Sized> PartialEq for *const T {
2467     #[inline]
2468     fn eq(&self, other: &*const T) -> bool { *self == *other }
2469 }
2470
2471 #[stable(feature = "rust1", since = "1.0.0")]
2472 impl<T: ?Sized> Eq for *const T {}
2473
2474 #[stable(feature = "rust1", since = "1.0.0")]
2475 impl<T: ?Sized> PartialEq for *mut T {
2476     #[inline]
2477     fn eq(&self, other: &*mut T) -> bool { *self == *other }
2478 }
2479
2480 #[stable(feature = "rust1", since = "1.0.0")]
2481 impl<T: ?Sized> Eq for *mut T {}
2482
2483 /// Compare raw pointers for equality.
2484 ///
2485 /// This is the same as using the `==` operator, but less generic:
2486 /// the arguments have to be `*const T` raw pointers,
2487 /// not anything that implements `PartialEq`.
2488 ///
2489 /// This can be used to compare `&T` references (which coerce to `*const T` implicitly)
2490 /// by their address rather than comparing the values they point to
2491 /// (which is what the `PartialEq for &T` implementation does).
2492 ///
2493 /// # Examples
2494 ///
2495 /// ```
2496 /// use std::ptr;
2497 ///
2498 /// let five = 5;
2499 /// let other_five = 5;
2500 /// let five_ref = &five;
2501 /// let same_five_ref = &five;
2502 /// let other_five_ref = &other_five;
2503 ///
2504 /// assert!(five_ref == same_five_ref);
2505 /// assert!(five_ref == other_five_ref);
2506 ///
2507 /// assert!(ptr::eq(five_ref, same_five_ref));
2508 /// assert!(!ptr::eq(five_ref, other_five_ref));
2509 /// ```
2510 #[stable(feature = "ptr_eq", since = "1.17.0")]
2511 #[inline]
2512 pub fn eq<T: ?Sized>(a: *const T, b: *const T) -> bool {
2513     a == b
2514 }
2515
2516 // Impls for function pointers
2517 macro_rules! fnptr_impls_safety_abi {
2518     ($FnTy: ty, $($Arg: ident),*) => {
2519         #[stable(feature = "fnptr_impls", since = "1.4.0")]
2520         impl<Ret, $($Arg),*> PartialEq for $FnTy {
2521             #[inline]
2522             fn eq(&self, other: &Self) -> bool {
2523                 *self as usize == *other as usize
2524             }
2525         }
2526
2527         #[stable(feature = "fnptr_impls", since = "1.4.0")]
2528         impl<Ret, $($Arg),*> Eq for $FnTy {}
2529
2530         #[stable(feature = "fnptr_impls", since = "1.4.0")]
2531         impl<Ret, $($Arg),*> PartialOrd for $FnTy {
2532             #[inline]
2533             fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
2534                 (*self as usize).partial_cmp(&(*other as usize))
2535             }
2536         }
2537
2538         #[stable(feature = "fnptr_impls", since = "1.4.0")]
2539         impl<Ret, $($Arg),*> Ord for $FnTy {
2540             #[inline]
2541             fn cmp(&self, other: &Self) -> Ordering {
2542                 (*self as usize).cmp(&(*other as usize))
2543             }
2544         }
2545
2546         #[stable(feature = "fnptr_impls", since = "1.4.0")]
2547         impl<Ret, $($Arg),*> hash::Hash for $FnTy {
2548             fn hash<HH: hash::Hasher>(&self, state: &mut HH) {
2549                 state.write_usize(*self as usize)
2550             }
2551         }
2552
2553         #[stable(feature = "fnptr_impls", since = "1.4.0")]
2554         impl<Ret, $($Arg),*> fmt::Pointer for $FnTy {
2555             fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2556                 fmt::Pointer::fmt(&(*self as *const ()), f)
2557             }
2558         }
2559
2560         #[stable(feature = "fnptr_impls", since = "1.4.0")]
2561         impl<Ret, $($Arg),*> fmt::Debug for $FnTy {
2562             fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2563                 fmt::Pointer::fmt(&(*self as *const ()), f)
2564             }
2565         }
2566     }
2567 }
2568
2569 macro_rules! fnptr_impls_args {
2570     ($($Arg: ident),+) => {
2571         fnptr_impls_safety_abi! { extern "Rust" fn($($Arg),*) -> Ret, $($Arg),* }
2572         fnptr_impls_safety_abi! { extern "C" fn($($Arg),*) -> Ret, $($Arg),* }
2573         fnptr_impls_safety_abi! { extern "C" fn($($Arg),* , ...) -> Ret, $($Arg),* }
2574         fnptr_impls_safety_abi! { unsafe extern "Rust" fn($($Arg),*) -> Ret, $($Arg),* }
2575         fnptr_impls_safety_abi! { unsafe extern "C" fn($($Arg),*) -> Ret, $($Arg),* }
2576         fnptr_impls_safety_abi! { unsafe extern "C" fn($($Arg),* , ...) -> Ret, $($Arg),* }
2577     };
2578     () => {
2579         // No variadic functions with 0 parameters
2580         fnptr_impls_safety_abi! { extern "Rust" fn() -> Ret, }
2581         fnptr_impls_safety_abi! { extern "C" fn() -> Ret, }
2582         fnptr_impls_safety_abi! { unsafe extern "Rust" fn() -> Ret, }
2583         fnptr_impls_safety_abi! { unsafe extern "C" fn() -> Ret, }
2584     };
2585 }
2586
2587 fnptr_impls_args! { }
2588 fnptr_impls_args! { A }
2589 fnptr_impls_args! { A, B }
2590 fnptr_impls_args! { A, B, C }
2591 fnptr_impls_args! { A, B, C, D }
2592 fnptr_impls_args! { A, B, C, D, E }
2593 fnptr_impls_args! { A, B, C, D, E, F }
2594 fnptr_impls_args! { A, B, C, D, E, F, G }
2595 fnptr_impls_args! { A, B, C, D, E, F, G, H }
2596 fnptr_impls_args! { A, B, C, D, E, F, G, H, I }
2597 fnptr_impls_args! { A, B, C, D, E, F, G, H, I, J }
2598 fnptr_impls_args! { A, B, C, D, E, F, G, H, I, J, K }
2599 fnptr_impls_args! { A, B, C, D, E, F, G, H, I, J, K, L }
2600
2601 // Comparison for pointers
2602 #[stable(feature = "rust1", since = "1.0.0")]
2603 impl<T: ?Sized> Ord for *const T {
2604     #[inline]
2605     fn cmp(&self, other: &*const T) -> Ordering {
2606         if self < other {
2607             Less
2608         } else if self == other {
2609             Equal
2610         } else {
2611             Greater
2612         }
2613     }
2614 }
2615
2616 #[stable(feature = "rust1", since = "1.0.0")]
2617 impl<T: ?Sized> PartialOrd for *const T {
2618     #[inline]
2619     fn partial_cmp(&self, other: &*const T) -> Option<Ordering> {
2620         Some(self.cmp(other))
2621     }
2622
2623     #[inline]
2624     fn lt(&self, other: &*const T) -> bool { *self < *other }
2625
2626     #[inline]
2627     fn le(&self, other: &*const T) -> bool { *self <= *other }
2628
2629     #[inline]
2630     fn gt(&self, other: &*const T) -> bool { *self > *other }
2631
2632     #[inline]
2633     fn ge(&self, other: &*const T) -> bool { *self >= *other }
2634 }
2635
2636 #[stable(feature = "rust1", since = "1.0.0")]
2637 impl<T: ?Sized> Ord for *mut T {
2638     #[inline]
2639     fn cmp(&self, other: &*mut T) -> Ordering {
2640         if self < other {
2641             Less
2642         } else if self == other {
2643             Equal
2644         } else {
2645             Greater
2646         }
2647     }
2648 }
2649
2650 #[stable(feature = "rust1", since = "1.0.0")]
2651 impl<T: ?Sized> PartialOrd for *mut T {
2652     #[inline]
2653     fn partial_cmp(&self, other: &*mut T) -> Option<Ordering> {
2654         Some(self.cmp(other))
2655     }
2656
2657     #[inline]
2658     fn lt(&self, other: &*mut T) -> bool { *self < *other }
2659
2660     #[inline]
2661     fn le(&self, other: &*mut T) -> bool { *self <= *other }
2662
2663     #[inline]
2664     fn gt(&self, other: &*mut T) -> bool { *self > *other }
2665
2666     #[inline]
2667     fn ge(&self, other: &*mut T) -> bool { *self >= *other }
2668 }
2669
2670 /// A wrapper around a raw non-null `*mut T` that indicates that the possessor
2671 /// of this wrapper owns the referent. Useful for building abstractions like
2672 /// `Box<T>`, `Vec<T>`, `String`, and `HashMap<K, V>`.
2673 ///
2674 /// Unlike `*mut T`, `Unique<T>` behaves "as if" it were an instance of `T`.
2675 /// It implements `Send`/`Sync` if `T` is `Send`/`Sync`. It also implies
2676 /// the kind of strong aliasing guarantees an instance of `T` can expect:
2677 /// the referent of the pointer should not be modified without a unique path to
2678 /// its owning Unique.
2679 ///
2680 /// If you're uncertain of whether it's correct to use `Unique` for your purposes,
2681 /// consider using `NonNull`, which has weaker semantics.
2682 ///
2683 /// Unlike `*mut T`, the pointer must always be non-null, even if the pointer
2684 /// is never dereferenced. This is so that enums may use this forbidden value
2685 /// as a discriminant -- `Option<Unique<T>>` has the same size as `Unique<T>`.
2686 /// However the pointer may still dangle if it isn't dereferenced.
2687 ///
2688 /// Unlike `*mut T`, `Unique<T>` is covariant over `T`. This should always be correct
2689 /// for any type which upholds Unique's aliasing requirements.
2690 #[unstable(feature = "ptr_internals", issue = "0",
2691            reason = "use NonNull instead and consider PhantomData<T> \
2692                      (if you also use #[may_dangle]), Send, and/or Sync")]
2693 #[doc(hidden)]
2694 pub struct Unique<T: ?Sized> {
2695     pointer: NonZero<*const T>,
2696     // NOTE: this marker has no consequences for variance, but is necessary
2697     // for dropck to understand that we logically own a `T`.
2698     //
2699     // For details, see:
2700     // https://github.com/rust-lang/rfcs/blob/master/text/0769-sound-generic-drop.md#phantom-data
2701     _marker: PhantomData<T>,
2702 }
2703
2704 #[unstable(feature = "ptr_internals", issue = "0")]
2705 impl<T: ?Sized> fmt::Debug for Unique<T> {
2706     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2707         fmt::Pointer::fmt(&self.as_ptr(), f)
2708     }
2709 }
2710
2711 /// `Unique` pointers are `Send` if `T` is `Send` because the data they
2712 /// reference is unaliased. Note that this aliasing invariant is
2713 /// unenforced by the type system; the abstraction using the
2714 /// `Unique` must enforce it.
2715 #[unstable(feature = "ptr_internals", issue = "0")]
2716 unsafe impl<T: Send + ?Sized> Send for Unique<T> { }
2717
2718 /// `Unique` pointers are `Sync` if `T` is `Sync` because the data they
2719 /// reference is unaliased. Note that this aliasing invariant is
2720 /// unenforced by the type system; the abstraction using the
2721 /// `Unique` must enforce it.
2722 #[unstable(feature = "ptr_internals", issue = "0")]
2723 unsafe impl<T: Sync + ?Sized> Sync for Unique<T> { }
2724
2725 #[unstable(feature = "ptr_internals", issue = "0")]
2726 impl<T: Sized> Unique<T> {
2727     /// Creates a new `Unique` that is dangling, but well-aligned.
2728     ///
2729     /// This is useful for initializing types which lazily allocate, like
2730     /// `Vec::new` does.
2731     // FIXME: rename to dangling() to match NonNull?
2732     pub const fn empty() -> Self {
2733         unsafe {
2734             Unique::new_unchecked(mem::align_of::<T>() as *mut T)
2735         }
2736     }
2737 }
2738
2739 #[unstable(feature = "ptr_internals", issue = "0")]
2740 impl<T: ?Sized> Unique<T> {
2741     /// Creates a new `Unique`.
2742     ///
2743     /// # Safety
2744     ///
2745     /// `ptr` must be non-null.
2746     pub const unsafe fn new_unchecked(ptr: *mut T) -> Self {
2747         Unique { pointer: NonZero(ptr as _), _marker: PhantomData }
2748     }
2749
2750     /// Creates a new `Unique` if `ptr` is non-null.
2751     pub fn new(ptr: *mut T) -> Option<Self> {
2752         if !ptr.is_null() {
2753             Some(Unique { pointer: NonZero(ptr as _), _marker: PhantomData })
2754         } else {
2755             None
2756         }
2757     }
2758
2759     /// Acquires the underlying `*mut` pointer.
2760     pub fn as_ptr(self) -> *mut T {
2761         self.pointer.0 as *mut T
2762     }
2763
2764     /// Dereferences the content.
2765     ///
2766     /// The resulting lifetime is bound to self so this behaves "as if"
2767     /// it were actually an instance of T that is getting borrowed. If a longer
2768     /// (unbound) lifetime is needed, use `&*my_ptr.as_ptr()`.
2769     pub unsafe fn as_ref(&self) -> &T {
2770         &*self.as_ptr()
2771     }
2772
2773     /// Mutably dereferences the content.
2774     ///
2775     /// The resulting lifetime is bound to self so this behaves "as if"
2776     /// it were actually an instance of T that is getting borrowed. If a longer
2777     /// (unbound) lifetime is needed, use `&mut *my_ptr.as_ptr()`.
2778     pub unsafe fn as_mut(&mut self) -> &mut T {
2779         &mut *self.as_ptr()
2780     }
2781 }
2782
2783 #[unstable(feature = "ptr_internals", issue = "0")]
2784 impl<T: ?Sized> Clone for Unique<T> {
2785     fn clone(&self) -> Self {
2786         *self
2787     }
2788 }
2789
2790 #[unstable(feature = "ptr_internals", issue = "0")]
2791 impl<T: ?Sized> Copy for Unique<T> { }
2792
2793 #[unstable(feature = "ptr_internals", issue = "0")]
2794 impl<T: ?Sized, U: ?Sized> CoerceUnsized<Unique<U>> for Unique<T> where T: Unsize<U> { }
2795
2796 #[unstable(feature = "ptr_internals", issue = "0")]
2797 impl<T: ?Sized> fmt::Pointer for Unique<T> {
2798     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2799         fmt::Pointer::fmt(&self.as_ptr(), f)
2800     }
2801 }
2802
2803 #[unstable(feature = "ptr_internals", issue = "0")]
2804 impl<'a, T: ?Sized> From<&'a mut T> for Unique<T> {
2805     fn from(reference: &'a mut T) -> Self {
2806         Unique { pointer: NonZero(reference as _), _marker: PhantomData }
2807     }
2808 }
2809
2810 #[unstable(feature = "ptr_internals", issue = "0")]
2811 impl<'a, T: ?Sized> From<&'a T> for Unique<T> {
2812     fn from(reference: &'a T) -> Self {
2813         Unique { pointer: NonZero(reference as _), _marker: PhantomData }
2814     }
2815 }
2816
2817 #[unstable(feature = "ptr_internals", issue = "0")]
2818 impl<'a, T: ?Sized> From<NonNull<T>> for Unique<T> {
2819     fn from(p: NonNull<T>) -> Self {
2820         Unique { pointer: p.pointer, _marker: PhantomData }
2821     }
2822 }
2823
2824 /// `*mut T` but non-zero and covariant.
2825 ///
2826 /// This is often the correct thing to use when building data structures using
2827 /// raw pointers, but is ultimately more dangerous to use because of its additional
2828 /// properties. If you're not sure if you should use `NonNull<T>`, just use `*mut T`!
2829 ///
2830 /// Unlike `*mut T`, the pointer must always be non-null, even if the pointer
2831 /// is never dereferenced. This is so that enums may use this forbidden value
2832 /// as a discriminant -- `Option<NonNull<T>>` has the same size as `*mut T`.
2833 /// However the pointer may still dangle if it isn't dereferenced.
2834 ///
2835 /// Unlike `*mut T`, `NonNull<T>` is covariant over `T`. If this is incorrect
2836 /// for your use case, you should include some PhantomData in your type to
2837 /// provide invariance, such as `PhantomData<Cell<T>>` or `PhantomData<&'a mut T>`.
2838 /// Usually this won't be necessary; covariance is correct for most safe abstractions,
2839 /// such as Box, Rc, Arc, Vec, and LinkedList. This is the case because they
2840 /// provide a public API that follows the normal shared XOR mutable rules of Rust.
2841 #[stable(feature = "nonnull", since = "1.25.0")]
2842 pub struct NonNull<T: ?Sized> {
2843     pointer: NonZero<*const T>,
2844 }
2845
2846 /// `NonNull` pointers are not `Send` because the data they reference may be aliased.
2847 // NB: This impl is unnecessary, but should provide better error messages.
2848 #[stable(feature = "nonnull", since = "1.25.0")]
2849 impl<T: ?Sized> !Send for NonNull<T> { }
2850
2851 /// `NonNull` pointers are not `Sync` because the data they reference may be aliased.
2852 // NB: This impl is unnecessary, but should provide better error messages.
2853 #[stable(feature = "nonnull", since = "1.25.0")]
2854 impl<T: ?Sized> !Sync for NonNull<T> { }
2855
2856 impl<T: Sized> NonNull<T> {
2857     /// Creates a new `NonNull` that is dangling, but well-aligned.
2858     ///
2859     /// This is useful for initializing types which lazily allocate, like
2860     /// `Vec::new` does.
2861     #[stable(feature = "nonnull", since = "1.25.0")]
2862     pub fn dangling() -> Self {
2863         unsafe {
2864             let ptr = mem::align_of::<T>() as *mut T;
2865             NonNull::new_unchecked(ptr)
2866         }
2867     }
2868 }
2869
2870 impl<T: ?Sized> NonNull<T> {
2871     /// Creates a new `NonNull`.
2872     ///
2873     /// # Safety
2874     ///
2875     /// `ptr` must be non-null.
2876     #[stable(feature = "nonnull", since = "1.25.0")]
2877     pub const unsafe fn new_unchecked(ptr: *mut T) -> Self {
2878         NonNull { pointer: NonZero(ptr as _) }
2879     }
2880
2881     /// Creates a new `NonNull` if `ptr` is non-null.
2882     #[stable(feature = "nonnull", since = "1.25.0")]
2883     pub fn new(ptr: *mut T) -> Option<Self> {
2884         if !ptr.is_null() {
2885             Some(NonNull { pointer: NonZero(ptr as _) })
2886         } else {
2887             None
2888         }
2889     }
2890
2891     /// Acquires the underlying `*mut` pointer.
2892     #[stable(feature = "nonnull", since = "1.25.0")]
2893     pub fn as_ptr(self) -> *mut T {
2894         self.pointer.0 as *mut T
2895     }
2896
2897     /// Dereferences the content.
2898     ///
2899     /// The resulting lifetime is bound to self so this behaves "as if"
2900     /// it were actually an instance of T that is getting borrowed. If a longer
2901     /// (unbound) lifetime is needed, use `&*my_ptr.as_ptr()`.
2902     #[stable(feature = "nonnull", since = "1.25.0")]
2903     pub unsafe fn as_ref(&self) -> &T {
2904         &*self.as_ptr()
2905     }
2906
2907     /// Mutably dereferences the content.
2908     ///
2909     /// The resulting lifetime is bound to self so this behaves "as if"
2910     /// it were actually an instance of T that is getting borrowed. If a longer
2911     /// (unbound) lifetime is needed, use `&mut *my_ptr.as_ptr()`.
2912     #[stable(feature = "nonnull", since = "1.25.0")]
2913     pub unsafe fn as_mut(&mut self) -> &mut T {
2914         &mut *self.as_ptr()
2915     }
2916
2917     /// Cast to a pointer of another type
2918     #[stable(feature = "nonnull_cast", since = "1.27.0")]
2919     pub fn cast<U>(self) -> NonNull<U> {
2920         unsafe {
2921             NonNull::new_unchecked(self.as_ptr() as *mut U)
2922         }
2923     }
2924
2925     /// Cast to an `Opaque` pointer
2926     #[unstable(feature = "allocator_api", issue = "32838")]
2927     pub fn as_opaque(self) -> NonNull<::alloc::Opaque> {
2928         unsafe {
2929             NonNull::new_unchecked(self.as_ptr() as _)
2930         }
2931     }
2932 }
2933
2934 #[stable(feature = "nonnull", since = "1.25.0")]
2935 impl<T: ?Sized> Clone for NonNull<T> {
2936     fn clone(&self) -> Self {
2937         *self
2938     }
2939 }
2940
2941 #[stable(feature = "nonnull", since = "1.25.0")]
2942 impl<T: ?Sized> Copy for NonNull<T> { }
2943
2944 #[unstable(feature = "coerce_unsized", issue = "27732")]
2945 impl<T: ?Sized, U: ?Sized> CoerceUnsized<NonNull<U>> for NonNull<T> where T: Unsize<U> { }
2946
2947 #[stable(feature = "nonnull", since = "1.25.0")]
2948 impl<T: ?Sized> fmt::Debug for NonNull<T> {
2949     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2950         fmt::Pointer::fmt(&self.as_ptr(), f)
2951     }
2952 }
2953
2954 #[stable(feature = "nonnull", since = "1.25.0")]
2955 impl<T: ?Sized> fmt::Pointer for NonNull<T> {
2956     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
2957         fmt::Pointer::fmt(&self.as_ptr(), f)
2958     }
2959 }
2960
2961 #[stable(feature = "nonnull", since = "1.25.0")]
2962 impl<T: ?Sized> Eq for NonNull<T> {}
2963
2964 #[stable(feature = "nonnull", since = "1.25.0")]
2965 impl<T: ?Sized> PartialEq for NonNull<T> {
2966     fn eq(&self, other: &Self) -> bool {
2967         self.as_ptr() == other.as_ptr()
2968     }
2969 }
2970
2971 #[stable(feature = "nonnull", since = "1.25.0")]
2972 impl<T: ?Sized> Ord for NonNull<T> {
2973     fn cmp(&self, other: &Self) -> Ordering {
2974         self.as_ptr().cmp(&other.as_ptr())
2975     }
2976 }
2977
2978 #[stable(feature = "nonnull", since = "1.25.0")]
2979 impl<T: ?Sized> PartialOrd for NonNull<T> {
2980     fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
2981         self.as_ptr().partial_cmp(&other.as_ptr())
2982     }
2983 }
2984
2985 #[stable(feature = "nonnull", since = "1.25.0")]
2986 impl<T: ?Sized> hash::Hash for NonNull<T> {
2987     fn hash<H: hash::Hasher>(&self, state: &mut H) {
2988         self.as_ptr().hash(state)
2989     }
2990 }
2991
2992 #[unstable(feature = "ptr_internals", issue = "0")]
2993 impl<T: ?Sized> From<Unique<T>> for NonNull<T> {
2994     fn from(unique: Unique<T>) -> Self {
2995         NonNull { pointer: unique.pointer }
2996     }
2997 }
2998
2999 #[stable(feature = "nonnull", since = "1.25.0")]
3000 impl<'a, T: ?Sized> From<&'a mut T> for NonNull<T> {
3001     fn from(reference: &'a mut T) -> Self {
3002         NonNull { pointer: NonZero(reference as _) }
3003     }
3004 }
3005
3006 #[stable(feature = "nonnull", since = "1.25.0")]
3007 impl<'a, T: ?Sized> From<&'a T> for NonNull<T> {
3008     fn from(reference: &'a T) -> Self {
3009         NonNull { pointer: NonZero(reference as _) }
3010     }
3011 }