core::ptr: deduplicate more method docs
used `rg -Fxf library/core/src/ptr/{const,mut}_ptr.rs` to find duplicated doc comments, and `diff -u` after copying them to files to ensure they are actually identical.
`sed 's| */// *||'` was then used to translate the doc comments to plain markdown.
part of https://github.com/rust-lang/rust/issues/139190
core: begin deduplicating pointer docs
this also cleans up two inconsistancies:
1. both doctests on the ::add methods were actually calling the const version.
2. on of the ::offset methods was missing a line of clarification.
part of https://github.com/rust-lang/rust/issues/139190
Add some track_caller info to precondition panics
Currently, when you encounter a precondition check, you'll always get the caller location of the implementation of the precondition checks. But with this PR, you'll be told the location of the invalid call. Which is useful.
I thought of this while looking at https://github.com/rust-lang/rust/pull/129642#issuecomment-2311703898.
The changes to `tests/ui/const*` happen because the const-eval interpreter skips `#[track_caller]` frames in its backtraces.
The perf implications of this are:
* Increased debug binary sizes. The caller_location implementation requires that the additional data we want to display here be stored in const allocations, which are deduplicated but not across crates. There is no impact on optimized build sizes. The panic path and the caller location data get optimized out.
* The compile time hit to opt-incr-patched bitmaps happens because the patch changes the line number of some function calls with precondition checks, causing us to go from 0 dirty CGUs to 1 dirty CGU.
* The other compile time hits are marginal but real, and due to doing a handful of new queries. Adding more useful data isn't completely free.
this also cleans up two inconsistancies:
1. both doctests on the ::add methods were
actually calling the const version.
2. on of the ::offset methods was missing
a line of clarification.
part of https://github.com/rust-lang/rust/issues/139190
stabilize ptr::swap_nonoverlapping in const
Closes https://github.com/rust-lang/rust/issues/133668
The blocking issue mentioned there is resolved by documentation. We may in the future actually support such code, but that is blocked on https://github.com/rust-lang/const-eval/issues/72 which is non-trivial to implement. Meanwhile, this completes stabilization of all `const fn` in `ptr`. :)
Here's a version of the problematic example to play around with:
https://play.rust-lang.org/?version=nightly&mode=debug&edition=2021&gist=6c390452379fb593e109b8f8ee854d2a
Should be FCP'd with both `@rust-lang/libs-api` and `@rust-lang/lang` since `swap_nonoverlapping` is documented to work as an "untyped" operation but due to the limitation mentioned above, that's not entirely true during const evaluation. I expect this limitation will only be hit in niche corner cases, so the benefits of having this function work most of the time outweigh the downsides of users running into this problem. (Note that unsafe code could already hit this limitation before this PR by doing cursed pointer casts, but having it hidden inside `swap_nonoverlapping` feels a bit different.)
Ensure `swap_nonoverlapping` is really always untyped
This replaces #134954, which was arguably overcomplicated.
## Fixes#134713
Actually using the type passed to `ptr::swap_nonoverlapping` for anything other than its size + align turns out to not work, so this goes back to always erasing the types down to just bytes.
(Except in `const`, which keeps doing the same thing as before to preserve `@RalfJung's` fix from #134689)
## Fixes#134946
I'd previously moved the swapping to use auto-vectorization *on bytes*, but someone pointed out on Discord that the tail loop handling from that left a whole bunch of byte-by-byte swapping around. This goes back to manual tail handling to avoid that, then still triggers auto-vectorization on pointer-width values. (So you'll see `<4 x i64>` on `x86-64-v3` for example.)
Replace last `usize` -> `ptr` transmute in `alloc` with strict provenance API
This replaces the `usize -> ptr` transmute in `RawVecInner::new_in` with a strict provenance API (`NonNull::without_provenance`).
The API is changed to take an `Alignment` which encodes the non-null constraint needed for `Unique` and allows us to do the construction safely.
Two internal-only APIs were added to let us avoid UB-checking in this hot code: `Layout::alignment` to get the `Alignment` type directly rather than as a `usize`, and `Unique::from_non_null` to create `Unique` in const context without a transmute.
Fix missing const for inherent pointer `replace` methods
`ptr::replace` (the free fn) is already const stable. However, there are inherent convenience methods on `*mut T` and `NonNull<T>`, allowing you to write eg. `unsafe { foo.replace(bar) }` where `foo` is `*mut T` or `NonNull<T>`.
It seems const was never added to the inherent method (likely oversight), so this PR adds it.
I don't believe this needs another[^1] FCP as the inherent methods are already stable and `ptr::replace` is already const stable, so this adds no new API.
Original tracking issue: #83164
`ptr::replace` constified in #83091
`ptr::replace` const stabilized in #130954
[^1]: `const_replace` FCP completed: https://github.com/rust-lang/rust/issues/83164#issuecomment-2385670050
core: Make `Debug` impl of raw pointers print metadata if present
Make Rust pointers appear less magic by including metadata information in their `Debug` output.
This does not break Rust stability guarantees because `Debug` impl are explicitly exempted from stability:
https://doc.rust-lang.org/std/fmt/trait.Debug.html#stability
> ## Stability
>
> Derived `Debug` formats are not stable, and so may change with future Rust versions. Additionally, `Debug` implementations of types provided by the standard library (`std`, `core`, `alloc`, etc.) are not stable, and may also change with future Rust versions.
Note that a regression test is added as a separate commit to make it clear what impact the last commit has on the output.
Closes#128684 because the output of that code now becomes:
```
thread 'main' panicked at src/main.rs:5:5:
assertion `left == right` failed
left: Pointer { addr: 0x7ffd45c6fc6b, metadata: 5 }
right: Pointer { addr: 0x7ffd45c6fc6b, metadata: 3 }
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
```
Use `std::mem::{size_of, size_of_val, align_of, align_of_val}` from the
prelude instead of importing or qualifying them.
These functions were added to all preludes in Rust 1.80.
Fix `ptr::from_ref` documentation example comment
The comment says that the expression involves no function call, but that was only true for the example above, the example here _does_ contain a function call.
``@rustbot`` label A-docs
Fix doc for read&write unaligned in zst operation
### PR Description
This PR addresses an inconsistency in the Rust documentation regarding `read_unaligned ` and `write_unaligned` on zero-sized types (ZSTs). The current documentation for [pointer validity](https://doc.rust-lang.org/nightly/std/ptr/index.html#safety) states that for zero-sized types (ZSTs), null pointers are valid:
> For zero-sized types (ZSTs), every pointer is valid, including the null pointer.
However, there is an inconsistency in the documentation for the unaligned read operation in the function [ptr::read_unaligned](https://doc.rust-lang.org/nightly/std/ptr/fn.read_unaligned.html)(as well as `write_unaligned`), which states:
> Note that even if T has size 0, the pointer must be non-null.
This change is also supported by [PR #134912](https://github.com/rust-lang/rust/pull/134912)
> the _unaligned method docs should be fixed.
ptr docs: make it clear that we are talking only about memory accesses
This should make it harder to take this sentence out of context and misunderstand it.
