Addressed issues raised in #44286. (OccupiedEntry::replace_entry)

[Binero]

This commit renames the replace function to replace_entry, and
creates a seperate replace_key function for OccupiedEntry. The
original replace function did not solve the use-case where the
key needed to be replaced, but not the value. Documentation and
naming has also been updated to better reflect what the original
replace function does.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @dtolnay (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[kennytm]

Please change the tabs into spaces.

[00:04:04] tidy error: /checkout/src/libstd/collections/hash/map.rs:2289: tab character
[00:04:04] tidy error: /checkout/src/libstd/collections/hash/map.rs:2290: tab character

[aidanhs]

Ping @dtolnay for review! (also pinged on IRC)

[dtolnay]

Thanks for the reminder!

I am on board with the idea, and the implementation looks good. But could you change the usage example to illustrate a more realistic use case? Replacing "poneyland".to_string() with "poneyland".to_string() is not meaningful.

In general, usage examples are often not about how to use a particular API. If the user got far enough with Rust to be looking at OccupiedEntry documentation, we can assume they understand how to match on an enum and invoke functions. Here and elsewhere, the role of the example should be about why someone would want this functionality.

Either here or in a following PR, please also update the replace_entry documentation with a why example.

[carols10cents]

Triage ping @Binero! Does @dtolnay's request about the documentation example make sense?

[Binero]

@dtolnay @carols10cents Oh, whoops. I missed this one. It sure does.

As for replace_key, I am not sure what the use case for that would be, @stepancheg requested it. replace_entry however is the expected behaviour when you use the entry API to replace a value, as otherwise the new key is lost, or the old key does not match the new value. It plugs the API hole resulting from the Entry taking ownership.

Discussion: #44286

[stepancheg]

It can be used for example to reclaim memory used by keys. E. g.

struct RcString { ... }

Vec<RcString> known_strings;

fn reclaim_memory_used_by_keys(map: &mut HashMap<RcString, Something>) {
    for s in &known_strings {
        if let Entry::Occupied(e) = Entrymap.entry(s) {
            e.replace_key();
        }
    }
}

[shepmaster]

Triage ping @Binero! It looks like you got some feedback on the rationale for replace_key — will you have time to work that back into the documentation?

[Binero]

Added better examples, and rebased them all.

[dtolnay]

@bors r+

[bors]

📌 Commit 3ba2631 has been approved by dtolnay

[bors]

⌛ Testing commit 3ba26319996e3d1d8a6594a80e3ab0acb89ade66 with merge 5120f57e5210955682db123cfb4a23d12143f80e...

[bors]

💔 Test failed - status-appveyor

[dtolnay]

tidy error: C:\projects\rust\src\libstd\collections\hash\map.rs:2256: trailing whitespace
tidy error: C:\projects\rust\src\libstd\collections\hash\map.rs:2284: trailing whitespace
tidy error: C:\projects\rust\src\libstd\collections\hash\map.rs:2286: trailing whitespace
tidy error: C:\projects\rust\src\libstd\collections\hash\map.rs:2288: trailing whitespace
some tidy checks failed

[Binero]

Amended the style-changes to the last commit.

[dtolnay]

@bors r+

[bors]

📌 Commit 0fb37fc has been approved by dtolnay

[bors]

⌛ Testing commit 0fb37fc with merge 45caff8...

[bors]

☀️ Test successful - status-appveyor, status-travis
Approved by: dtolnay
Pushing 45caff8 to master...