ptr::swap docs needs clarfication

[Gankra]

The docs state that overlap is permitted, which is intended to cover the lhs==rhs case, but don't specify what that means for partial overlap. For instance:

let mut x = [0u32, 1, 2]; 
let a = &mut x[0] as *mut _ as *mut[u32; 2]; 
let b = &mut x[1] as *mut _ as *mut[u32; 2]; 
ptr::swap(a, b);

// Today: [1, 0, 1]
println!("{:?}", x); 

Reasonable implementations are forced to produce either 0 or 2 for the middle value. We should definitely at least spec that that happens. If we want to be Extra Helpful, we can specify that 0 is used, because there's basically no reason to change this behaviour, or for a different impl to diverge.

Something like "if the LHS and RHS overlap, then the overlapping region of memory will be derived from the LHS", along with the above example to clarify.

A nice thing about specifying it is that, because it's otherwise symmetric, you can swap your lhs/rhs to choose exactly which half you want to "win".

[steveklabnik]

Nominating for @rust-lang/libs discussion about what behavior to spec; then @rust-lang/docs is happy to doc whatever they decide.

[dtolnay]

I am okay with the current behavior. Agree the doc should explain what happens.

[alexcrichton]

Discussed during libs triage the conclusion was "let's do what C++ does", there weren't any particular strong opinions.

[frewsxcv]

Seems like this might be resolved by #43964?

[Gankra]

No that's where the issue was raised. I didn't want to block the PR on a pre-existing issue.

[frewsxcv]

i'd be happy to take care of this

Discussed during libs triage the conclusion was "let's do what C++ does", there weren't any particular strong opinions.

to clarify, does C++ do the 'LHS winning' behavior that @gankro mentioned in the original description of this issue? and if so, does C++ specify this behavior somewhere?

[frewsxcv]

opened a PR for this, would appreciate if one of y'all could take a look: #46483