std::optional - cppreference.com (original) (raw)

| | | | | ------------------------------------ | | ------------- | | template< class T > class optional; | | (since C++17) |

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 does not contain a value in the following conditions:

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. (since C++26)

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

T - the type of the value to manage initialization state for. The type must meet the requirements of Destructible (in particular, array and reference types are not allowed).

[edit] Nested types

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

(constructor) constructs the optional object (public member function) [edit]
(destructor) destroys the contained value, if there is one (public member function) [edit]
operator= assigns contents (public member function) [edit]
Iterators
begin(C++26) returns an iterator to the beginning (public member function) [edit]
end(C++26) returns an iterator to the end (public member function) [edit]
Observers
operator->operator* accesses the contained value (public member function) [edit]
operator boolhas_value checks whether the object contains a value (public member function) [edit]
value returns the contained value (public member function) [edit]
value_or returns the contained value if available, another value otherwise (public member function) [edit]
Monadic operations
and_then(C++23) returns the result of the given function on the contained value if it exists, or an empty optional otherwise (public member function) [edit]
transform(C++23) returns an optional containing the transformed contained value if it exists, or an empty optional otherwise (public member function) [edit]
or_else(C++23) returns the optional itself if it contains a value, or the result of the given function otherwise (public member function) [edit]
Modifiers
swap exchanges the contents (public member function) [edit]
reset destroys any contained value (public member function) [edit]
emplace constructs the contained value in-place (public member function) [edit]

[edit] Non-member functions

[edit] Helper classes

[edit] Helpers

[edit] Helper specializations

This specialization of ranges::enable_view makes optional satisfy view.

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

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 #include #include   // 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 storageallocation was confusing the contained object must benested within the optional object

[edit] See also