std::optional

 

C++

編譯器支援

自由（freestanding）與宿主（hosted）

語言

標準庫

標準庫標頭檔案

具名要求

特性測試宏 (C++20)

語言支援庫

概念庫 (C++20)

診斷庫

記憶體管理庫

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

通用工具庫

容器庫

迭代器庫

範圍庫 (C++20)

演算法庫

字串庫

文字處理庫

數值庫

日期和時間庫

輸入/輸出庫

檔案系統庫 (C++17)

併發支援庫 (C++11)

執行控制庫 (C++26)

技術規範

符號索引

外部庫

 

工具庫

語言支援 型別支援（基本型別、RTTI） 庫特性測試宏 (C++20) 程式工具 變參函式 initializer_list (C++11) is_constant_evaluated (C++20) is_within_lifetime (C++26) source_location (C++20) 協程支援 (C++20) 契約支援 (C++26) 三路比較 three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)   is_eqis_ltis_lteq (C++20)(C++20)(C++20)   is_neqis_gtis_gteq (C++20)(C++20)(C++20)

通用工具 函式物件 位操作 (C++20) bitset hash (C++11) 關係運算符 (C++20 中棄用) rel_ops::operator!=rel_ops::operator>    rel_ops::operator<=rel_ops::operator>= 整數比較函式 cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)   cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) 交換與型別操作 swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) 常用詞彙型別 pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23)

 

std::optional

成員函式

optional::optional

optional::~optional

optional::operator=

觀察器

optional::operator->optional::operator*

optional::operator booloptional::has_value

optional::value

optional::value_or

迭代器

optional::begin (C++26)

optional::end (C++26)

Monadic operations

optional::and_then (C++23)

optional::transform (C++23)

optional::or_else (C++23)

修改器

optional::emplace

optional::swap

optional::reset

非成員函式

operator==operator!=operator<operator<=operator>operator>=operator<=> (C++20)

make_optional

swap(std::optional)

推導指引

輔助類

hash<std::optional>

nullopt_t

in_place_t

bad_optional_access

輔助物件

nullopt

in_place

 

定義於標頭檔案 <optional>
template< class T > class optional;		(C++17 起)

類模板 std::optional 管理一個可選的包含值，即一個可能存在也可能不存在的值。

optional 的一個常見用例是作為可能失敗的函式的返回值。與其他方法（例如 std::pair<T, bool>）不同，optional 能夠很好地處理構造開銷大的物件，並且更具可讀性，因為它明確表達了意圖。

在任何給定時間，任何 optional 例項要麼**包含一個值**，要麼**不包含一個值**。

如果 optional 包含一個值，則該值保證**巢狀**在 optional 物件內部。因此，optional 物件模擬一個物件，而不是一個指標，儘管定義了 operator*() 和 operator->()。

當 optional 型別的物件被**上下文轉換為 bool** 時，如果物件包含一個值，則轉換返回 true；如果物件不包含值，則返回 false。

在以下情況下，optional 物件包含一個值：

• 物件使用型別為 T 的值或另一個包含值的 optional 進行初始化/賦值。

在以下情況下，optional 物件不包含一個值：

• 物件被預設初始化。
• 物件使用型別為 std::nullopt_t 的值或不包含值的 optional 物件進行初始化/賦值。
• 呼叫了成員函式 reset()。

optional 物件是一個**view**，如果它**包含一個值**，則包含一個元素；否則，如果它不包含一個值，則包含零個元素。所包含元素的生命週期與物件繫結。

(C++26 起)

不允許可選的引用、函式、陣列或（可能帶 cv 限定符的）void；如果例項化 optional 時使用此類型別，程式將是非良構的。此外，如果例項化 optional 時使用（可能帶 cv 限定符的）標籤型別 std::nullopt_t 或 std::in_place_t，程式也將是非良構的。

模板引數

T

-

要管理初始化狀態的值的型別。該型別必須滿足 可析構 的要求（特別是，不允許陣列和引用型別）。

巢狀型別

型別	定義
value_type	T
iterator (C++26 起)	實現定義的 舊式隨機訪問迭代器、常量表達式迭代器 和 連續迭代器，其 value_type 和 reference 分別是 std::remove_cv_t<T> 和 T&。
const_iterator (C++26 起)	實現定義的 舊式隨機訪問迭代器、常量表達式迭代器 和 連續迭代器，其 value_type 和 reference 分別是 std::remove_cv_t<T> 和 const T&。

容器 的迭代器型別的所有要求也適用於 optional 的 iterator 型別。

資料成員

T* val

指向包含物件（如果存在）的指標 (僅用於闡釋的成員物件*)

成員函式

(建構函式)	構造 optional 物件 (公共成員函式)
(解構函式)	如果存在，銷燬所包含的值 (公共成員函式)
operator=	賦值內容 (公共成員函式)
迭代器
begin (C++26)	返回指向起始的迭代器 (公共成員函式)
end (C++26)	返回指向末尾的迭代器 (公共成員函式)
觀察器
operator->operator*	訪問所包含的值 (公共成員函式)
operator boolhas_value	檢查物件是否包含值 (公共成員函式)
value	返回所包含的值 (公共成員函式)
value_or	如果可用，返回包含的值，否則返回另一個值 (公共成員函式)
Monadic operations
and_then (C++23)	如果存在包含的值，則返回給定函式對該值的結果，否則返回空的 optional (公共成員函式)
transform (C++23)	如果存在包含的值，則返回一個包含轉換後的值的 optional，否則返回一個空的 optional (公共成員函式)
or_else (C++23)	如果 optional 包含值，則返回 optional 本身，否則返回給定函式的結果 (公共成員函式)
修改器
swap	交換內容 (公共成員函式)
reset	銷燬任何包含的值 (公共成員函式)
emplace	就地構造包含的值 (公共成員函式)

非成員函式

operator==operator!=operator<operator<=operator>operator>=operator<=> (C++17)(C++17)(C++17)(C++17)(C++17)(C++17)(C++20)	比較 optional 物件 (函式模板)
make_optional (C++17)	建立 optional 物件 (函式模板)
std::swap(std::optional) (C++17)	特化 std::swap 演算法 (函式模板)

輔助類

std::hash<std::optional> (C++17)	對 std::optional 的雜湊支援 (類模板特化)
nullopt_t (C++17)	指示 std::optional 不包含值的型別 (類)
bad_optional_access (C++17)	當檢查式訪問不包含值的 optional 時丟擲的異常 (類)

輔助函式

nullopt (C++17)	nullopt_t 型別的物件 (常量)
in_placein_place_typein_place_indexin_place_tin_place_type_tin_place_index_t (C++17)	原地構造標籤 (標籤)

輔助特化

template< class T > constexpr bool ranges::enable_view<std::optional<T>> = true;		(C++26 起)

此 ranges::enable_view 特化使得 optional 滿足 view 的要求。

template< class T > constexpr auto format_kind<std::optional<T>> = range_format::disabled;		(C++26 起)

此 format_kind 特化停用 optional 的 範圍格式化支援。

備註

特性測試宏	值	標準	特性
__cpp_lib_optional	201606L	(C++17)	std::optional
	202106L	(C++23) (DR20)	完全 constexpr
	202110L	(C++23)	Monadic operations
__cpp_lib_optional_range_support	202406L	(C++26)	對 std::optional 的範圍支援

示例

執行此程式碼

#include <iostream>
#include <optional>
#include <string>
 
// optional can be used as the return type of a factory that may fail
std::optional<std::string> create(bool b)
{
    if (b)
        return "Godzilla";
    return {};
}
 
// std::nullopt can be used to create any (empty) std::optional
auto create2(bool b)
{
    return b ? std::optional<std::string>{"Godzilla"} : std::nullopt;
}
 
int main()
{
    std::cout << "create(false) returned "
              << create(false).value_or("empty") << '\n';
 
    // optional-returning factory functions are usable as conditions of while and if
    if (auto str = create2(true))
        std::cout << "create2(true) returned " << *str << '\n';
}

輸出

create(false) returned empty
create2(true) returned Godzilla

缺陷報告

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

缺陷報告	應用於	釋出時的行為	正確的行為
LWG 4141	C++17	儲存要求 令人困惑	包含的物件必須 巢狀在 optional 物件中

參閱

variant (C++17)	一種型別安全的帶判別聯合體 (類模板)
any (C++17)	儲存任意 可複製構造 型別例項的物件 (類)
expected (C++23)	一個包裝器，包含預期值或錯誤值 (類模板)
ranges::single_viewviews::single (C++20)	一個包含單個指定值的 view (類模板) (自定義點物件)
ranges::empty_viewviews::empty (C++20)	一個不含元素的空 view (類模板) (變數模板)