容器函式庫

 

C++

編譯器支援

獨立式與託管式

語言

標準函式庫

標準函式庫標頭檔

具名要求

特性測試巨集 (C++20)

語言支援函式庫

概念函式庫 (C++20)

診斷函式庫

記憶體管理函式庫

元編程函式庫 (C++11)

通用公用程式函式庫

容器函式庫

疊代器函式庫

Ranges 函式庫 (C++20)

演算法函式庫

字串函式庫

文本處理函式庫

數值函式庫

日期與時間函式庫

輸入/輸出函式庫

檔案系統函式庫 (C++17)

並行支援函式庫 (C++11)

執行控制函式庫 (C++26)

技術規範

符號索引

外部函式庫

 

容器函式庫

序列

array (C++11)

vector

vector<bool>

inplace_vector (C++26)

hive (C++26)

deque

forward_list (C++11)

list

關聯

set

multiset

map

multimap

無序關聯

unordered_set (C++11)

unordered_multiset (C++11)

unordered_map (C++11)

unordered_multimap (C++11)

適配器 (Adaptors)

stack

queue

priority_queue

flat_set (C++23)

flat_multiset (C++23)

flat_map (C++23)

flat_multimap (C++23)

檢視

span (C++20)

mdspan (C++23)

表格

迭代器失效

成員函式表

非成員函式表

 

容器函式庫（Containers library）是類別樣板與演算法的通用集合，允許程式設計師輕鬆實作常見的資料結構，如佇列、列表與堆疊。容器類別共有 兩(直到 C++11)三(自 C++11) 種：

• 序列容器（sequence containers）、
• 關聯容器（associative containers）、

無序關聯容器（unordered associative containers）、

（C++11 起）

每一種都設計用以支援不同的操作集合。

容器管理為其元素分配的儲存空間，並提供成員函式來存取它們，無論是直接存取還是透過迭代器（具有類似指標屬性的物件）。

大多數容器至少具有幾個共同的成員函式，並共享功能。哪種容器最適合特定應用，不僅取決於所提供的功能，還取決於其在不同工作負載下的效率。

序列容器

序列容器實作了可以按順序存取的資料結構。

array (C++11)	固定大小的原地 (inplace) 連續陣列 (類別模板)
vector	可調整大小的連續陣列 (類別模板)
inplace_vector (C++26)	可調整大小、固定容量、原地連續陣列 (類別模板)
hive (C++26)	重用已刪除元素記憶體的集合 (類別樣板)
deque	雙端隊列 (double-ended queue) (類別模板)
forward_list (C++11)	單向鏈結串列 (類別模板)
list	雙向鏈結串列 (類別模板)

關聯容器

關聯容器實作了可以快速搜尋（複雜度為 O(log n)）的排序資料結構。

set	唯一鍵的集合，按鍵排序 (類別樣板)
map	鍵值對（key-value pairs）的集合，按鍵排序，且鍵是唯一的 (類別樣板)
multiset	鍵的集合，按鍵排序 (類別樣板)
multimap	鍵值對的集合，按鍵排序 (類別樣板)

無序關聯容器 (自 C++11)

無序關聯容器實作了未排序（雜湊）的資料結構，可以快速搜尋（平均複雜度為 O(1)，最差情況下為 O(n)）。

unordered_set (C++11)	唯一鍵的集合，按鍵雜湊 (類別範本)
unordered_map (C++11)	鍵值對的集合，按鍵雜湊，鍵是唯一的 (類別範本)
unordered_multiset (C++11)	鍵的集合，按鍵雜湊 (類別範本)
unordered_multimap (C++11)	鍵值對的集合，按鍵雜湊 (類別範本)

容器適配器

容器適配器為序列容器提供不同的介面。

stack	適配容器以提供堆疊（stack，LIFO 資料結構） (類別樣板)
queue	適配容器以提供佇列（queue，FIFO 資料結構） (類別樣板)
priority_queue	適配容器以提供優先佇列 (類別樣板)
flat_set (C++23)	適配容器以提供按鍵排序的唯一鍵集合 (類別樣板)
flat_map (C++23)	適配兩個容器以提供按唯一鍵排序的鍵值對集合 (類別樣板)
flat_multiset (C++23)	適配一個容器以提供按鍵排序的鍵集合 (類別樣板)
flat_multimap (C++23)	適配兩個容器以提供按鍵排序的鍵值對集合 (類別樣板)

視圖 (自 C++20)

視圖提供了彈性的設施，用於與非擁有型（non-owning）元素陣列上的一維或多維視圖進行互動。

span (C++20)	連續物件序列上的非擁有型視圖 (類別樣板)
mdspan (C++23)	多維非擁有型陣列視圖 (類別樣板)

迭代器失效

唯讀方法絕不會使迭代器或參照失效。修改容器內容的方法可能會使迭代器和/或參照失效，如下表所示。

分類	容器 (Container)	插入之後，...		刪除之後，...		有條件地
		迭代器 是否有效？	參照 是否有效？	迭代器 是否有效？	參照 是否有效？
序列容器	array	不適用 (N/A)		不適用 (N/A)
	vector	否		不適用 (N/A)		插入導致容量改變
		是		是		在被修改的元素之前 （對於插入，僅當容量未改變時）
		否		否		在被修改的元素處或之後
	deque	否	是	是，但被刪除的元素除外		修改了第一個或最後一個元素
			否	否		僅修改了中間部分
	list	是		是，但被刪除的元素除外
	forward_list	是		是，但被刪除的元素除外
關聯容器	set multiset map multimap	是		是，但被刪除的元素除外
無序關聯容器	unordered_set unordered_multiset unordered_map unordered_multimap	否	是	不適用 (N/A)		插入導致了重新雜湊（rehash）
		是		是，但被刪除的元素除外		未重新雜湊

此處，插入是指任何向容器增加一個或多個元素的方法，而刪除（erasure）是指任何從容器移除一個或多個元素的方法。

• 插入方法的例子有 std::set::insert、std::map::emplace、std::vector::push_back 以及 std::deque::push_front。

請注意，std::unordered_map::operator[] 也算在內，因為它可能會向映射中插入元素。

（C++11 起）

• 刪除方法的例子有 std::set::erase、std::vector::pop_back、std::deque::pop_front 以及 std::map::clear。
  • clear 會使所有迭代器與參照失效。因為它刪除了所有元素，這在技術上符合上述規則。

除非另有說明（無論是明確說明或是透過其他函式來定義某個函式），否則將容器作為引數傳遞給函式庫函式絕不會使指向該容器內物件的迭代器失效，也不會改變該容器內物件的值。

尾後迭代器（past-the-end iterator）值得特別提。一般來說，此迭代器會像是指向未刪除元素的一般迭代器一樣失效。因此 std::set::end 永遠不會失效，而 std::unordered_set::end 僅在重新雜湊時失效(自 C++11)，std::vector::end 則總是會失效（因為它總是在被修改的元素之後），以此類推。

有一個例外：刪除 std::deque 最後一個元素的刪除操作「確實」會使尾後迭代器失效，儘管它並不是容器中被刪除的元素（甚至根本不是元素）。結合 std::deque 迭代器的一般規則，最終結果是唯一「不會」使 std::deque::end 失效的修改操作是刪除第一個元素而非最後一個元素的刪除操作。

執行緒安全 所有容器函式都可以由不同執行緒在不同容器上同時呼叫。更廣泛地說，C++ 標準函式庫函式不會讀取其他執行緒可存取的物件，除非這些物件可透過函式引數（包括 this 指標）直接或間接存取。 所有 const 成員函式都可以由不同執行緒在同一個容器上同時呼叫。此外，就執行緒安全而言，成員函式 begin()、end()、rbegin()、rend()、front()、back()、data()、find()、lower_bound()、upper_bound()、equal_range()、at() 以及（除了關聯容器外的）operator[] 的行為都視同 const（也就是說，它們也可以由不同執行緒在同一個容器上同時呼叫）。更廣泛地說，C++ 標準函式庫函式不會修改物件，除非這些物件可透過函式的非 const 引數（包括 this 指標）直接或間接存取。 同一個容器中的不同元素可以由不同執行緒同時修改，但 std::vector<bool> 的元素除外（例如，std::future 物件的 vector 可以從多個執行緒接收值）。 迭代器操作（例如遞增一個迭代器）會讀取但不會修改底層容器，並可與同一個容器上其他迭代器的操作、const 成員函式或對元素的讀取同時執行。會使任何迭代器失效的容器操作則會修改容器，不能與現有迭代器上的任何操作同時執行，即使那些迭代器並未失效。 同一個容器的元素可以與那些未指定會存取這些元素的成員函式同時修改。更廣泛地說，C++ 標準函式庫函式不會讀取透過其引數間接存取的物件（包括容器的其他元素），除非其規範有此要求。 在任何情況下，容器操作（以及演算法或任何其他 C++ 標準函式庫函式）都可以在內部平行化，只要這不改變使用者可見的結果（例如 std::transform 可以平行化，但規定按順序訪問序列中每個元素的 std::for_each 則不行）。

（C++11 起）

函式表

註：標準並未將 std::basic_string 視為容器，但由於其相似性，其行為非常像容器。為方便起見，此處將其列為「虛擬容器（Pseudo container）」。

	- C++03 中存在的函式
	- 自 C++11 起存在的函式
	- 自 C++17 起存在的函式
	- 自 C++20 起存在的函式
	- 自 C++23 起存在的函式

成員函式表

		虛擬容器	序列容器					關聯容器				無序關聯容器				容器適配器
標頭檔		<string>	<array>	<vector>	<deque>	<forward_list>	<list>	<set>		<map>		<unordered_set>		<unordered_map>		<stack>	<queue>		<flat_set>		<flat_map>		標頭檔
容器 (Container)		basic_string	array	vector	deque	forward_list	list	set	multiset	map	multimap	unordered_set	unordered_multiset	unordered_map	unordered_multimap	stack	queue	priority_queue	flat_set	flat_multiset	flat_map	flat_multimap	容器 (Container)
	(建構子)	basic_string	(隱含)	vector	deque	forward_list	list	set	multiset	map	multimap	unordered_set	unordered_multiset	unordered_map	unordered_multimap	stack	queue	priority_queue	flat_set	flat_multiset	flat_map	flat_multimap	(建構子)
	(解構函式)	~basic_string	(隱含)	~vector	~deque	~forward_list	~list	~set	~multiset	~map	~multimap	~unordered_set	~unordered_multiset	~unordered_map	~unordered_multimap	~stack	~queue	~priority_queue	~flat_set	~flat_multiset	~flat_map	~flat_multimap	(解構函式)
	operator=	operator=	(隱含)	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=	operator=
	assign	assign		assign	assign	assign	assign																assign
	assign_range	assign_range		assign_range	assign_range	assign_range	assign_range																assign_range
迭代器	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin				begin cbegin	begin cbegin	begin cbegin	begin cbegin	begin cbegin	迭代器
	end cend	end cend	end cend	end cend	end cend	end cend	end cend	end cend	end cend	end cend	end cend	end cend	end cend	end cend	end cend				end cend	end cend	end cend	end cend	end cend
	rbegin crbegin	rbegin crbegin	rbegin crbegin	rbegin crbegin	rbegin crbegin		rbegin crbegin	rbegin crbegin	rbegin crbegin	rbegin crbegin	rbegin crbegin								rbegin crbegin	rbegin crbegin	rbegin crbegin	rbegin crbegin	rbegin crbegin
	rend crend	rend crend	rend crend	rend crend	rend crend		rend crend	rend crend	rend crend	rend crend	rend crend								rend crend	rend crend	rend crend	rend crend	rend crend
元素 存取	at	at	at	at	at					at				at							at		at	元素 存取
	operator[]	operator[]	operator[]	operator[]	operator[]					operator[]				operator[]							operator[]		operator[]
	data	data	data	data																			data
	front	front	front	front	front	front	front										front	top					front
	back	back	back	back	back		back									top	back						back
容量	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	empty	容量
	size	size	size	size	size		size	size	size	size	size	size	size	size	size	size	size	size	size	size	size	size	size
	max_size	max_size	max_size	max_size	max_size	max_size	max_size	max_size	max_size	max_size	max_size	max_size	max_size	max_size	max_size				max_size	max_size	max_size	max_size	max_size
	resize	resize		resize	resize	resize	resize																resize
	capacity	capacity		capacity																			capacity
	reserve	reserve		reserve								reserve	reserve	reserve	reserve								reserve
	shrink_to_fit	shrink_to_fit		shrink_to_fit	shrink_to_fit																		shrink_to_fit
修改器	clear	clear		clear	clear	clear	clear	clear	clear	clear	clear	clear	clear	clear	clear				clear	clear	clear	clear	clear	修改器
	insert	insert		insert	insert	insert_after	insert	insert	insert	insert	insert	insert	insert	insert	insert				insert	insert	insert	insert	insert
	insert_range	insert_range		insert_range	insert_range	insert_range_after	insert_range	insert_range	insert_range	insert_range	insert_range	insert_range	insert_range	insert_range	insert_range				insert_range	insert_range	insert_range	insert_range	insert_range
	insert_or_assign									insert_or_assign				insert_or_assign							insert_or_assign		insert_or_assign
	emplace			emplace	emplace	emplace_after	emplace	emplace	emplace	emplace	emplace	emplace	emplace	emplace	emplace				emplace	emplace	emplace	emplace	emplace
	emplace_hint							emplace_hint	emplace_hint	emplace_hint	emplace_hint	emplace_hint	emplace_hint	emplace_hint	emplace_hint				emplace_hint	emplace_hint	emplace_hint	emplace_hint	emplace_hint
	try_emplace									try_emplace				try_emplace							try_emplace		try_emplace
	erase	erase		erase	erase	erase_after	erase	erase	erase	erase	erase	erase	erase	erase	erase				erase	erase	erase	erase	erase
	push_front				push_front	push_front	push_front																push_front
	prepend_range				prepend_range	prepend_range	prepend_range																prepend_range
	emplace_front				emplace_front	emplace_front	emplace_front																emplace_front
	pop_front				pop_front	pop_front	pop_front										pop	pop					pop_front
	push_back	push_back		push_back	push_back		push_back									push	push	push					push_back
	append_range	append_range		append_range	append_range		append_range									push_range	push_range	push_range					append_range
	emplace_back			emplace_back	emplace_back		emplace_back									emplace	emplace	emplace					emplace_back
	pop_back	pop_back		pop_back	pop_back		pop_back									pop							pop_back
	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap
	merge					merge	merge	merge	merge	merge	merge	merge	merge	merge	merge								merge
	extract							extract	extract	extract	extract	extract	extract	extract	extract								extract
列表操作	splice					splice_after	splice																splice	列表操作
	remove					remove	remove																remove
	remove_if					remove_if	remove_if																remove_if
	reverse					reverse	reverse																reverse
	unique					unique	unique																unique
	sort					sort	sort																sort
儲存桶與雜湊	begin(size_type) cbegin(size_type)											begin(size_type) cbegin(size_type)	begin(size_type) cbegin(size_type)	begin(size_type) cbegin(size_type)	begin(size_type) cbegin(size_type)								begin(size_type) cbegin(size_type)	儲存桶與雜湊
	end(size_type) cend(size_type)											end(size_type) cend(size_type)	end(size_type) cend(size_type)	end(size_type) cend(size_type)	end(size_type) cend(size_type)								end(size_type) cend(size_type)
	bucket_count											bucket_count	bucket_count	bucket_count	bucket_count								bucket_count
	max_bucket_count											max_bucket_count	max_bucket_count	max_bucket_count	max_bucket_count								max_bucket_count
	bucket_size											bucket_size	bucket_size	bucket_size	bucket_size								bucket_size
	bucket											bucket	bucket	bucket	bucket								bucket
	load_factor											load_factor	load_factor	load_factor	load_factor								load_factor
	max_load_factor											max_load_factor	max_load_factor	max_load_factor	max_load_factor								max_load_factor
	rehash											rehash	rehash	rehash	rehash								rehash
查找	count							count	count	count	count	count	count	count	count				count	count	count	count	count	查找
	find	find						find	find	find	find	find	find	find	find				find	find	find	find	find
	contains	contains						contains	contains	contains	contains	contains	contains	contains	contains				contains	contains	contains	contains	contains
	lower_bound							lower_bound	lower_bound	lower_bound	lower_bound								lower_bound	lower_bound	lower_bound	lower_bound	lower_bound
	upper_bound							upper_bound	upper_bound	upper_bound	upper_bound								upper_bound	upper_bound	upper_bound	upper_bound	upper_bound
	equal_range							equal_range	equal_range	equal_range	equal_range	equal_range	equal_range	equal_range	equal_range				equal_range	equal_range	equal_range	equal_range	equal_range
觀察器	key_comp							key_comp	key_comp	key_comp	key_comp								key_comp	key_comp	key_comp	key_comp	key_comp	觀察器
	value_comp							value_comp	value_comp	value_comp	value_comp								value_comp	value_comp	value_comp	value_comp	value_comp
	hash_function											hash_function	hash_function	hash_function	hash_function								hash_function
	key_eq											key_eq	key_eq	key_eq	key_eq								key_eq
配置器 (Allocator)	get_allocator	get_allocator		get_allocator	get_allocator	get_allocator	get_allocator	get_allocator	get_allocator	get_allocator	get_allocator	get_allocator	get_allocator	get_allocator	get_allocator								get_allocator	配置器 (Allocator)
適配器 (Adaptors)	extract																		extract	extract	extract	extract	extract	適配器 (Adaptors)
	replace																		replace	replace	replace	replace	replace
容器 (Container)		basic_string	array	vector	deque	forward_list	list	set	multiset	map	multimap	unordered_set	unordered_multiset	unordered_map	unordered_multimap	stack	queue	priority_queue	flat_set	flat_multiset	flat_map	flat_multimap	容器 (Container)
標頭檔		<string>	<array>	<vector>	<deque>	<forward_list>	<list>	<set>		<map>		<unordered_set>		<unordered_map>		<stack>	<queue>		<flat_set>		<flat_map>		標頭檔
		虛擬容器	序列容器					關聯容器				無序關聯容器				容器適配器

• 註：兩個不同 extract 行中的函式具有不同的意義與語法

非成員函式表

		虛擬容器	序列容器					關聯容器				無序關聯容器				容器適配器
標頭檔		<string>	<array>	<vector>	<deque>	<forward_list>	<list>	<set>		<map>		<unordered_set>		<unordered_map>		<stack>	<queue>		<flat_set>		<flat_map>		標頭檔
容器 (Container)		basic_string	array	vector	deque	forward_list	list	set	multiset	map	multimap	unordered_set	unordered_multiset	unordered_map	unordered_multimap	stack	queue	priority_queue	flat_set	flat_multiset	flat_map	flat_multimap	容器 (Container)
非成員函式	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==	operator==		operator==	operator==	operator==	operator==	operator==	非成員函式
	operator!= (在 C++20 中移除)	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=	operator!=						operator!= (在 C++20 中移除)
	operator< (在 C++20 中移除)	operator<	operator<	operator<	operator<	operator<	operator<	operator<	operator<	operator<	operator<					operator<	operator<						operator< (在 C++20 中移除)
	operator<= (在 C++20 中移除)	operator<=	operator<=	operator<=	operator<=	operator<=	operator<=	operator<=	operator<=	operator<=	operator<=					operator<=	operator<=						operator<= (在 C++20 中移除)
	operator> (在 C++20 中移除)	operator>	operator>	operator>	operator>	operator>	operator>	operator>	operator>	operator>	operator>					operator>	operator>						operator> (在 C++20 中移除)
	operator>= (在 C++20 中移除)	operator>=	operator>=	operator>=	operator>=	operator>=	operator>=	operator>=	operator>=	operator>=	operator>=					operator>=	operator>=						operator>= (在 C++20 中移除)
	operator<=>	operator<=>	operator<=>	operator<=>	operator<=>	operator<=>	operator<=>	operator<=>	operator<=>	operator<=>	operator<=>					operator<=>	operator<=>		operator<=>	operator<=>	operator<=>	operator<=>	operator<=>
	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap	swap
	erase	erase		erase	erase	erase	erase																erase
	erase_if	erase_if		erase_if	erase_if	erase_if	erase_if	erase_if	erase_if	erase_if	erase_if	erase_if	erase_if	erase_if	erase_if				erase_if	erase_if	erase_if	erase_if	erase_if
容器 (Container)		basic_string	array	vector	deque	forward_list	list	set	multiset	map	multimap	unordered_set	unordered_multiset	unordered_map	unordered_multimap	stack	queue	priority_queue	flat_set	flat_multiset	flat_map	flat_multimap	容器 (Container)
標頭檔		<string>	<array>	<vector>	<deque>	<forward_list>	<list>	<set>		<map>		<unordered_set>		<unordered_map>		<stack>	<queue>		<flat_set>		<flat_map>		標頭檔
		虛擬容器	序列容器					關聯容器				無序關聯容器				容器適配器

<、<=、>、>= 與 != 運算子分別從 operator<=> 與 operator== 合成（synthesized）而來。

(自 C++20 起)

缺陷報告

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

DR	應用於	出版時的行為	正確的行為
LWG 51	C++98	容器迭代器可能會被 任意函式庫操作使之失效	它們僅在 規範要求時才會失效

參閱

C++ 具名要求

• 容器 (Container)
• 序列容器 (SequenceContainer)
• 連續容器 (ContiguousContainer)
• 可反向遍歷容器 (ReversibleContainer)
• 關聯容器 (AssociativeContainer)
• 具配置器感知能力的容器 (AllocatorAwareContainer)
• 無序關聯容器 (UnorderedAssociativeContainer)

valarray	數值陣列、陣列遮罩與陣列切片 (類別樣板)
basic_string	儲存並操作字元序列 (類別模板)
basic_string_view (C++17)	唯讀字串檢視 (string view) (類別樣板)