From cppreference.com
template<class...Args>iteratoremplace_hint(const_iteratorhint,Args&&...args);(since C++11)Inserts a new element into the container, using hint as a suggestion where the element should go.
The constructor of the element type (value_type, that is, std::pair<constKey,T>) is called with exactly the same arguments as supplied to the function, forwarded with std::forward<Args>(args)....
If after the operation the new number of elements is greater than old
*
a rehashing takes place.
If rehashing occurs (due to the insertion), all iterators are invalidated. Otherwise (no rehashing), iterators are not invalidated.
Parameters
hint - iterator, used as a suggestion as to where to insert the new element args - arguments to forward to the constructor of the element Return value
An iterator to the inserted element, or to the element that prevented the insertion.
Exceptions
If an exception is thrown for any reason, this function has no effect (
strong exception safety guarantee
).
Complexity
Amortized constant on average, worst case linear in the size of the container.
Example
Run this code
#include<chrono>#include<cstddef>#include<functional>#include<iomanip>#include<iostream>#include<unordered_map>constintn_operations=100'500'0;std::size_tmap_emplace(){std::unordered_map<int,char>map;for(inti=0;i<n_operations;++i)map.emplace(i,'a');returnmap.size();}std::size_tmap_emplace_hint(){std::unordered_map<int,char>map;autoit=map.begin();for(inti=0;i<n_operations;++i){map.emplace_hint(it,i,'b');it=map.end();}returnmap.size();}std::size_tmap_emplace_hint_wrong(){std::unordered_map<int,char>map;autoit=map.begin();for(inti=n_operations;i>0;--i){map.emplace_hint(it,i,'c');it=map.end();}returnmap.size();}std::size_tmap_emplace_hint_corrected(){std::unordered_map<int,char>map;autoit=map.begin();for(inti=n_operations;i>0;--i){map.emplace_hint(it,i,'d');it=map.begin();}returnmap.size();}std::size_tmap_emplace_hint_closest(){std::unordered_map<int,char>map;autoit=map.begin();for(inti=0;i<n_operations;++i)it=map.emplace_hint(it,i,'e');returnmap.size();}doubletime_it(std::function<std::size_t()>map_test,std::stringwhat="",doubleratio=0.0){constautostart=std::chrono::system_clock::now();conststd::size_tmap_size=map_test();constautostop=std::chrono::system_clock::now();std::chrono::duration<double,std::milli>time=stop-start;if(what.size()&&map_size)std::cout<<std::setw(8)<<time<<" for "<<what<<" (ratio: "<<(ratio==0.0?1.0:ratio/time.count())<<")\n";returntime.count();}intmain(){std::cout<<std::fixed<<std::setprecision(2);time_it(map_emplace);// cache warmupconstautox=time_it(map_emplace,"plain emplace");time_it(map_emplace_hint,"emplace with correct hint",x);time_it(map_emplace_hint_wrong,"emplace with wrong hint",x);time_it(map_emplace_hint_corrected,"corrected emplace",x);time_it(map_emplace_hint_closest,"emplace using returned iterator",x);}Possible output:
143.48ms for plain emplace (ratio: 1.00) 164.78ms for emplace with correct hint (ratio: 0.87) 171.22ms for emplace with wrong hint (ratio: 0.84) 166.55ms for corrected emplace (ratio: 0.86) 167.41ms for emplace using returned iterator (ratio: 0.86) See also
constructs element in-place
(public member function)
inserts elements or nodes(since C++17)
(public member function)