Clarify Extend behaviour wrt existing keys

[shahn]

This seems to be consistent with all the Extend implementations I found, and isn't documented anywhere else afaik.

[rust-highfive]

r? @aturon

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

[shahn]

r? @steveklabnik

[steveklabnik]

@rust-lang/libs is this something we want to guarantee here?

[sfackler]

I would probably move this documentation to the implementations themselves - this wording may not make sense for a multimap or multiset, for example.

[pnkfelix]

@sfackler one might argue the phrase "the entry is updated" is open-ended enough to cover multimaps/multisets. It is certainly more appropos than saying "the entry is replaced", at least to me.

(I assume that the critical detail the author desires is to convey that such entries are not ignored during the traversal. Is that open-ended enough to commit to?)

[shahn]

Yes indeed, that's what this is about. How about the following wording: the entry is updated or newly added if multiple elements with the same key are permitted."?

[shahn]

I have pondered a bit on the wording and provided an updated wording, is that better? I would really like to avoid making the Extend behaviour implementation documented, because that's a lot of places to look and a chance for confusing behaviour/inconsistent docs to creep in.

[steveklabnik]

I like this wording, I think. @sfackler@pnkfelix ?

[sfackler]

👍

[steveklabnik]

@bors: r+ rollup

thanks!

[bors]

📌 Commit 74b2587 has been approved by steveklabnik