[container.requirements] Confusing "Returns" paragraph under a.emplace_hint(p, args)

[seishun]

An iterator pointing to the element with the key equivalent to the newly inserted element.

• In containers with unique keys, an element is not always inserted, so there might be no "newly inserted element".
• In containers with equivalent keys, there might be more than one element "with the key equivalent to the newly inserted element".

[jensmaurer]

Would the phrasing

"Returns: The iterator returned by emplace."

address your concerns?

@jwakely ?

[seishun]

I'm not sure if it's correct to say that emplace returns an iterator in containers with unique keys.

[jensmaurer]

Well, emplace returns a pair for containers with unique keys, and we pick the iterator part of that pair. It's still "the" iterator returned by emplace, since the other part of the pair is a boolean, thus not an iterator.

[seishun]

Then perhaps the "Returns" paragraph under a_uniq.emplace(args) should say "the returned iterator" for consistency, just like it already does under try_emplace throughout [containers].