std::inplace_vector

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

超程式設計庫 (C++11)

通用工具庫

容器庫

迭代器庫

範圍庫 (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)

介面卡

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 是一個具有連續就地儲存的動態可變大小陣列。型別 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> 是 可平凡複製的 且為空。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	-	元素型別。必須是 可移動構造 和 可移動賦值 的。
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 (public member function)
(解構函式)	銷燬 inplace_vector (public member function)
operator=	將值賦給容器 (public member function)
assign	將值賦給容器 (public member function)
assign_range	將一個範圍的值賦給容器 (public member function)
元素訪問
at	訪問指定的元素，帶邊界檢查 (public member function)
operator[]	訪問指定的元素 (public member function)
front	訪問第一個元素 (public member function)
back	訪問最後一個元素 (public member function)
data	直接訪問底層連續儲存 (public member function)
迭代器
begincbegin	返回指向起始的迭代器 (public member function)
endcend	返回指向末尾的迭代器 (public member function)
rbegincrbegin	返回指向起始的逆向迭代器 (public member function)
rendcrend	返回指向末尾的逆向迭代器 (public member function)
大小和容量
empty	檢查容器是否為空 (public member function)
size	返回元素數量 (public member function)
max_size [靜態]	返回元素的最大可能數量 (public static member function)
capacity [靜態]	返回當前已分配儲存空間中可容納的元素數量 (public static member function)
resize	更改儲存的元素數量 (public member function)
reserve [靜態]	預留儲存空間 (public static member function)
shrink_to_fit [靜態]	透過釋放未使用的記憶體來減少記憶體使用 (public static member function)
修改器
insert	插入元素 (public member function)
insert_range	插入元素範圍 (public member function)
emplace	就地構造元素 (public member function)
emplace_back	就地構造元素於結尾 (public member function)
try_emplace_back	嘗試在末尾就地構造元素 (public member function)
unchecked_emplace_back	無條件地在末尾就地構造元素 (public member function)
push_back	新增元素到結尾 (public member function)
try_push_back	嘗試在末尾新增元素 (public member function)
unchecked_push_back	無條件地在末尾新增元素 (public member function)
pop_back	移除末元素 (public member function)
append_range	新增一個元素範圍到結尾 (public member function)
try_append_range	嘗試在末尾新增一系列元素 (public member function)
clear	清除內容 (public member function)
erase	擦除元素 (public member function)
swap	交換內容 (public member function)

非成員函式

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 中的物件在插入時才被初始化，而 C 陣列或 std::array 必須在例項化時構造所有元素。

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)	固定大小的原位連續陣列 (類模板)
deque	雙端佇列 (類模板)

外部連結

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。