CARVIEW |
Select Language
HTTP/1.1 301 Moved Permanently
Server: nginx
Date: Sat, 19 Jul 2025 10:30:04 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Location: /reference/unordered_map/unordered_map/emplace_hint/
HTTP/1.1 200 OK
Server: nginx
Date: Sat, 19 Jul 2025 10:30:04 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
ETag: W/"8e32-S6eEKTBEpLvRn7A50jCXfNt2JS0"
Content-Encoding: gzip
Inserts a new element in the unordered_map if its key is unique. This new element is constructed in place using args as the arguments for the element's constructor. position points to a location in the container suggested as a hint on where to start the search for its insertion point (the container may or may not use this suggestion to optimize the insertion operation).
The insertion only takes place if no element in the container has a key equivalent to the one being emplaced (keys in an unordered_map are unique).
If inserted, this effectively increases the container size by one.
A similar member function exists, insert, which either copies or moves an existing object into the container, and may also take a position hint.
Member type iterator is a forward iterator.
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).
Worst case: linear in container size.
May trigger a rehash (not included).
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 remain valid in all cases, even after a rehash.
Reference
C library:
- <cassert> (assert.h)
- <cctype> (ctype.h)
- <cerrno> (errno.h)
-
<cfenv> (fenv.h)C++11
- <cfloat> (float.h)
-
<cinttypes> (inttypes.h)C++11
- <ciso646> (iso646.h)
- <climits> (limits.h)
- <clocale> (locale.h)
- <cmath> (math.h)
- <csetjmp> (setjmp.h)
- <csignal> (signal.h)
- <cstdarg> (stdarg.h)
-
<cstdbool> (stdbool.h)C++11
- <cstddef> (stddef.h)
-
<cstdint> (stdint.h)C++11
- <cstdio> (stdio.h)
- <cstdlib> (stdlib.h)
- <cstring> (string.h)
-
<ctgmath> (tgmath.h)C++11
- <ctime> (time.h)
-
<cuchar> (uchar.h)C++11
- <cwchar> (wchar.h)
- <cwctype> (wctype.h)
Containers:
-
<array>C++11
- <deque>
-
<forward_list>C++11
- <list>
- <map>
- <queue>
- <set>
- <stack>
-
<unordered_map>C++11
-
<unordered_set>C++11
- <vector>
-
Input/Output:
Multi-threading:
-
<atomic>C++11
-
<condition_variable>C++11
-
<future>C++11
-
<mutex>C++11
-
<thread>C++11
-
Other:
- <algorithm>
- <bitset>
-
<chrono>C++11
-
<codecvt>C++11
- <complex>
- <exception>
- <functional>
-
<initializer_list>C++11
- <iterator>
- <limits>
- <locale>
- <memory>
- <new>
- <numeric>
-
<random>C++11
-
<ratio>C++11
-
<regex>C++11
- <stdexcept>
- <string>
-
<system_error>C++11
-
<tuple>C++11
-
<type_traits>C++11
-
<typeindex>C++11
- <typeinfo>
- <utility>
- <valarray>
<unordered_map>
-
unordered_mapC++11
-
unordered_multimapC++11
unordered_map
-
unordered_map::~unordered_mapC++11
-
unordered_map::unordered_mapC++11
member functions
-
unordered_map::atC++11
-
unordered_map::beginC++11
-
unordered_map::bucketC++11
-
unordered_map::bucket_countC++11
-
unordered_map::bucket_sizeC++11
-
unordered_map::cbeginC++11
-
unordered_map::cendC++11
-
unordered_map::clearC++11
-
unordered_map::countC++11
-
unordered_map::emplaceC++11
-
unordered_map::emplace_hintC++11
-
unordered_map::emptyC++11
-
unordered_map::endC++11
-
unordered_map::equal_rangeC++11
-
unordered_map::eraseC++11
-
unordered_map::findC++11
-
unordered_map::get_allocatorC++11
-
unordered_map::hash_functionC++11
-
unordered_map::insertC++11
-
unordered_map::key_eqC++11
-
unordered_map::load_factorC++11
-
unordered_map::max_bucket_countC++11
-
unordered_map::max_load_factorC++11
-
unordered_map::max_sizeC++11
-
unordered_map::operator[]C++11
-
unordered_map::operator=C++11
-
unordered_map::rehashC++11
-
unordered_map::reserveC++11
-
unordered_map::sizeC++11
-
unordered_map::swapC++11
-
non-member overloads
-
operators (unordered_map)C++11
-
swap (unordered_map)C++11
-
- Reference
- <unordered_map>
- unordered_map
- emplace_hint
public member function
<unordered_map>
std::unordered_map::emplace_hint
template <class... Args>iterator emplace_hint ( const_iterator position, Args&&... args );
Construct and insert element with hint
The insertion only takes place if no element in the container has a key equivalent to the one being emplaced (keys in an unordered_map are unique).
If inserted, this effectively increases the container size by one.
A similar member function exists, insert, which either copies or moves an existing object into the container, and may also take a position hint.
Parameters
- position
- Position suggested as a hint for the insertion operation. This value may be used by the container to optimize the operation.
Member type const_iterator is a forward iterator type. - args
- Arguments used to construct a new object of the mapped type for the inserted element.
Arguments forwarded to construct the new element (of typepair<const key_type, mapped_type>
).
This can be one of:
- Two arguments: one for the key, the other for the mapped value.
- A single argument of apair
type with a value for the key as first member, and a value for the mapped value as second.
- piecewise_construct as first argument, and two additional arguments with tuples to be forwarded as arguments for the key value and for the mapped value respectivelly.
See pair::pair for more info.
Return value
An iterator to the element in the container with the key equivalent to the newly inserted element. This points to the newly inserted element if it was indeed inserted, or to the existing element with the equivalent key if one already existed (it is not replaced).Member type iterator is a forward iterator.
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).
Example
No example yet. See unordered_map::emplace's example.Complexity
Average case: constant.Worst case: linear in container size.
May trigger a rehash (not included).
Iterator validity
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 remain valid in all cases, even after a rehash.
See also
- unordered_map::emplace
- Construct and insert element (public member function)
- unordered_map::insert
- Insert elements (public member function)
- unordered_map::operator[]
- Access element (public member function)
- unordered_map::at
- Access element (public member function)
Home page | Privacy policy
© cplusplus.com, 2000-2025 - All rights reserved - v3.3.4s
Spotted an error? contact us
© cplusplus.com, 2000-2025 - All rights reserved - v3.3.4s
Spotted an error? contact us