Allow a `HashMap` and `BTreeMap` entry to be replaced.

[Binero]

At the moment the only way to replace a map entry with a new one, swallows the old key. In cases the user wants to keep the old key, the only way to do so is to first remove_entry and to then insert a new one. This requires two map look-ups.

As the Entry API aims to make operations that would otherwise require two look-ups into operations that require only one, the replacing of an entry is an obvious hole in the API.

• Implemented in #44278
• Tweaked in #45152

[stepancheg]

While it is indeed a missing API, there are several issues with this new API implemented in PR #44278:

• it seems to panics if take_key was called before (it is not public API)
• it replaces both key and value, so
• • is not possible to replace only key or only value (there's insert function which replaces only value)
• • it does do completely independent things in one operation
• it is not possible to replace key in VacantEntry (it is pointless)
• it takes self, while it could take &mut self, so replace could be called again if it is needed for some reason
• key replacement it is against least surprise principle

I think HashMap::replace should be different:

impl OccupiedEntry<...> {
    fn replace_value(&mut self, new_value: V) -> V {
        replace value with new value, do not touch the key.
    }
}

And probably that's it.

If we need to replace key for some reason, replace_key operation needs to be added to both OccupiedEntry and VacantEntry.

[Binero]

• take_key cannot be called before, all functions that call it consume the entry.
• The point is to be able to swap out the key without multiple lookups. replace_value beats the point.
• A VacantEntry does not have a key, so it's unclear how the function would work.

[stepancheg]

take_key cannot be called before, all functions that call it consume the entry.

Oh, it is not public API, thanks.

The point is to be able to swap out the key without multiple lookups. replace_value beats the point.

But this function does not allow to replace key without replacing value.

BTW, there's already a function to replace value, it's called insert.

So if we had replace_key instead of current replace, then current replace could be emulated as:

occupied_entry.insert(new_value);
occupied_entry.replace_key()

replace_key is not possible now, and replace is redundant if we had replace_key.

A VacantEntry does not have a key, so it's unclear how the function would work.

Please ignore that.

[Binero]

I will take a look at replace_key when I have time, probably next week.

[Binero]

@stepancheg I think it's probably better to have replace_key consume the entry, because the semantics of the function would otherwise change after the first call.

[SimonSapin]

This has been in Nightly for long enough that I’m inclined to stabilize, but I don’t quite understand the use case. @Binero, can you explain some more why it can be important to recover the old key rather than the new one (passed to HashMap::entry() which hashes and compares equal?

[Binero]

@SimonSapin

It is quite a niche function, so it's certainly not instantly obvious where this would be useful.

That said, it has some uses when you want to for example lower the memory footprint of a HashMap by swapping out an Rc<T> with another, equivalent, Rc<T> that you are already using elsewhere.

If either T or the HashMap is large enough, this could reduce the memory footprint of the application by quite a lot.