std::inplace_vector

 

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)

表格

迭代器失效

成員函式表

非成員函式表

 

std::inplace_vector

成員型別
成員函式
inplace_vector::inplace_vector inplace_vector::~inplace_vector    inplace_vector::operator= inplace_vector::assign inplace_vector::assign_range 大小與容量 inplace_vector::empty inplace_vector::size inplace_vector::max_size inplace_vector::capacity inplace_vector::resize inplace_vector::reserve inplace_vector::shrink_to_fit 迭代器 inplace_vector::begininplace_vector::cbegin inplace_vector::endinplace_vector::cend inplace_vector::rbegininplace_vector::crbegin inplace_vector::rendinplace_vector::crend	元素存取 inplace_vector::at inplace_vector::operator[] inplace_vector::front inplace_vector::back inplace_vector::data 修改器 inplace_vector::clear inplace_vector::erase inplace_vector::swap inplace_vector::insert inplace_vector::insert_range inplace_vector::emplace inplace_vector::emplace_back inplace_vector::try_emplace_back inplace_vector::unchecked_emplace_back inplace_vector::push_back inplace_vector::try_push_back inplace_vector::unchecked_push_back inplace_vector::pop_back inplace_vector::append_range inplace_vector::try_append_range
非成員函式
erase(std::inplace_vector)erase_if(std::inplace_vector) swap(std::inplace_vector)	operator==operator<=>

 

定義於標頭檔 <inplace_vector>
template<     class T,     std::size_t N > struct inplace_vector;		（C++26 起）

inplace_vector 是一種具有連續「就地」(inplace) 儲存空間且可動態調整大小的陣列。型別為 T 的元素儲存於物件本身內部，並進行正確的對齊。內部儲存空間的容量在編譯期固定，且等於 N。

元素以連續方式儲存，這意味著不僅可以透過迭代器或隨機存取 operator[] 存取元素，還可以使用指向元素的常規指標偏移量來存取。inplace_vector 元素的指標可以傳遞給任何預期接收 C 陣列元素指標的函式。

inplace_vector 滿足 Container、ReversibleContainer、ContiguousContainer 和 SequenceContainer 的模型，包括大部分的 序列容器可選操作需求，除了不提供 push_front、emplace_front、pop_front 和 prepend_range 成員函式。

對於任何正整數 N，std::inplace_vector<T, N>::iterator 與 std::inplace_vector<T, N>::const_iterator 皆滿足 ConstexprIterator 需求。

特例化版本 std::inplace_vector<T, 0> 是 TriviallyCopyable 且為空的。 std::is_trivially_default_constructible_v<std::inplace_vector<T, 0>> 也為 true。

std::inplace_vector<T, N> 的任何成員函式若嘗試執行導致插入超出容量 N 的操作，將會拋出 std::bad_alloc。

inplace_vector 常見操作的複雜度如下：

• 透過 operator[] 或 at() 進行元素的隨機存取 – 常數時間：𝓞(1)。
• 在末端插入或移除元素 – 常數時間：𝓞(1)。
• 在末端插入或移除多個元素 – 與插入/移除的元素數量呈線性關係：𝓞(n)。
• 在開頭或中間插入或移除元素 – 與插入/移除的元素數量加上距離向量末端的距離呈線性關係：𝓞(n)。

迭代器失效

std::inplace_vector 的迭代器失效保證與 std::vector 不同：

• 移動 inplace_vector 會使所有迭代器失效；
• 交換兩個 inplace_vector 會使所有迭代器失效（在交換過程中，迭代器將繼續指向同一個陣列元素，因此其值可能會改變）。

下列成員函式可能會使迭代器失效：operator=、assign、assign_range、clear、emplace、erase、insert、insert_range、pop_back、resize 以及 swap。

下列成員函式僅會使 end 迭代器失效：append_range、emplace_back、push_back、try_append_range、try_emplace_back、try_push_back、unchecked_emplace_back 以及 unchecked_push_back。

模板參數

T	-	元素型別。必須為 MoveConstructible 且可 MoveAssignable。
N	-	容量，即 inplace_vector 中元素的最大數量（可以是 ​0​）。

成員型別

類型	定義
value_type	T
size_type	std::size_t
difference_type	std::ptrdiff_t
reference	value_type&
const_reference	const value_type&
pointer	value_type*
const_pointer	const value_type*
iterator	實作定義的 LegacyRandomAccessIterator 和 random_access_iterator，指向 value_type
const_iterator	實作定義的 LegacyRandomAccessIterator，ConstexprIterator(自 C++26 起) 和 random_access_iterator，指向 const value_type
reverse_iterator	std::reverse_iterator<iterator>
const_reverse_iterator	std::reverse_iterator<const_iterator>

成員函式

(建構子)	建構 inplace_vector (公開成員函式)
(解構函式)	解構 inplace_vector (公開成員函式)
operator=	指派值給容器 (公開成員函式)
assign	指派值給容器 (公開成員函式)
assign_range	指派數值範圍給容器 (公開成員函式)
元素存取
at	存取指定元素，並進行邊界檢查 (公開成員函式)
operator[]	存取指定元素 (公開成員函式)
front	存取第一個元素 (公開成員函式)
back	存取最後一個元素 (公開成員函式)
data	直接存取底層連續儲存空間 (公開成員函式)
迭代器
begincbegin	回傳指向起點的反覆器 (公開成員函式)
endcend	回傳指向終點的反覆器 (公開成員函式)
rbegincrbegin	回傳指向起點的反向反覆器 (公開成員函式)
rendcrend	回傳指向終點的反向反覆器 (公開成員函式)
大小與容量
empty	檢查容器是否為空 (公開成員函式)
size	回傳元素個數 (公開成員函式)
max_size [靜態]	回傳最大可能的元素個數 (公開靜態成員函式)
capacity [靜態]	傳回目前已分配儲存空間中可容納的元素數量 (公開靜態成員函式)
resize	更改儲存的元素個數 (公開成員函式)
reserve [靜態]	預留儲存空間 (公開靜態成員函式)
shrink_to_fit [靜態]	透過釋放未使用的記憶體來減少記憶體使用量 (公開靜態成員函式)
修改器
insert	插入元素 (公開成員函式)
insert_range	插入數值範圍元素 (公開成員函式)
emplace	原地建構元素 (公開成員函式)
emplace_back	原地建構一個元素到結尾 (公開成員函式)
try_emplace_back	嘗試在末端就地建構一個元素 (公開成員函式)
unchecked_emplace_back	無條件地在末端就地建構一個元素 (公開成員函式)
push_back	新增元素到結尾 (公開成員函式)
try_push_back	嘗試在末端添加一個元素 (公開成員函式)
unchecked_push_back	無條件地在末端添加一個元素 (公開成員函式)
pop_back	移除最後一個元素 (公開成員函式)
append_range	新增數值範圍元素到結尾 (公開成員函式)
try_append_range	嘗試在末端添加一個元素範圍 (公開成員函式)
clear	清除內容 (公開成員函式)
erase	刪除元素 (公開成員函式)
swap	交換內容 (公開成員函式)

非成員函式

std::swap(std::inplace_vector) (C++26)	特化 std::swap 演算法 (函式範本)
erase(std::inplace_vector)erase_if(std::inplace_vector) (C++26)	移除所有符合特定條件的元素 (函式樣板)
operator==operator<=> (C++26)	依字典順序比較兩個 inplace_vector 的值 (函式模板)

註解

inplace_vector 中的元素數量可以動態變化，最高可達固定的容量，因為元素與 std::array 類似，儲存在物件本身內部。然而，與必須在實例化時建構所有元素的 C 陣列或 std::array 不同，inplace_vector 中的物件是在插入時才進行初始化的。

inplace_vector 在不希望使用動態記憶體配置的環境中非常有用。

功能測試巨集	數值	標準	功能
__cpp_lib_inplace_vector	202406L	(C++26)	std::inplace_vector：具有固定容量就地儲存空間且可動態調整大小的向量
__cpp_lib_constexpr_inplace_vector	202502L	(C++26)	constexpr 針對非平凡元素型別的 std::inplace_vector

範例

執行此程式碼

#include <algorithm>
#include <array>
#include <cassert>
#include <inplace_vector>
 
int main()
{
    std::inplace_vector<int, 4> v1{0, 1, 2};
    assert(v1.max_size() == 4);
    assert(v1.capacity() == 4);
    assert(v1.size() == 3);
    assert(std::ranges::equal(v1, std::array{0, 1, 2}));
    assert(v1[0] == 0);
    assert(v1.at(0) == 0);
    assert(v1.front() == 0);
    assert(*v1.begin() == 0);
    assert(v1.back() == 2);
    v1.push_back(3);
    assert(v1.back() == 3);
    assert(std::ranges::equal(v1, std::array{0, 1, 2, 3}));
    v1.resize(3);
    assert(std::ranges::equal(v1, std::array{0, 1, 2}));
    assert(v1.try_push_back(3) != nullptr);
    assert(v1.back() == 3);
    assert(v1.size() == 4);
    assert(v1.try_push_back(13) == nullptr); // no place
    assert(v1.back() == 3);
    assert(v1.size() == 4);
    v1.clear();
    assert(v1.size() == 0);
    assert(v1.empty());
}

參見

vector	可調整大小的連續陣列 (類別模板)
array (C++11)	固定大小的原地 (inplace) 連續陣列 (類別模板)
deque	雙端隊列 (double-ended queue) (類別模板)

外部連結

1.	inplace_vector — P0843R14 (std::inplace_vector) 的參考實作。
2.	static_vector — Boost.Container 將就地向量實作為具有自身保證的獨立型別。
3.	fixed_vector — EASTL 透過額外的模板參數來實作就地向量。
4.	small_vector — Folly 同樣透過額外的模板參數來實作就地向量。
5.	stack_alloc — Howard Hinnant 的自訂配置器，可在 std::vector 之上模擬 std::inplace_vector。