名稱空間
變體
操作

std::set<Key,Compare,Allocator>::insert

來自 cppreference.com
< cpp‎ | 容器‎ | set
 
C++
 
容器庫
 
std::set
 
std::pair<iterator, bool> insert( const value_type& value );
 (1)
std::pair<iterator, bool> insert( value_type&& value );
 (2) (C++11 起)
(3)
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 );
 (4) (C++11 起)
template< class InputIt >
void insert( InputIt first, InputIt last );
 (5)
void insert( std::initializer_list<value_type> ilist );
 (6) (C++11 起)
insert_return_type insert( node_type&& nh );
 (7) (C++17 起)
iterator insert( const_iterator pos, node_type&& nh );
 (8) (C++17 起)
template< class K >
std::pair<iterator, bool> insert( K&& x );
 (9) (C++23 起)
template< class K >
iterator insert( const_iterator pos, K&& x );
 (10) (C++23 起)

如果容器中尚不包含具有等效鍵的元素，則將元素插入容器中。

1,2) 插入 value。
3,4) 將 value 插入到儘可能接近 pos 緊前位置處。
5) 插入範圍 [first, last) 中的元素。如果範圍中的多個元素具有等效鍵，則插入哪個元素是未指定的（待處理 LWG2844）。
6) 從初始化列表 ilist 插入元素。如果範圍中的多個元素具有等效鍵，則插入哪個元素是未指定的（待處理 LWG2844）。
7) 如果 nh 是空 節點控制代碼，則不執行任何操作。否則，如果容器中尚不包含與 nh.key() 等效的鍵，則將 nh 擁有的元素插入容器。如果 nh 不為空且 get_allocator() != nh.get_allocator()，則行為未定義。
8) 如果 nh 是空 節點控制代碼，則不執行任何操作並返回末尾迭代器。否則，如果容器中尚不包含與 nh.key() 等效的鍵，則將 nh 擁有的元素插入容器，並返回指向與 nh.key() 等效的鍵的元素的迭代器（無論插入成功還是失敗）。如果插入成功，則從 nh 移動；否則，它保留對元素的擁有權。該元素插入到儘可能接近 pos 緊前位置處。如果 nh 不為空且 get_allocator() != nh.get_allocator()，則行為未定義。
9) 如果 *this 已包含與 x 透明比較等效的元素，則不執行任何操作。否則，使用 std::forward<K>(x) 構造一個 value_type 的物件 u，然後將 u 插入到 *this 中。如果 equal_range(u) == equal_range(x) 為 false，則行為未定義。value_type 必須能從 std::forward<K>(x) 就地構造到 set 中。此過載僅當限定 ID Compare::is_transparent 有效且表示一個型別時才參與過載決議。它允許在不構造 Key 例項的情況下呼叫此函式。
10) 如果 *this 已包含與 x 透明比較等效的元素，則不執行任何操作。否則，使用 std::forward<K>(x) 構造一個 value_type 的物件 u，然後將 u 插入到 *this 中，位置儘可能接近 pos 緊前的位置。如果 equal_range(u) == equal_range(x) 為 false，則行為未定義。value_type 必須能從 std::forward<K>(x) 就地構造到 set 中。此過載僅當以下條件成立時才參與過載決議：這些條件共同允許在不構造 Key 例項的情況下呼叫此函式。

沒有迭代器或引用失效。如果插入成功，在節點控制代碼中持有元素時獲得的指向該元素的指標和引用將失效，並且在提取之前獲得的指向該元素的指標和引用將變為有效。(C++17 起)

目錄

[編輯] 引數

pos - 指向新元素將插入位置之前的迭代器
value - 要插入的元素值
first, last - 定義要插入的元素源範圍的迭代器對
ilist - 要從中插入值的初始化列表
nh - 相容的節點控制代碼
x - 可與鍵透明比較的任何型別的值
型別要求
-
InputIt 必須滿足 LegacyInputIterator 的要求。

[編輯] 返回值

1,2) 一個對，包含指向插入元素的迭代器（或指向阻止插入的元素的迭代器）和一個布林值，當且僅當插入發生時設定為 true。
3,4) 指向插入元素的迭代器，或指向阻止插入的元素的迭代器。
5,6) (無)
7) 一個 insert_return_type 物件，其成員初始化如下：
  • 如果 nh 為空，則 inserted 為 false，position 為 end()，且 node 為空。
  • 否則，如果插入發生，則 inserted 為 true，position 指向插入的元素，且 node 為空。
  • 如果插入失敗，則 inserted 為 false，node 具有 nh 的先前值，且 position 指向具有與 nh.key() 等效的鍵的元素。
8) 如果 nh 為空，則為末尾迭代器；如果插入發生，則為指向插入元素的迭代器；如果插入失敗，則為指向具有與 nh.key() 等效的鍵的元素的迭代器。
9) 一個對，包含指向插入元素的迭代器（或指向阻止插入的元素的迭代器）和一個布林值，當且僅當插入發生時設定為 true。
10) 指向插入元素的迭代器，或指向阻止插入的元素的迭代器。

[編輯] 異常

1-4) 如果任何操作丟擲異常，則插入無效。
本節不完整
原因：情況 5-8, 9, 10

[編輯] 複雜度

1,2) 對容器大小呈對數，O(log(size()))。
3,4) 如果插入發生在 pos 緊後(C++11 前)前(C++11 起)的位置，則為均攤常數；否則為容器大小的對數。
5,6) O(N·log(size() + N))，其中 N 是要插入的元素數量。
7) 對容器大小呈對數，O(log(size()))。
8) 如果插入發生在 pos 緊前的位置，則為均攤常數；否則為容器大小的對數。
9) 對容器大小呈對數，O(log(size()))。
10) 如果插入發生在 pos 緊前的位置，則為均攤常數；否則為容器大小的對數。

[編輯] 注意

提示插入 (3,4) 不返回布林值，以便與順序容器（例如 std::vector::insert）上的位置插入具有簽名相容性。這使得建立泛型插入器（例如 std::inserter）成為可能。檢查提示插入成功的一種方法是比較 size() 前後。

過載 (5,6) 通常實現為一個迴圈，該迴圈使用 end() 作為提示呼叫過載 (3)；它們針對追加已排序序列（例如另一個 std::set），其最小元素大於 *this 中的最後一個元素進行了最佳化。

特性測試宏 值 標準 特性
__cpp_lib_associative_heterogeneous_insertion 202311L (C++26) 有序和無序關聯容器中其餘成員函式的異構過載。(9,10)

[編輯] 示例

執行此程式碼
#include <cassert>
#include <iostream>
#include <set>
 
int main()
{
    std::set<int> set;
 
    auto result_1 = set.insert(3);
    assert(result_1.first != set.end()); // it is a valid iterator
    assert(*result_1.first == 3);
    if (result_1.second)
        std::cout << "insert done\n";
 
    auto result_2 = set.insert(3);
    assert(result_2.first == result_1.first); // same iterator
    assert(*result_2.first == 3);
    if (!result_2.second)
        std::cout << "no insertion\n";
}

輸出

insert done
no insertion

[編輯] 缺陷報告

下列更改行為的缺陷報告追溯地應用於以前出版的 C++ 標準。

缺陷報告 應用於 釋出時的行為 正確的行為
LWG 233 C++98 pos 只是一個提示，它可能被完全忽略 插入要求
儘可能接近
pos 緊前位置
LWG 264 C++98 如果範圍 [first, last) 根據 Compare 排序，則過載 (5) 的複雜度要求為線性
範圍 [first, last) 根據 Compare 排序		 在此特殊情況下
取消線性要求
LWG 316 C++98 在過載 (1) 的返回值中，未指定
哪個布林值表示成功插入		 成功由
true 表示

[編輯] 另請參閱

(C++11)
 就地構造元素
(公共成員函式) [編輯]
(C++11)
 使用提示就地構造元素
(公共成員函式) [編輯]
 建立從引數推斷型別的std::insert_iterator
(函式模板) [編輯]
取自“https://cppreference.tw/mwiki/index.php?title=cpp/container/set/insert&oldid=180855”