# 标准库头文件 <map>

< cpp‎ | header

此头文件是容器库的一部分。

### 包含
<compare> (C++20) | 三路比较运算符支持
<initializer_list> (C++11) | std::initializer_list 类模板
### 类
map | 键值对的集合，按照键排序，键是唯一的 (类模板)
multimap | 键值对的集合，按照键排序 (类模板)
### 函数
operator==operator!=operator<operator<=operator>operator>=operator<=> (C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20) | 按照字典顺序比较 map 中的值 (函数模板)
std::swap(std::map) | 特化 std::swap 算法 (函数模板)
erase_if(std::map) (C++20) | 擦除所有满足特定判别标准的元素 (函数模板)
operator==operator!=operator<operator<=operator>operator>=operator<=> (C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20 中移除)(C++20) | 按照字典顺序比较 multimap 中的值 (函数模板)
std::swap(std::multimap) | 特化 std::swap 算法 (函数模板)
erase_if(std::multimap) (C++20) | 擦除所有满足特定判别标准的元素 (函数模板)
##### 范围访问
begin cbegin (C++11)(C++14) | 返回指向容器或数组起始的迭代器 (函数模板)
end cend (C++11)(C++14) | 返回指向容器或数组结尾的迭代器 (函数模板)
rbegin crbegin (C++14) | 返回指向一个容器或数组的逆向迭代器 (函数模板)
rend crend (C++14) | 返回容器或数组的逆向尾迭代器 (函数模板)
size ssize (C++17)(C++20) | 返回容器或数组的大小 (函数模板)
empty (C++17) | 检查容器是否为空 (函数模板)
data (C++17) | 获得指向底层数组的指针 (函数模板)

### 概要

    #include <compare>
    #include <initializer_list>

    namespace std {
      // 类模板 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>
        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>
        /*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>
        void swap(map<Key, T, Compare, Allocator>& x,
                  map<Key, T, Compare, Allocator>& y)
          noexcept(noexcept(x.swap(y)));

      template<class Key, class T, class Compare, class Allocator, class Predicate>
        typename map<Key, T, Compare, Allocator>::size_type
          erase_if(map<Key, T, Compare, Allocator>& c, Predicate pred);

      // 类模板 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>
        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>
        /*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>
        void swap(multimap<Key, T, Compare, Allocator>& x,
                  multimap<Key, T, Compare, Allocator>& y)
          noexcept(noexcept(x.swap(y)));

      template<class Key, class T, class Compare, class Allocator, class Predicate>
        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>>>;
      }
    }

#### 类模板 std::map

    namespace std {
      template<class Key, class T, class Compare = less<Key>,
               class Allocator = allocator<pair<const Key, T>>>
      class map {
      public:
        // 类型
        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                = typename allocator_traits<Allocator>::pointer;
        using const_pointer          = typename allocator_traits<Allocator>::const_pointer;
        using reference              = value_type&;
        using const_reference        = const value_type&;
        using size_type              = /* 由实现定义 */;
        using difference_type        = /* 由实现定义 */;
        using iterator               = /* 由实现定义 */;
        using const_iterator         = /* 由实现定义 */;
        using reverse_iterator       = std::reverse_iterator<iterator>;
        using const_reverse_iterator = std::reverse_iterator<const_iterator>;
        using node_type              = /* 未指明 */;
        using insert_return_type     = /*insert-return-type*/<iterator, node_type>;

        class value_compare {
          friend class map;
        protected:
          Compare comp;
          value_compare(Compare c) : comp(c) {}
        public:
          bool operator()(const value_type& x, const value_type& y) const {
            return comp(x.first, y.first);
          }
        };

        // 构造/复制/销毁
        map() : map(Compare()) { }
        explicit map(const Compare& comp, const Allocator& = Allocator());
        template<class InputIt>
          map(InputIt first, InputIt last,
              const Compare& comp = Compare(), const Allocator& = Allocator());
        map(const map& x);
        map(map&& x);
        explicit map(const Allocator&);
        map(const map&, const Allocator&);
        map(map&&, const Allocator&);
        map(initializer_list<value_type>,
          const Compare& = Compare(),
          const Allocator& = Allocator());
        template<class InputIt>
          map(InputIt first, InputIt last, const Allocator& a)
            : map(first, last, Compare(), a) { }
        map(initializer_list<value_type> il, const Allocator& a)
          : map(il, Compare(), a) { }
        ~map();
        map& operator=(const map& x);
        map& operator=(map&& x)
          noexcept(allocator_traits<Allocator>::is_always_equal::value &&
                   is_nothrow_move_assignable_v<Compare>);
        map& operator=(initializer_list<value_type>);
        allocator_type get_allocator() const noexcept;

        // 迭代器
        iterator               begin() noexcept;
        const_iterator         begin() const noexcept;
        iterator               end() noexcept;
        const_iterator         end() const noexcept;

        reverse_iterator       rbegin() noexcept;
        const_reverse_iterator rbegin() const noexcept;
        reverse_iterator       rend() noexcept;
        const_reverse_iterator rend() const noexcept;

        const_iterator         cbegin() const noexcept;
        const_iterator         cend() const noexcept;
        const_reverse_iterator crbegin() const noexcept;
        const_reverse_iterator crend() const noexcept;

        // 容量
        [[nodiscard]] bool empty() const noexcept;
        size_type size() const noexcept;
        size_type max_size() const noexcept;

        // 元素访问
        mapped_type& operator[](const key_type& x);
        mapped_type& operator[](key_type&& x);
        mapped_type&       at(const key_type& x);
        const mapped_type& at(const key_type& x) const;

        // 修改器
        template<class... Args> pair<iterator, bool> emplace(Args&&... args);
        template<class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
        pair<iterator, bool> insert(const value_type& x);
        pair<iterator, bool> insert(value_type&& x);
        template<class P> pair<iterator, bool> insert(P&& x);
        iterator insert(const_iterator position, const value_type& x);
        iterator insert(const_iterator position, value_type&& x);
        template<class P>
          iterator insert(const_iterator position, P&&);
        template<class InputIt>
          void insert(InputIt first, InputIt last);
        void insert(initializer_list<value_type>);

        node_type extract(const_iterator position);
        node_type extract(const key_type& x);
        template<class K> node_type extract(K&& x);
        insert_return_type insert(node_type&& nh);
        iterator           insert(const_iterator hint, node_type&& nh);

        template<class... Args>
          pair<iterator, bool> try_emplace(const key_type& k, Args&&... args);
        template<class... Args>
          pair<iterator, bool> try_emplace(key_type&& k, Args&&... args);
        template<class... Args>
          iterator try_emplace(const_iterator hint, const key_type& k, Args&&... args);
        template<class... Args>
          iterator try_emplace(const_iterator hint, key_type&& k, Args&&... args);
        template<class M>
          pair<iterator, bool> insert_or_assign(const key_type& k, M&& obj);
        template<class M>
          pair<iterator, bool> insert_or_assign(key_type&& k, M&& obj);
        template<class M>
          iterator insert_or_assign(const_iterator hint, const key_type& k, M&& obj);
        template<class M>
          iterator insert_or_assign(const_iterator hint, key_type&& k, M&& obj);

        iterator  erase(iterator position);
        iterator  erase(const_iterator position);
        size_type erase(const key_type& x);
        template<class K> size_type erase(K&& x);
        iterator  erase(const_iterator first, const_iterator last);
        void      swap(map&)
          noexcept(allocator_traits<Allocator>::is_always_equal::value &&
                   is_nothrow_swappable_v<Compare>);
        void      clear() noexcept;

        template<class C2>
          void merge(map<Key, T, C2, Allocator>& source);
        template<class C2>
          void merge(map<Key, T, C2, Allocator>&& source);
        template<class C2>
          void merge(multimap<Key, T, C2, Allocator>& source);
        template<class C2>
          void merge(multimap<Key, T, C2, Allocator>&& source);

        // 观察器
        key_compare key_comp() const;
        value_compare value_comp() const;

        // map 操作
        iterator       find(const key_type& x);
        const_iterator find(const key_type& x) const;
        template<class K> iterator       find(const K& x);
        template<class K> const_iterator find(const K& x) const;

        size_type      count(const key_type& x) const;
        template<class K> size_type count(const K& x) const;

        bool           contains(const key_type& x) const;
        template<class K> bool contains(const K& x) const;

        iterator       lower_bound(const key_type& x);
        const_iterator lower_bound(const key_type& x) const;
        template<class K> iterator       lower_bound(const K& x);
        template<class K> const_iterator lower_bound(const K& x) const;

        iterator       upper_bound(const key_type& x);
        const_iterator upper_bound(const key_type& x) const;
        template<class K> iterator       upper_bound(const K& x);
        template<class K> const_iterator upper_bound(const K& x) const;

        pair<iterator, iterator>               equal_range(const key_type& x);
        pair<const_iterator, const_iterator>   equal_range(const key_type& x) const;
        template<class K>
          pair<iterator, iterator>             equal_range(const K& x);
        template<class K>
          pair<const_iterator, const_iterator> equal_range(const K& x) const;
      };

      template<class InputIt, class Compare = less</*iter-key-type*/<InputIt>>,
               class Allocator = allocator</*iter-to-alloc-type*/<InputIt>>>
        map(InputIt, InputIt, Compare = Compare(), Allocator = Allocator())
          -> map</*iter-key-type*/<InputIt>, /*iter-mapped-type*/<InputIt>,
                 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 InputIt, class Allocator>
        map(InputIt, InputIt, Allocator)
          -> map</*iter-key-type*/<InputIt>, /*iter-mapped-type*/<InputIt>,
                 less</*iter-key-type*/<InputIt>>, Allocator>;

      template<class Key, class T, class Allocator>
        map(initializer_list<pair<Key, T>>, Allocator) -> map<Key, T, less<Key>, Allocator>;

      // 交换
      template<class Key, class T, class Compare, class Allocator>
        void swap(map<Key, T, Compare, Allocator>& x,
                  map<Key, T, Compare, Allocator>& y)
          noexcept(noexcept(x.swap(y)));
    }

#### 类模板 std::multimap

    namespace std {
      template<class Key, class T, class Compare = less<Key>,
               class Allocator = allocator<pair<const Key, T>>>
      class multimap {
      public:
        // 类型
        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                = typename allocator_traits<Allocator>::pointer;
        using const_pointer          = typename allocator_traits<Allocator>::const_pointer;
        using reference              = value_type&;
        using const_reference        = const value_type&;
        using size_type              = /* 由实现定义 */;
        using difference_type        = /* 由实现定义 */;
        using iterator               = /* 由实现定义 */;
        using const_iterator         = /* 由实现定义 */;
        using reverse_iterator       = std::reverse_iterator<iterator>;
        using const_reverse_iterator = std::reverse_iterator<const_iterator>;
        using node_type              = /* 未指明 */;

        class value_compare {
          friend class multimap;
        protected:
          Compare comp;
          value_compare(Compare c) : comp(c) { }
        public:
          bool operator()(const value_type& x, const value_type& y) const {
            return comp(x.first, y.first);
          }
        };

        // 构造/复制/销毁
        multimap() : multimap(Compare()) { }
        explicit multimap(const Compare& comp, const Allocator& = Allocator());
        template<class InputIt>
          multimap(InputIt first, InputIt last,
                   const Compare& comp = Compare(),
                   const Allocator& = Allocator());
        multimap(const multimap& x);
        multimap(multimap&& x);
        explicit multimap(const Allocator&);
        multimap(const multimap&, const Allocator&);
        multimap(multimap&&, const Allocator&);
        multimap(initializer_list<value_type>,
          const Compare& = Compare(),
          const Allocator& = Allocator());
        template<class InputIt>
          multimap(InputIt first, InputIt last, const Allocator& a)
            : multimap(first, last, Compare(), a) { }
        multimap(initializer_list<value_type> il, const Allocator& a)
          : multimap(il, Compare(), a) { }
        ~multimap();
        multimap& operator=(const multimap& x);
        multimap& operator=(multimap&& x)
          noexcept(allocator_traits<Allocator>::is_always_equal::value &&
                   is_nothrow_move_assignable_v<Compare>);
        multimap& operator=(initializer_list<value_type>);
        allocator_type get_allocator() const noexcept;

        // 迭代器
        iterator               begin() noexcept;
        const_iterator         begin() const noexcept;
        iterator               end() noexcept;
        const_iterator         end() const noexcept;

        reverse_iterator       rbegin() noexcept;
        const_reverse_iterator rbegin() const noexcept;
        reverse_iterator       rend() noexcept;
        const_reverse_iterator rend() const noexcept;

        const_iterator         cbegin() const noexcept;
        const_iterator         cend() const noexcept;
        const_reverse_iterator crbegin() const noexcept;
        const_reverse_iterator crend() const noexcept;

        // 容量
        [[nodiscard]] bool empty() const noexcept;
        size_type size() const noexcept;
        size_type max_size() const noexcept;

        // 修改器
        template<class... Args> iterator emplace(Args&&... args);
        template<class... Args> iterator emplace_hint(const_iterator position, Args&&... args);
        iterator insert(const value_type& x);
        iterator insert(value_type&& x);
        template<class P> iterator insert(P&& x);
        iterator insert(const_iterator position, const value_type& x);
        iterator insert(const_iterator position, value_type&& x);
        template<class P> iterator insert(const_iterator position, P&& x);
        template<class InputIt>
          void insert(InputIt first, InputIt last);
        void insert(initializer_list<value_type>);

        node_type extract(const_iterator position);
        node_type extract(const key_type& x);
        template<class K> node_type extract(K&& x);
        iterator insert(node_type&& nh);
        iterator insert(const_iterator hint, node_type&& nh);

        iterator  erase(iterator position);
        iterator  erase(const_iterator position);
        size_type erase(const key_type& x);
        template<class K> size_type erase(K&& x);
        iterator  erase(const_iterator first, const_iterator last);
        void      swap(multimap&)
          noexcept(allocator_traits<Allocator>::is_always_equal::value &&
                   is_nothrow_swappable_v<Compare>);
        void      clear() noexcept;

        template<class C2>
          void merge(multimap<Key, T, C2, Allocator>& source);
        template<class C2>
          void merge(multimap<Key, T, C2, Allocator>&& source);
        template<class C2>
          void merge(map<Key, T, C2, Allocator>& source);
        template<class C2>
          void merge(map<Key, T, C2, Allocator>&& source);

        // 观察器
        key_compare key_comp() const;
        value_compare value_comp() const;

        // map 操作
        iterator       find(const key_type& x);
        const_iterator find(const key_type& x) const;
        template<class K> iterator       find(const K& x);
        template<class K> const_iterator find(const K& x) const;

        size_type      count(const key_type& x) const;
        template<class K> size_type count(const K& x) const;

        bool           contains(const key_type& x) const;
        template<class K> bool contains(const K& x) const;

        iterator       lower_bound(const key_type& x);
        const_iterator lower_bound(const key_type& x) const;
        template<class K> iterator       lower_bound(const K& x);
        template<class K> const_iterator lower_bound(const K& x) const;

        iterator       upper_bound(const key_type& x);
        const_iterator upper_bound(const key_type& x) const;
        template<class K> iterator       upper_bound(const K& x);
        template<class K> const_iterator upper_bound(const K& x) const;

        pair<iterator, iterator>               equal_range(const key_type& x);
        pair<const_iterator, const_iterator>   equal_range(const key_type& x) const;
        template<class K>
          pair<iterator, iterator>             equal_range(const K& x);
        template<class K>
          pair<const_iterator, const_iterator> equal_range(const K& x) const;
      };

      template<class InputIt, class Compare = less</*iter-key-type*/<InputIt>>,
               class Allocator = allocator</*iter-to-alloc-type*/<InputIt>>>
        multimap(InputIt, InputIt, Compare = Compare(), Allocator = Allocator())
          -> multimap</*iter-key-type*/<InputIt>, /*iter-mapped-type*/<InputIt>,
                      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 InputIt, class Allocator>
        multimap(InputIt, InputIt, Allocator)
          -> multimap</*iter-key-type*/<InputIt>, /*iter-mapped-type*/<InputIt>,
                      less</*iter-key-type*/<InputIt>>, Allocator>;

      template<class Key, class T, class Allocator>
        multimap(initializer_list<pair<Key, T>>, Allocator)
          -> multimap<Key, T, less<Key>, Allocator>;

      // 交换
      template<class Key, class T, class Compare, class Allocator>
        void swap(multimap<Key, T, Compare, Allocator>& x,
                  multimap<Key, T, Compare, Allocator>& y)
          noexcept(noexcept(x.swap(y)));
    }