CARVIEW |
Select Language
HTTP/1.1 301 Moved Permanently
Server: nginx
Date: Thu, 24 Jul 2025 20:43:22 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Location: /reference/map/map/insert/
HTTP/1.1 200 OK
Server: nginx
Date: Thu, 24 Jul 2025 20:43:22 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
ETag: W/"9672-VfqAlhu/cvzPoxRWJ1L2+LQD56g"
Content-Encoding: gzip
Extends the container by inserting new elements, effectively increasing the container size by the number of elements inserted.
Because element keys in a map are unique, the insertion operation checks whether each inserted element has a key equivalent to the one of an element already in the container, and if so, the element is not inserted, returning an iterator to this existing element (if the function returns a value).
For a similar container allowing for duplicate elements, see multimap.
An alternative way to insert elements in a map is by using member function map::operator[].
Internally, map containers keep all their elements sorted by their key following the criterion specified by its comparison object. The elements are always inserted in its respective position following this ordering.
The parameters determine how many elements are inserted and to which values they are initialized:
The versions with a hint (2) return an iterator pointing to either the newly inserted element or to the element that already had an equivalent key in the map.
Member type iterator is a bidirectional iterator type that points to elements.
pair is a class template declared in <utility> (see pair).
Output:
Concurrently accessing existing elements is safe, although iterating ranges in the container is not.
Otherwise, the container is guaranteed to end in a valid state (basic guarantee).
If allocator_traits::construct is not supported with the appropriate arguments for the element constructions, or if an invalid position is specified, it causes undefined behavior.
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>
map
- map::~map
- map::map
member functions
-
map::atC++11
- map::begin
-
map::cbeginC++11
-
map::cendC++11
- map::clear
- map::count
-
map::crbeginC++11
-
map::crendC++11
-
map::emplaceC++11
-
map::emplace_hintC++11
- map::empty
- map::end
- map::equal_range
- map::erase
- map::find
- map::get_allocator
- map::insert
- map::key_comp
- map::lower_bound
- map::max_size
- map::operator[]
- map::operator=
- map::rbegin
- map::rend
- map::size
- map::swap
- map::upper_bound
- map::value_comp
-
non-member overloads
public member function
<map>
std::map::insert
single element (1) | pair<iterator,bool> insert (const value_type& val); |
---|---|
with hint (2) | iterator insert (iterator position, const value_type& val); |
range (3) | template <class InputIterator> void insert (InputIterator first, InputIterator last); |
single element (1) | pair<iterator,bool> insert (const value_type& val);template <class P> pair<iterator,bool> insert (P&& val); |
---|---|
with hint (2) | iterator insert (const_iterator position, const value_type& val);template <class P> iterator insert (const_iterator position, P&& val); |
range (3) | template <class InputIterator> void insert (InputIterator first, InputIterator last); |
initializer list (4) | void insert (initializer_list<value_type> il); |
Insert elements
Because element keys in a map are unique, the insertion operation checks whether each inserted element has a key equivalent to the one of an element already in the container, and if so, the element is not inserted, returning an iterator to this existing element (if the function returns a value).
For a similar container allowing for duplicate elements, see multimap.
An alternative way to insert elements in a map is by using member function map::operator[].
Internally, map containers keep all their elements sorted by their key following the criterion specified by its comparison object. The elements are always inserted in its respective position following this ordering.
The parameters determine how many elements are inserted and to which values they are initialized:
Parameters
- val
- Value to be copied to (or moved as) the inserted element.
Member type value_type is the type of the elements in the container, defined in map as pair<const key_type,mapped_type> (see map member types).
The template parameter P shall be a type convertible to value_type.
The signatures taking an argument of typeP&&
are only called ifstd::is_constructible<value_type,P&&>
istrue
.
- position
-
Hint for the position where the element can be inserted.
The function optimizes its insertion time if position points to the element that will precede the inserted element.
The function optimizes its insertion time if position points to the element that will follow the inserted element (or to the end, if it would be the last).
Member types iterator and const_iterator are defined in map as bidirectional iterator types that point to elements. - first, last
- Iterators specifying a range of elements. Copies of the elements in the range [first,last) are inserted in the container.
Notice that the range includes all the elements between first and last, including the element pointed by first but not the one pointed by last.
The function template argument InputIterator shall be an input iterator type that points to elements of a type from which value_type objects can be constructed. - il
- An initializer_list object. Copies of these elements are inserted.
These objects are automatically constructed from initializer list declarators.
Member type value_type is the type of the elements contained in the container, defined in map as pair<const key_type,mapped_type> (see map member types).
Return value
The single element versions (1) return a pair, with its member pair::first set to an iterator pointing to either the newly inserted element or to the element with an equivalent key in the map. The pair::second element in the pair is set to true if a new element was inserted or false if an equivalent key already existed.The versions with a hint (2) return an iterator pointing to either the newly inserted element or to the element that already had an equivalent key in the map.
Member type iterator is a bidirectional iterator type that points to elements.
pair is a class template declared in <utility> (see pair).
Example
|
|
element 'z' already existed with a value of 200 mymap contains: a => 100 b => 300 c => 400 z => 200 anothermap contains: a => 100 b => 300 |
Complexity
If a single element is inserted, logarithmic in size in general, but amortized constant if a hint is given and the position given is the optimal.Iterator validity
No changes.Data races
The container is modified.Concurrently accessing existing elements is safe, although iterating ranges in the container is not.
Exception safety
If a single element is to be inserted, there are no changes in the container in case of exception (strong guarantee).Otherwise, the container is guaranteed to end in a valid state (basic guarantee).
If allocator_traits::construct is not supported with the appropriate arguments for the element constructions, or if an invalid position is specified, it causes undefined behavior.
See also
- map::operator[]
- Access element (public member function)
- map::find
- Get iterator to element (public member function)
- map::erase
- Erase elements (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