Rename `CoerceSized` to `DispatchFromDyn`, and reverse the direction so that, for example, you write
```
impl<T: Unsize<U>, U> DispatchFromDyn<*const U> for *const T {}
```
instead of
```
impl<T: Unsize<U>, U> DispatchFromDyn<*const T> for *const U {}
```
this way the trait is really just a subset of `CoerceUnsized`.
The checks in object_safety.rs are updated for the new trait, and some documentation and method names in there are updated for the new trait name — e.g. `receiver_is_coercible` is now called `receiver_is_dispatchable`. Since the trait now works in the opposite direction, some code had to updated here for that too.
I did not update the error messages for invalid `CoerceSized` (now `DispatchFromDyn`) implementations, except to find/replace `CoerceSized` with `DispatchFromDyn`. Will ask for suggestions in the PR thread.
During review of the previous commit, @joshtriplett noticed that
the emphasis on 'the same' is unnecessary. For consistency, remove it
on the offset() functions, as well.
Ralf Jung made the same changes to the offset functions' documentation
in commit fb089156. As add/sub just call offset, the same limitation
applies here, as well.
Removed emphasis on review request by @joshtriplett
Rewrite docs for pointer methods
This takes over https://github.com/rust-lang/rust/pull/51016 by @ecstatic-morse. They did most of the work, I just did some editing.
However, I realized one problem: This updates the docs for the "free functions" in `core::ptr`, but it does not update the copies of these docs for the inherent methods of the `*const T` and `*mut T` types. These getting out-of-sync is certainly bad, but I also don't feel like copying all this stuff around. Instead, we should remove this redundancy. Any good ideas?
This splits "valid" into "valid for reads" and "valid for writes", and
also adds the concept of operation size to validity. Now functions which
operate on sequences state that e.g. pointer args must be "valid for reads of
size x".
The enumerated list of conditions is replaced by an explanation that
rust doesn't have a formal memory model. It does say that pointers
created directly from references are guaranteed to be valid, and links
to both the "Unsafe Code" section of the book and the "Undefined
Behavior" section of the reference.
- Add links to the GNU libc docs for `memmove`, `memcpy`, and
`memset`, as well as internally linking to other functions in `std::ptr`
- List invariants which, when violated, cause UB for all functions
- Add example to `ptr::drop_in_place` and compares it to `ptr::read`.
- Add examples which more closely mirror real world uses for the
functions in `std::ptr`. Also, move the reimplementation of `mem::swap`
to the examples of `ptr::read` and use a more interesting example for
`copy_nonoverlapping`.
- Change module level description
- Define what constitutes a "valid" pointer.
- Centralize discussion of ownership of bitwise copies in `ptr::read` and
provide an example.
