Namespaces
Variants

std::multimap<Key,T,Compare,Allocator>:: insert

From cppreference.net
C++
Containers library
std::multimap
Member functions
Non-member functions
Deduction guides (C++17)
iterator insert ( const value_type & value ) ;
(1)
iterator insert ( value_type && value ) ;
(2) (自 C++17 起)
template < class P >
iterator insert ( P && value ) ;
(3) (自 C++11 起)
(4)
iterator insert ( iterator pos, const value_type & value ) ;
(C++11 前)
iterator insert ( const_iterator pos, const value_type & value ) ;
(自 C++11 起)
iterator insert ( const_iterator pos, value_type && value ) ;
(5) (自 C++17 起)
template < class P >
iterator insert ( const_iterator pos, P && value ) ;
(6) (自 C++11 起)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(7)
void insert ( std:: initializer_list < value_type > ilist ) ;
(8) (自 C++11 起)
iterator insert ( node_type && nh ) ;
(9) (自 C++17 起)
iterator insert ( const_iterator pos, node_type && nh ) ;
(10) (自 C++17 起)

向容器中插入元素。

1-3) 插入 value 。若容器已存在等价键的元素，则在该范围的 upper bound 处插入。
重载 (3) 等价于 emplace ( std:: forward < P > ( value ) ) ，且仅当 std:: is_constructible < value_type, P && > :: value == true 时参与重载决议。
4-6) 将 value 插入到尽可能接近 pos 之前位置的位置。
重载 (6) 等价于 emplace_hint ( hint, std:: forward < P > ( value ) ) ，且仅当 std:: is_constructible < value_type, P && > :: value == true 时参与重载决议。
7) 插入来自范围 [ first , last ) 的元素。
8) 从初始化列表 ilist 插入元素。
9) 若 nh 为空 节点句柄 ，则不执行任何操作。否则，将 nh 所拥有的元素插入容器，并返回指向被插入元素的迭代器。若容器中已存在与 nh. key ( ) 等效的键值范围，则该元素将被插入到该范围的末尾。若 nh 非空且 get_allocator ( ) ! = nh. get_allocator ( ) ，则行为未定义。
10) 若 nh 是空 节点句柄 ，则不执行任何操作并返回结束迭代器。否则，将 nh 所拥有的元素插入容器，并返回指向键等价于 nh. key ( ) 的元素的迭代器。该元素会尽可能插入到紧邻 pos 之前的位置。若 nh 非空且 get_allocator ( ) ! = nh. get_allocator ( ) ，则行为未定义。

不会使任何迭代器或引用失效。 若插入成功，则通过节点句柄持有该元素期间获得的指针和引用会失效，而在提取该元素之前获得的指针和引用将变为有效。 (C++17 起)

目录

参数

pos - 指向新元素将插入位置之前的迭代器
value - 要插入的元素值
first, last - 定义要插入元素源 范围 的迭代器对
ilist - 要从中插入值的初始化列表
nh - 兼容的 节点句柄
类型要求
-
InputIt 必须满足 LegacyInputIterator 的要求。

返回值

1-6) 指向被插入元素的迭代器。
7,8) (无)
9,10) 若 nh 为空则返回尾迭代器，否则返回指向被插入元素的迭代器。

异常

1-6) 若任何操作抛出异常，则插入操作无效。
7,8) 不提供异常安全保证。
9,10) 若任何操作抛出异常，则插入操作无效。

复杂度

1-3) O(log(size()))
4-6) 若插入发生在 pos 之前的位置，则摊还常数时间复杂度，否则为 O(log(size())) 。
7,8) O(N·log(size() + N)) ，其中 N 为待插入元素的数量。
9) O(log(size()))
10) 若插入发生在 pos 之前的位置，则摊还常数时间复杂度，否则为 O(log(size())) 。

示例

运行此代码 
#include <functional>
#include <iostream>
#include <map>
#include <string>
#include <string_view>
#include <utility>
template<class M>
void print(const std::string_view rem, const M& mmap)
{
    std::cout << rem << ' ';
    for (const auto& e : mmap)
        std::cout << '{' << e.first << ',' << e.second << "} ";
    std::cout << '\n';
}
int main()
{
    // 列表初始化
    std::multimap<int, std::string, std::greater<int>> mmap
        {{2, "foo"}, {2, "bar"}, {3, "baz"}, {1, "abc"}, {5, "def"}};
    print("#1", mmap);
    // 使用 value_type 插入
    mmap.insert(decltype(mmap)::value_type(5, "pqr"));
    print("#2", mmap);
    // 使用 pair 插入
    mmap.insert(std::pair{6, "uvw"});
    print("#3", mmap);
    mmap.insert({7, "xyz"});
    print("#4", mmap);
    // 使用 initializer_list 插入
    mmap.insert({{5, "one"}, {5, "two"}});
    print("#5", mmap);
    // 使用迭代器对插入
    mmap.clear();
    const auto il = {std::pair{1, "ä"}, {2, "ё"}, {2, "ö"}, {3, "ü"}};
    mmap.insert(il.begin(), il.end());
    print("#6", mmap);
}

输出： 

#1 {5,def} {3,baz} {2,foo} {2,bar} {1,abc}
#2 {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#3 {6,uvw} {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#4 {7,xyz} {6,uvw} {5,def} {5,pqr} {3,baz} {2,foo} {2,bar} {1,abc}
#5 {7,xyz} {6,uvw} {5,def} {5,pqr} {5,one} {5,two} {3,baz} {2,foo} {2,bar} {1,abc}
#6 {3,ü} {2,ё} {2,ö} {1,ä}

缺陷报告

以下行为变更缺陷报告被追溯应用于先前发布的C++标准。

缺陷报告 适用版本 发布时行为 正确行为
LWG 233 C++98 pos 仅是提示，可能被完全忽略 要求插入位置尽可能接近
pos 之前的位置
LWG 264 C++98 若范围 [ first , last ) 按 Compare 排序，
要求重载 (5) 的时间复杂度为线性 		移除此特殊情形下的
线性复杂度要求
LWG 371 C++98 未保证等价元素的顺序稳定性 要求保持等价元素顺序
LWG 2005 C++11 重载 (3,6) 的描述存在缺陷 改进了描述

参见

(C++11)
原位构造元素
(公开成员函数)
(C++11)
使用提示原位构造元素
(公开成员函数)
创建从参数推断类型的 std::insert_iterator
(函数模板)