Document behavior of ptr::swap with overlapping regions of memory.

[frewsxcv]

Fixes #44479.

[rust-highfive]

r? @BurntSushi

(rust_highfive has picked a reviewer for you, use r? to override)

[BurntSushi]

I don't think I understood the last sentence here until I looked at the example. Is there any way to write this more clearly? (The answer might be "no." I don't have any particularly good ideas.)

[frewsxcv]

another wording that comes to mind:

If the values do overlap, then the overlapping region of memory from x takes priority.

[BurntSushi]

That does actually seem better to me.

[frewsxcv]

adjusted in the latest force push

[durka]

I have to be honest, I didn't understand "takes priority" and I find the original wording better :/

[Gankra]

"will be used" is another possibility. It might also make sense to simply be like "see the example below" since this is definitely something an example clarifies greatly.

[frewsxcv]

applied @gankro's suggestions in the latest force push

--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -91,9 +91,12 @@ pub const fn null<T>() -> *const T { 0 as *const T }
 pub const fn null_mut<T>() -> *mut T { 0 as *mut T }
 
 /// Swaps the values at two mutable locations of the same type, without
-/// deinitializing either. The values pointed at by `x` and `y` may overlap,
-/// unlike `mem::swap` which is otherwise equivalent. If the values do overlap,
-/// then the overlapping region of memory from `x` takes priority.
+/// deinitializing either.
+///
+/// The values pointed at by `x` and `y` may overlap, unlike `mem::swap` which
+/// is otherwise equivalent. If the values do overlap, then the overlapping
+/// region of memory from `x` will be used. This is demonstrated in the
+/// examples section below.
 ///
 /// # Safety
 ///

[BurntSushi]

This looks good to me and appears consistent with what we agreed on in #44479. I did leave one comment about clarifying the docs, but you might say that the current PR is good enough!

cc @gankro @rust-lang/libs

[Gankra]

sgtm

[steveklabnik]

I'm also a little unsure about how to phrase this, but if we can't think of anything, we should

[frewsxcv]

anyone else have thoughts here? someone wanna approve this?

[BurntSushi]

Let's do it! Thanks for the improvement @frewsxcv! @bors r+

[bors]

📌 Commit f366227 has been approved by BurntSushi

[frewsxcv]

@bors rollup