public member function
template <class... Args> iterator emplace ( Args&&... args );
Construct and insert element
Inserts a new element in the unordered_multimap. This new element is constructed in place using args as the arguments for the element's constructor.
This effectively increases the container size by one.
A similar member function exists, insert, which either copies or moves existing objects into the container.
- Arguments used to construct a new object of the mapped type for the inserted element.
Because the mapped type is only part of the value type, the standard specification is -at least- ambiguous here. If implemented by your library, it may have been interpreted as either:
- The first argument in the list is treated as the key and the remaining arguments are used to construct an object of the mapped type in place.
- The arguments are used to construct a new object of the value type and passed to the pair constructor.
An iterator to the newly inserted element.
Member type iterator is a forward iterator type.
The storage for the new element is allocated using allocator_traits<allocator_type>::construct(), which may throw exceptions on failure (for the default allocator, bad_alloc is thrown if the allocation request does not succeed).
int main ()
myumm.emplace ("NCC-1701", "C. Pike");
myumm.emplace ("NCC-1701", "J.T. Kirk");
myumm.emplace ("NCC-1701-D", "J.L. Picard");
myumm.emplace ("NCC-74656", "K. Janeway");
std::cout << "myumm contains:" << std::endl;
for (auto& x: myumm)
std::cout << x.first << ": " << x.second << std::endl;
std::cout << std::endl;
NCC-1701: C. Pike
NCC-1701: J.T. Kirk
NCC-1701-D: J.L. Picard
NCC-74656: K. Janeway
Average case: constant.
Worst case: linear in container size.
May trigger a rehash (not included).
On most cases, all iterators in the container remain valid after the insertion. The only exception being when the growth of the container forces a rehash. In this case, all iterators in the container are invalidated.
A rehash is forced if the new container size after the insertion operation would increase above its capacity threshold (calculated as the container's bucket_count multiplied by its max_load_factor).
References to elements in the unordered_multimap container remain valid in all cases, even after a rehash.