std::optional
<optional>
class optional;
The class template std::optional
manages an optional contained value, i.e. a value that may or may not be present.
A common use case for optional
is the return value of a function that may fail. As opposed to other approaches, such as std::pair <T, bool>, optional
handles expensive-to-construct objects well and is more readable, as the intent is expressed explicitly.
Any instance of optional
at any given point in time either contains a value or does not contain a value.
If an optional
contains a value, the value is guaranteed to be nested within the optional
object. Thus, an optional
object models an object, not a pointer, even though operator*() and operator->() are defined.
When an object of type optional<T>
is contextually converted to bool, the conversion returns true if the object contains a value and false if it does not contain a value.
The optional
object contains a value in the following conditions:
- The object is initialized with/assigned from a value of type
T
or anotheroptional
that contains a value.
The object does not contain a value in the following conditions:
- The object is default-initialized.
- The object is initialized with/assigned from a value of type std::nullopt_t or an
optional
object that does not contain a value. - The member function reset() is called.
The optional
object is a view
that contains either one element if it contains a value, or otherwise zero elements if it does not contain a value. The lifetime of the contained element is bound to the object.
There are no optional references, functions, arrays, or (possibly cv-qualified) void; a program is ill-formed if it instantiates an optional
with such a type. In addition, a program is ill-formed if it instantiates an optional
with the (possibly cv-qualified) tag types std::nullopt_t or std::in_place_t .
Contents
[edit] Template parameters
[edit] Nested types
value_type
T
iterator
(since C++26)
implementation-defined LegacyRandomAccessIterator, ConstexprIterator, and contiguous_iterator
whose value_type
and reference
are std::remove_cv_t <T> and T&, respectively.
const_iterator
(since C++26)
implementation-defined LegacyRandomAccessIterator, ConstexprIterator, and contiguous_iterator
whose value_type
and reference
are std::remove_cv_t <T> and const T&, respectively.
All requirements on the iterator types of a Container apply to the iterator
type of optional
as well.
[edit] Data members
T*
val
a pointer to the contained object (if exists)(exposition-only member object*)
[edit] Member functions
Iterators
Observers
Monadic operations
optional
otherwise (public member function) [edit]
optional
containing the transformed contained value if it exists, or an empty optional
otherwise (public member function) [edit]
optional
itself if it contains a value, or the result of the given function otherwise (public member function) [edit]
Modifiers
[edit] Non-member functions
optional
objects (function template) [edit]
[edit] Helper classes
(class) [edit]
[edit] Helpers
[edit] Helper specializations
constexpr bool ranges::enable_view <std::optional<T>> = true;
This specialization of ranges::enable_view makes optional
satisfy view
.
constexpr auto format_kind<std::optional<T>> = range_format::disabled;
This specialization of format_kind disables the range formatting support of optional
.
[edit] Deduction guides
[edit] Notes
Feature-test macro | Value | Std | Feature |
---|---|---|---|
__cpp_lib_optional |
201606L |
(C++17) | std::optional
|
202106L |
(C++23) (DR20) |
Fully constexpr | |
202110L |
(C++23) | Monadic operations | |
__cpp_lib_optional_range_support |
202406L |
(C++26) | Range support for std::optional
|
[edit] Example
#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'; }
Output:
create(false) returned empty create2(true) returned Godzilla
[edit] Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR | Applied to | Behavior as published | Correct behavior |
---|---|---|---|
LWG 4141 | C++17 | the requirement of storage allocation was confusing |
the contained object must be nested within the optional object
|
[edit] See also
view
that contains a single element of a specified value(class template) (customization point object)[edit]