[std][BTree] Fix behavior of ::append to match documentation, ::insert, and ::extend

[tinnamchoi]

Resolves #145614

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[Mark-Simulacrum]

BTreeMap::append is documented as:

Moves all elements from other into self, leaving other empty.

If a key from other is already present in self, the respective value from self will be overwritten with the respective value from other.

This (IMO) leaves ambiguous whether equal (by Eq/Ord) keys are updated or not in the implementation. Today, append will update the key as well. This PR is proposing that we align the behavior with insert's, which is documented as not updating the key:

If the map did have this key present, the value is updated, and the old value is returned. The key is not updated, though; this matters for types that can be == without being identical. See the module-level documentation for more.

This is a breaking change, so nominating for libs-api. We can try running crater, but I'm not sure we'll find much signal given the specific conditions needed to trigger it (BTreeMap, using append, having keys with extra metadata, and writing a test reachable in Crater that exercises this case).

HashMap's extend impl uses insert internally, so it matches insert behavior. BTreeMap's extend also calls BTreeMap::insert in a loop and so does not match append today.

@tinnamchoi, can you also update the docs for append to reflect this change?