Standard library header <map>
From cppreference.com
This header is part of the containers library.
Includes | |
(C++20) |
Three-way comparison operator support |
(C++11) |
std::initializer_list class template |
Classes | |
| collection of key-value pairs, sorted by keys, keys are unique (class template) | |
| collection of key-value pairs, sorted by keys (class template) | |
Functions | |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values of two maps (function template) |
| specializes the std::swap algorithm (function template) | |
(C++20) |
erases all elements satisfying specific criteria (function template) |
(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(removed in C++20)(C++20) |
lexicographically compares the values of two multimaps (function template) |
| specializes the std::swap algorithm (function template) | |
(C++20) |
erases all elements satisfying specific criteria (function template) |
Range access | |
(C++11)(C++14) |
returns an iterator to the beginning of a container or array (function template) |
(C++11)(C++14) |
returns an iterator to the end of a container or array (function template) |
(C++14) |
returns a reverse iterator to the beginning of a container or array (function template) |
(C++14) |
returns a reverse end iterator for a container or array (function template) |
(C++17)(C++20) |
returns the size of a container or array (function template) |
(C++17) |
checks whether the container is empty (function template) |
(C++17) |
obtains the pointer to the underlying array (function template) |
Synopsis
#include <compare>
#include <initializer_list>
namespace std {
// class template map
template<class Key,
class T,
class Compare = less<Key>,
class Allocator = allocator<pair<const Key, T>>>
class map;
template<class Key, class T, class Compare, class Allocator>
constexpr bool operator==(const map<Key, T, Compare, Allocator>& x,
const map<Key, T, Compare, Allocator>& y);
template<class Key, class T, class Compare, class Allocator>
constexpr /*synth-three-way-result*/<pair<const Key, T>> operator<=>(
const map<Key, T, Compare, Allocator>& x, const map<Key, T, Compare, Allocator>& y);
template<class Key, class T, class Compare, class Allocator>
constexpr void swap(map<Key, T, Compare, Allocator>& x,
map<Key, T, Compare, Allocator>& y) noexcept(noexcept(x.swap(y)));
// erasure for map
template<class Key, class T, class Compare, class Allocator, class Predicate>
constexpr typename map<Key, T, Compare, Allocator>::size_type erase_if(
map<Key, T, Compare, Allocator>& c, Predicate pred);
// class template multimap
template<class Key,
class T,
class Compare = less<Key>,
class Allocator = allocator<pair<const Key, T>>>
class multimap;
template<class Key, class T, class Compare, class Allocator>
constexpr bool operator==(const multimap<Key, T, Compare, Allocator>& x,
const multimap<Key, T, Compare, Allocator>& y);
template<class Key, class T, class Compare, class Allocator>
constexpr /*synth-three-way-result*/<pair<const Key, T>> operator<=>(
const multimap<Key, T, Compare, Allocator>& x,
const multimap<Key, T, Compare, Allocator>& y);
template<class Key, class T, class Compare, class Allocator>
constexpr void swap(
multimap<Key, T, Compare, Allocator>& x,
multimap<Key, T, Compare, Allocator>& y) noexcept(noexcept(x.swap(y)));
// erasure for multimap
template<class Key, class T, class Compare, class Allocator, class Predicate>
constexpr typename multimap<Key, T, Compare, Allocator>::size_type erase_if(
multimap<Key, T, Compare, Allocator>& c, Predicate pred);
namespace pmr {
template<class Key, class T, class Compare = less<Key>>
using map = std::map<Key, T, Compare, polymorphic_allocator<pair<const Key, T>>>;
template<class Key, class T, class Compare = less<Key>>
using multimap =
std::multimap<Key, T, Compare, polymorphic_allocator<pair<const Key, T>>>;
}
}
Class template std::map
namespace std {
template<class Key,
class T,
class Compare = less<Key>,
class Allocator = allocator<pair<const Key, T>>>
class map
{
public:
// types
using key_type = Key;
using mapped_type = T;
using value_type = pair<const Key, T>;
using key_compare = Compare;
using allocator_type = Allocator;
using pointer = allocator_traits<Allocator>::pointer;
using const_pointer = allocator_traits<Allocator>::const_pointer;
using reference = value_type&;
using const_reference = const value_type&;
using size_type = /* implementation-defined */;
using difference_type = /* implementation-defined */;
using iterator = /* implementation-defined */;
using const_iterator = /* implementation-defined */;
using reverse_iterator = std::reverse_iterator<iterator>;
using const_reverse_iterator = std::reverse_iterator<const_iterator>;
using node_type = /* unspecified */;
using insert_return_type = /*insert-return-type*/<iterator, node_type>;
class value_compare
{
protected:
Compare comp;
constexpr value_compare(Compare c)
: comp(c)
{
}
public:
constexpr bool operator()(const value_type& x, const value_type& y) const
{
return comp(x.first, y.first);
}
};
// construct/copy/destroy
constexpr map()
: map(Compare())
{
}
constexpr explicit map(const Compare& comp, const Allocator& = Allocator());
template<class InputIter>
constexpr map(InputIter first,
InputIter last,
const Compare& comp = Compare(),
const Allocator& = Allocator());
template<container-compatible-range<value_type> R>
constexpr map(from_range_t,
R&& rg,
const Compare& comp = Compare(),
const Allocator& = Allocator());
constexpr map(const map& x);
constexpr map(map&& x);
constexpr explicit map(const Allocator&);
constexpr map(const map&, const type_identity_t<Allocator>&);
constexpr map(map&&, const type_identity_t<Allocator>&);
constexpr map(initializer_list<value_type>,
const Compare& = Compare(),
const Allocator& = Allocator());
template<class InputIter>
constexpr map(InputIter first, InputIter last, const Allocator& a)
: map(first, last, Compare(), a)
{
}
template<container-compatible-range<value_type> R>
constexpr map(from_range_t, R&& rg, const Allocator& a)
: map(from_range, std::forward<R>(rg), Compare(), a)
{
}
constexpr map(initializer_list<value_type> il, const Allocator& a)
: map(il, Compare(), a)
{
}
constexpr ~map();
constexpr map& operator=(const map& x);
constexpr map& operator=(map&& x) noexcept(
allocator_traits<Allocator>::is_always_equal::value&&
is_nothrow_move_assignable_v<Compare>);
constexpr map& operator=(initializer_list<value_type>);
constexpr allocator_type get_allocator() const noexcept;
// iterators
constexpr iterator begin() noexcept;
constexpr const_iterator begin() const noexcept;
constexpr iterator end() noexcept;
constexpr const_iterator end() const noexcept;
constexpr reverse_iterator rbegin() noexcept;
constexpr const_reverse_iterator rbegin() const noexcept;
constexpr reverse_iterator rend() noexcept;
constexpr const_reverse_iterator rend() const noexcept;
constexpr const_iterator cbegin() const noexcept;
constexpr const_iterator cend() const noexcept;
constexpr const_reverse_iterator crbegin() const noexcept;
constexpr const_reverse_iterator crend() const noexcept;
// capacity
constexpr bool empty() const noexcept;
constexpr size_type size() const noexcept;
constexpr size_type max_size() const noexcept;
// element access
constexpr mapped_type& operator[](const key_type& x);
constexpr mapped_type& operator[](key_type&& x);
template<class K> constexpr mapped_type& operator[](K&& x);
constexpr mapped_type& at(const key_type& x);
constexpr const mapped_type& at(const key_type& x) const;
template<class K> constexpr mapped_type& at(const K& x);
template<class K> constexpr const mapped_type& at(const K& x) const;
// modifiers
template<class... Args> constexpr pair<iterator, bool> emplace(Args&&... args);
template<class... Args>
constexpr iterator emplace_hint(const_iterator position, Args&&... args);
constexpr pair<iterator, bool> insert(const value_type& x);
constexpr pair<iterator, bool> insert(value_type&& x);
template<class P> constexpr pair<iterator, bool> insert(P&& x);
constexpr iterator insert(const_iterator position, const value_type& x);
constexpr iterator insert(const_iterator position, value_type&& x);
template<class P> constexpr iterator insert(const_iterator position, P&&);
template<class InputIter> constexpr void insert(InputIter first, InputIter last);
template<container-compatible-range<value_type> R>
constexpr void insert_range(R&& rg);
constexpr void insert(initializer_list<value_type>);
constexpr node_type extract(const_iterator position);
constexpr node_type extract(const key_type& x);
template<class K> constexpr node_type extract(K&& x);
constexpr insert_return_type insert(node_type&& nh);
constexpr iterator insert(const_iterator hint, node_type&& nh);
template<class... Args>
constexpr pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);
template<class... Args>
constexpr pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);
template<class K, class... Args>
constexpr pair<iterator, bool> try_emplace(K&& k, Args&&... args);
template<class... Args>
constexpr iterator try_emplace(const_iterator hint,
const key_type& k,
Args&&... args);
template<class... Args>
constexpr iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);
template<class K, class... Args>
constexpr iterator try_emplace(const_iterator hint, K&& k, Args&&... args);
template<class M>
constexpr pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);
template<class M>
constexpr pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);
template<class K, class M>
constexpr pair<iterator, bool> insert_or_assign(K&& k, M&& obj);
template<class M>
constexpr iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);
template<class M>
constexpr iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);
template<class K, class M>
constexpr iterator insert_or_assign(const_iterator hint, K&& k, M&& obj);
constexpr iterator erase(iterator position);
constexpr iterator erase(const_iterator position);
constexpr size_type erase(const key_type& x);
template<class K> constexpr size_type erase(K&& x);
constexpr iterator erase(const_iterator first, const_iterator last);
constexpr void swap(map&) noexcept(
allocator_traits<Allocator>::is_always_equal::value&&
is_nothrow_swappable_v<Compare>);
constexpr void clear() noexcept;
template<class C2> constexpr void merge(map<Key, T, C2, Allocator>& source);
template<class C2> constexpr void merge(map<Key, T, C2, Allocator>&& source);
template<class C2> constexpr void merge(multimap<Key, T, C2, Allocator>& source);
template<class C2> constexpr void merge(multimap<Key, T, C2, Allocator>&& source);
// observers
constexpr key_compare key_comp() const;
constexpr value_compare value_comp() const;
// map operations
constexpr iterator find(const key_type& x);
constexpr const_iterator find(const key_type& x) const;
template<class K> constexpr iterator find(const K& x);
template<class K> constexpr const_iterator find(const K& x) const;
constexpr size_type count(const key_type& x) const;
template<class K> constexpr size_type count(const K& x) const;
constexpr bool contains(const key_type& x) const;
template<class K> constexpr bool contains(const K& x) const;
constexpr iterator lower_bound(const key_type& x);
constexpr const_iterator lower_bound(const key_type& x) const;
template<class K> constexpr iterator lower_bound(const K& x);
template<class K> constexpr const_iterator lower_bound(const K& x) const;
constexpr iterator upper_bound(const key_type& x);
constexpr const_iterator upper_bound(const key_type& x) const;
template<class K> constexpr iterator upper_bound(const K& x);
template<class K> constexpr const_iterator upper_bound(const K& x) const;
constexpr pair<iterator, iterator> equal_range(const key_type& x);
constexpr pair<const_iterator, const_iterator> equal_range(const key_type& x) const;
template<class K> constexpr pair<iterator, iterator> equal_range(const K& x);
template<class K>
constexpr pair<const_iterator, const_iterator> equal_range(const K& x) const;
};
template<class InputIter,
class Compare = less</*iter-key-type*/<InputIter>>,
class Allocator = allocator</*iter-to-alloc-type*/<InputIter>>>
map(InputIter, InputIter, Compare = Compare(), Allocator = Allocator())
-> map</*iter-key-type*/<InputIter>,
/*iter-mapped-type*/<InputIter>,
Compare,
Allocator>;
template<ranges::input_range R,
class Compare = less</*range-key-type*/<R>>,
class Allocator = allocator</*range-to-alloc-type*/<R>>>
map(from_range_t, R&&, Compare = Compare(), Allocator = Allocator())
-> map</*range-key-type*/<R>, /*range-mapped-type*/<R>, Compare, Allocator>;
template<class Key,
class T,
class Compare = less<Key>,
class Allocator = allocator<pair<const Key, T>>>
map(initializer_list<pair<Key, T>>, Compare = Compare(), Allocator = Allocator())
-> map<Key, T, Compare, Allocator>;
template<class InputIter, class Allocator>
map(InputIter, InputIter, Allocator) -> map</*iter-key-type*/<InputIter>,
/*iter-mapped-type*/<InputIter>,
less</*iter-key-type*/<InputIter>>,
Allocator>;
template<ranges::input_range R, class Allocator>
map(from_range_t, R&&, Allocator) -> map</*range-key-type*/<R>,
/*range-mapped-type*/<R>,
less</*range-key-type*/<R>>,
Allocator>;
template<class Key, class T, class Allocator>
map(initializer_list<pair<Key, T>>, Allocator) -> map<Key, T, less<Key>, Allocator>;
}
Class template std::multimap
namespace std {
template<class Key,
class T,
class Compare = less<Key>,
class Allocator = allocator<pair<const Key, T>>>
class multimap
{
public:
// types
using key_type = Key;
using mapped_type = T;
using value_type = pair<const Key, T>;
using key_compare = Compare;
using allocator_type = Allocator;
using pointer = allocator_traits<Allocator>::pointer;
using const_pointer = allocator_traits<Allocator>::const_pointer;
using reference = value_type&;
using const_reference = const value_type&;
using size_type = /* implementation-defined */;
using difference_type = /* implementation-defined */;
using iterator = /* implementation-defined */;
using const_iterator = /* implementation-defined */;
using reverse_iterator = std::reverse_iterator<iterator>;
using const_reverse_iterator = std::reverse_iterator<const_iterator>;
using node_type = /* unspecified */;
class value_compare
{
protected:
Compare comp;
constexpr value_compare(Compare c)
: comp(c)
{
}
public:
constexpr bool operator()(const value_type& x, const value_type& y) const
{
return comp(x.first, y.first);
}
};
// construct/copy/destroy
constexpr multimap()
: multimap(Compare())
{
}
constexpr explicit multimap(const Compare& comp, const Allocator& = Allocator());
template<class InputIter>
constexpr multimap(InputIter first,
InputIter last,
const Compare& comp = Compare(),
const Allocator& = Allocator());
template<container-compatible-range<value_type> R>
constexpr multimap(from_range_t,
R&& rg,
const Compare& comp = Compare(),
const Allocator& = Allocator());
constexpr multimap(const multimap& x);
constexpr multimap(multimap&& x);
constexpr explicit multimap(const Allocator&);
constexpr multimap(const multimap&, const type_identity_t<Allocator>&);
constexpr multimap(multimap&&, const type_identity_t<Allocator>&);
constexpr multimap(initializer_list<value_type>,
const Compare& = Compare(),
const Allocator& = Allocator());
template<class InputIter>
constexpr multimap(InputIter first, InputIter last, const Allocator& a)
: multimap(first, last, Compare(), a)
{
}
template<container-compatible-range<value_type> R>
constexpr multimap(from_range_t, R&& rg, const Allocator& a)
: multimap(from_range, std::forward<R>(rg), Compare(), a)
{
}
constexpr multimap(initializer_list<value_type> il, const Allocator& a)
: multimap(il, Compare(), a)
{
}
constexpr ~multimap();
constexpr multimap& operator=(const multimap& x);
constexpr multimap& operator=(multimap&& x) noexcept(
allocator_traits<Allocator>::is_always_equal::value&&
is_nothrow_move_assignable_v<Compare>);
constexpr multimap& operator=(initializer_list<value_type>);
constexpr allocator_type get_allocator() const noexcept;
// iterators
constexpr iterator begin() noexcept;
constexpr const_iterator begin() const noexcept;
constexpr iterator end() noexcept;
constexpr const_iterator end() const noexcept;
constexpr reverse_iterator rbegin() noexcept;
constexpr const_reverse_iterator rbegin() const noexcept;
constexpr reverse_iterator rend() noexcept;
constexpr const_reverse_iterator rend() const noexcept;
constexpr const_iterator cbegin() const noexcept;
constexpr const_iterator cend() const noexcept;
constexpr const_reverse_iterator crbegin() const noexcept;
constexpr const_reverse_iterator crend() const noexcept;
// capacity
constexpr bool empty() const noexcept;
constexpr size_type size() const noexcept;
constexpr size_type max_size() const noexcept;
// modifiers
template<class... Args> constexpr iterator emplace(Args&&... args);
template<class... Args>
constexpr iterator emplace_hint(const_iterator position, Args&&... args);
constexpr iterator insert(const value_type& x);
constexpr iterator insert(value_type&& x);
template<class P> constexpr iterator insert(P&& x);
constexpr iterator insert(const_iterator position, const value_type& x);
constexpr iterator insert(const_iterator position, value_type&& x);
template<class P> constexpr iterator insert(const_iterator position, P&& x);
template<class InputIter> constexpr void insert(InputIter first, InputIter last);
template<container-compatible-range<value_type> R>
constexpr void insert_range(R&& rg);
constexpr void insert(initializer_list<value_type>);
constexpr node_type extract(const_iterator position);
constexpr node_type extract(const key_type& x);
template<class K> node_type extract(K&& x);
constexpr iterator insert(node_type&& nh);
constexpr iterator insert(const_iterator hint, node_type&& nh);
constexpr iterator erase(iterator position);
constexpr iterator erase(const_iterator position);
constexpr size_type erase(const key_type& x);
template<class K> constexpr size_type erase(K&& x);
constexpr iterator erase(const_iterator first, const_iterator last);
constexpr void swap(multimap&) noexcept(
allocator_traits<Allocator>::is_always_equal::value&&
is_nothrow_swappable_v<Compare>);
constexpr void clear() noexcept;
template<class C2> constexpr void merge(multimap<Key, T, C2, Allocator>& source);
template<class C2> constexpr void merge(multimap<Key, T, C2, Allocator>&& source);
template<class C2> constexpr void merge(map<Key, T, C2, Allocator>& source);
template<class C2> constexpr void merge(map<Key, T, C2, Allocator>&& source);
// observers
constexpr key_compare key_comp() const;
constexpr value_compare value_comp() const;
// map operations
constexpr iterator find(const key_type& x);
constexpr const_iterator find(const key_type& x) const;
template<class K> constexpr iterator find(const K& x);
template<class K> constexpr const_iterator find(const K& x) const;
constexpr size_type count(const key_type& x) const;
template<class K> constexpr size_type count(const K& x) const;
constexpr bool contains(const key_type& x) const;
template<class K> constexpr bool contains(const K& x) const;
constexpr iterator lower_bound(const key_type& x);
constexpr const_iterator lower_bound(const key_type& x) const;
template<class K> constexpr iterator lower_bound(const K& x);
template<class K> constexpr const_iterator lower_bound(const K& x) const;
constexpr iterator upper_bound(const key_type& x);
constexpr const_iterator upper_bound(const key_type& x) const;
template<class K> constexpr iterator upper_bound(const K& x);
template<class K> constexpr const_iterator upper_bound(const K& x) const;
constexpr pair<iterator, iterator> equal_range(const key_type& x);
constexpr pair<const_iterator, const_iterator> equal_range(const key_type& x) const;
template<class K> constexpr pair<iterator, iterator> equal_range(const K& x);
template<class K>
constexpr pair<const_iterator, const_iterator> equal_range(const K& x) const;
};
template<class InputIter,
class Compare = less</*iter-key-type*/<InputIter>>,
class Allocator = allocator</*iter-to-alloc-type*/<InputIter>>>
multimap(InputIter, InputIter, Compare = Compare(), Allocator = Allocator())
-> multimap</*iter-key-type*/<InputIter>,
/*iter-mapped-type*/<InputIter>,
Compare,
Allocator>;
template<ranges::input_range R,
class Compare = less</*range-key-type*/<R>>,
class Allocator = allocator</*range-to-alloc-type*/<R>>>
multimap(from_range_t, R&&, Compare = Compare(), Allocator = Allocator())
-> multimap</*range-key-type*/<R>, /*range-mapped-type*/<R>, Compare, Allocator>;
template<class Key,
class T,
class Compare = less<Key>,
class Allocator = allocator<pair<const Key, T>>>
multimap(initializer_list<pair<Key, T>>, Compare = Compare(), Allocator = Allocator())
-> multimap<Key, T, Compare, Allocator>;
template<class InputIter, class Allocator>
multimap(InputIter, InputIter, Allocator)
-> multimap</*iter-key-type*/<InputIter>,
/*iter-mapped-type*/<InputIter>,
less</*iter-key-type*/<InputIter>>,
Allocator>;
template<ranges::input_range R, class Allocator>
multimap(from_range_t, R&&, Allocator) -> multimap</*range-key-type*/<R>,
/*range-mapped-type*/<R>,
less</*range-key-type*/<R>>,
Allocator>;
template<class Key, class T, class Allocator>
multimap(initializer_list<pair<Key, T>>, Allocator)
-> multimap<Key, T, less<Key>, Allocator>;
}
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 133 | C++98 | map::get_allocator was missing in the synopsis | added |