Namespaces
Variants

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

From cppreference.net
std:: pair < iterator, bool > insert ( const value_type & value ) ;
(1)
template < class P >
std:: pair < iterator, bool > insert ( P && value ) ;
(2) (C++11以降)
std:: pair < iterator, bool > insert ( value_type && value ) ;
(3) (C++17以降)
(4)
iterator insert ( iterator pos, const value_type & value ) ;
(C++11以前)
iterator insert ( const_iterator pos, const value_type & value ) ;
(C++11以降)
template < class P >
iterator insert ( const_iterator pos, P && value ) ;
(5) (C++11以降)
iterator insert ( const_iterator pos, value_type && value ) ;
(6) (C++17以降)
template < class InputIt >
void insert ( InputIt first, InputIt last ) ;
(7)
void insert ( std:: initializer_list < value_type > ilist ) ;
(8) (C++11以降)
insert_return_type insert ( node_type && nh ) ;
(9) (C++17以降)
iterator insert ( const_iterator pos, node_type && nh ) ;
(10) (C++17以降)

コンテナに要素を挿入します。ただし、同等のキーを持つ要素が既にコンテナに含まれていない場合に限ります。

1-3) value を挿入します。
オーバーロード (2) emplace ( std:: forward < P > ( value ) ) と等価であり、 std:: is_constructible < value_type, P && > :: value == true の場合にのみオーバーロード解決に参加します。
4-6) value を、 pos の直前の位置にできるだけ近い位置に挿入します。
オーバーロード (5) emplace_hint ( pos, std:: forward < P > ( value ) ) と等価であり、 std:: is_constructible < value_type, P && > :: value == true の場合にのみオーバーロード解決に参加します。
7) 範囲 [ first , last ) から要素を挿入します。範囲内の複数の要素が同等と比較されるキーを持つ場合、どの要素が挿入されるかは未規定です(保留中 LWG2844 )。
8) 初期化子リスト ilist から要素を挿入します。範囲内の複数の要素が同等と比較されるキーを持つ場合、どの要素が挿入されるかは未規定です( LWG2844 未解決)。
9) nh が空の node handle である場合、何も行わない。そうでない場合、コンテナが nh. key ( ) と等価なキーを持つ要素を既に含んでいなければ、 nh が所有する要素をコンテナに挿入する。 nh が空でなく、かつ get_allocator ( ) ! = nh. get_allocator ( ) である場合、動作は未定義である。
10) nh が空の node handle の場合、何もせずに終端イテレータを返す。それ以外の場合、コンテナが nh. key ( ) と等価なキーを持つ要素をまだ含んでいなければ、 nh が所有する要素をコンテナに挿入し、 nh. key ( ) と等価なキーを持つ要素を指すイテレータを返す(挿入が成功したか失敗したかに関わらず)。挿入が成功した場合、 nh は移動され、それ以外の場合は要素の所有権を保持する。要素は pos の直前にできるだけ近い位置に挿入される。 nh が空でなく、かつ get_allocator ( ) ! = nh. get_allocator ( ) の場合、動作は未定義である。

イテレータおよび参照は無効化されません。 挿入が成功した場合、ノードハンドル内に保持されている間に取得された要素へのポインタおよび参照は無効化され、抽出前にその要素に対して取得されたポインタおよび参照は有効になります。 (C++17以降)

目次

パラメータ

pos - 新しい要素が挿入される位置の前を指すイテレータ
value - 挿入する要素の値
first, last - 挿入する要素の 範囲 を定義するイテレータのペア
ilist - 値の挿入元となる初期化子リスト
nh - 互換性のある ノードハンドル
型要件
-
InputIt LegacyInputIterator の要件を満たさなければならない。

戻り値

1-3) 挿入された要素(または挿入を妨げた要素)へのイテレータと、挿入が行われた場合にのみ bool 値が true に設定されるペア。
4-6) 挿入された要素、または挿入を妨げた要素へのイテレータ。
7,8) (なし)
9) insert_return_type のオブジェクトが以下のように初期化されます:
  • nh が空の場合、 inserted false position end ( ) node は空となります。
  • 挿入が行われた場合、 inserted true position は挿入された要素を指し、 node は空となります。
  • 挿入が失敗した場合、 inserted false node nh の前の値を持ち、 position nh. key ( ) と等価なキーを持つ要素を指します。
10) nh が空の場合は終端イテレータ、挿入が行われた場合は挿入された要素を指すイテレータ、失敗した場合は nh. key ( ) と等価なキーを持つ要素を指すイテレータ。

例外

1-6) 例外が任意の操作によってスローされた場合、挿入は無効となります。

計算量

1-3) コンテナのサイズに対して対数的、 O(log(size()))
4-6) 挿入が after (until C++11) before (since C++11) pos の直後の位置で発生する場合は償却定数時間、それ以外の場合はコンテナのサイズに対して対数時間。
7,8) O(N·log(size() + N)) 、ここで N は挿入する要素の数です。
9) コンテナのサイズに対して対数的、 O(log(size()))
10) 挿入が 直前 pos の位置で発生する場合は償却定数時間、それ以外の場合はコンテナのサイズに対して対数時間。

注記

ヒント付き挿入 ( ( 4-6 ) および ( 10 ) )は、 std::vector::insert のようなシーケンシャルコンテナでの位置指定挿入とのシグネチャ互換性を保つため、ブール値を返しません。これにより、 std::inserter のような汎用インサーターを作成することが可能になります。ヒント付き挿入の成功を確認する一つの方法は、挿入前後の size() を比較することです。

#include <iomanip>
#include <iostream>
#include <map>
#include <string>
using namespace std::リテラル;
template<typename It>
void print_insertion_status(It it, bool success)
{
    std::cout << "の挿入" << it->first
              << (success ? " 成功しました\n" : " 失敗しました\n");
}
int main()
{
    std::map<std::string, float> heights;
    // オーバーロード 3: rvalue 参照からの挿入
    const auto [it_hinata, success] = heights.insert({"日向"s, 162.8});
    print_insertion_status(it_hinata, success);
    {
        // オーバーロード 1: lvalue 参照からの挿入
        const auto [it, success2] = heights.insert(*it_hinata);
        print_insertion_status(it, success2);
    }
    {
        // オーバーロード 2: emplaceへの転送による挿入
        const auto [it, success] = heights.insert(std::pair{"影山", 180.6});
        print_insertion_status(it, success);
    }
    {
        // オーバーロード 6: 位置ヒント付き右辺値参照からの挿入
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, {"Azumane"s, 184.7});
        print_insertion_status(it, std::size(heights) != n);
    }
    {
        // オーバーロード 4: 位置ヒント付きで左辺値参照から挿入
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, *it_hinata);
        print_insertion_status(it, std::size(heights) != n);
    }
    {
        // オーバーロード 5: 位置ヒント付き emplace への転送による挿入
        const std::size_t n = std::size(heights);
        const auto it = heights.insert(it_hinata, std::pair{"月島", 188.3});
        print_insertion_status(it, std::size(heights) != n);
    }
    auto node_hinata = heights.extract(it_hinata);
    std::map<std::string, float> heights2;
    // オーバーロード 7: イテレータ範囲からの挿入
    heights2.insert(std::begin(heights), std::end(heights));
    // オーバーロード 8: initializer_list からの挿入
    heights2.insert({{"Kozume"s, 169.2}, {"黒尾", 187.7}});
    // オーバーロード 9: ノードの挿入
    const auto status = heights2.insert(std::move(node_hinata));
    print_insertion_status(status.position, status.inserted);
    node_hinata = heights2.extract(status.position);
    {
        // オーバーロード 10: 位置ヒント付きでノードを挿入
        const std::size_t n = std::size(heights2);
        const auto it = heights2.insert(std::begin(heights2), std::move(node_hinata));
        print_insertion_status(it, std::size(heights2) != n);
    }
    // 結果のマップを出力
    std::cout << std::left << '\n';
    for (const auto& [name, height] : heights2)
        std::cout << std::setw(10) << name << " | " << height << "cm\n";
}

出力:

日向の挿入に成功しました
日向の挿入に失敗しました
影山の挿入に成功しました
東峰の挿入に成功しました
日向の挿入に失敗しました
月島の挿入に成功しました
日向の挿入に成功しました
日向の挿入に成功しました
Azumane    | 184.7cm
Hinata     | 162.8cm
Kageyama   | 180.6cm
Kozume     | 169.2cm
Kuroo      | 187.7cm
Tsukishima | 188.3cm

欠陥報告

以下の動作変更の欠陥報告書は、以前に公開されたC++規格に対して遡及的に適用されました。

DR 適用対象 公開時の動作 正しい動作
LWG 233 C++98 pos は単なるヒントであり、完全に無視される可能性があった 挿入は pos の直前の位置に
可能な限り近くなるように
行われることが要求される
LWG 264 C++98 オーバーロード ( 7 ) の計算量は、範囲 [ first , last ) Compare に従って
ソートされている場合、線形であることが要求されていた
この特別なケースにおける
線形計算量の要件を削除
LWG 316 C++98 オーバーロード ( 1 ) の戻り値において、どの bool 値が
挿入の成功を示すかが規定されていなかった
成功は true によって
示される
LWG 2005 C++11 オーバーロード ( 2 ) ( 5 ) の説明が不十分であった 説明を改善

関連項目

(C++11)
要素をその場で構築する
(公開メンバ関数)
ヒントを使用して要素をその場で構築する
(公開メンバ関数)
要素を挿入するか、キーが既に存在する場合は現在の要素に代入する
(公開メンバ関数)
引数から推論された型の std::insert_iterator を作成する
(関数テンプレート)