View source for cpp/utility/optional

{{cpp/title|optional}}
{{cpp/utility/optional/navbar}}
{{ddcl|header=optional|since=c++17|
template< class T >
class optional;
}}

The class template {{tt|std::optional}} manages an ''optional'' contained value, i.e. a value that may or may not be present.

A common use case for {{tt|optional}} is the return value of a function that may fail. As opposed to other approaches, such as {{c/core|std::pair<T, bool>}}, {{tt|optional}} handles expensive-to-construct objects well and is more readable, as the intent is expressed explicitly.

Any instance of {{tt|optional<T>}} at any given point in time either ''contains a value'' or ''does not contain a value''.

If an {{tt|optional<T>}} ''contains a value'', the value is guaranteed to be allocated as part of the {{tt|optional}} object footprint, i.e. no dynamic memory allocation ever takes place. Thus, an {{tt|optional}} object models an object, not a pointer, even though {{lc|operator*()}} and {{lc|operator->()}} are defined.

When an object of type {{tt|optional<T>}} is [[cpp/language/implicit_cast|contextually converted to {{c/core|bool}}]], the conversion returns {{c|true}} if the object ''contains a value'' and {{c|false}} if it ''does not contain a value''.

The {{tt|optional}} object ''contains a value'' in the following conditions:

* The object is initialized with/assigned from a value of type {{tt|T}} or another {{tt|optional}} 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 {{lc|std::nullopt_t}} or an  {{tt|optional}} object that ''does not contain a value''.
* The member function {{lc|reset()}} is called.

There are no optional references; a program is ill-formed if it instantiates an {{tt|optional}} with a reference type. In addition, a program is ill-formed if it instantiates an {{tt|optional}} with the (possibly cv-qualified) tag types {{lc|std::nullopt_t}} or {{lc|std::in_place_t}}.

===Template parameters===
{{par begin}}
{{par|T|the type of the value to manage initialization state for. The type must meet the requirements of {{named req|Destructible}} (in particular, array and reference types are not allowed).}}
{{par end}}

===Member types===
{{dsc begin}}
{{dsc hitem|Member type|Definition}}
{{dsc|{{tt|value_type}}|{{tt|T}}}}
{{dsc end}}

===Member functions===
{{dsc begin}}
{{dsc inc|cpp/utility/optional/dsc constructor}}
{{dsc inc|cpp/utility/optional/dsc destructor}}
{{dsc inc|cpp/utility/optional/dsc operator{{=}}}}

{{dsc h2|Observers}}
{{dsc inc|cpp/utility/optional/dsc operator*}}
{{dsc inc|cpp/utility/optional/dsc operator bool}}
{{dsc inc|cpp/utility/optional/dsc value}}
{{dsc inc|cpp/utility/optional/dsc value_or}}

{{dsc h2|Monadic operations}}
{{dsc inc|cpp/utility/optional/dsc and_then}}
{{dsc inc|cpp/utility/optional/dsc transform}}
{{dsc inc|cpp/utility/optional/dsc or_else}}

{{dsc h2|Modifiers}}
{{dsc inc|cpp/utility/optional/dsc swap}}
{{dsc inc|cpp/utility/optional/dsc reset}}
{{dsc inc|cpp/utility/optional/dsc emplace}}
{{dsc end}}

===Non-member functions===
{{dsc begin}}
{{dsc inc|cpp/utility/optional/dsc operator_cmp}}
{{dsc inc|cpp/utility/optional/dsc make_optional}}
{{dsc inc|cpp/utility/optional/dsc swap2}}
{{dsc end}}

===Helper classes===
{{dsc begin}}
{{dsc inc|cpp/utility/optional/dsc hash}}
{{dsc inc|cpp/utility/optional/dsc nullopt_t}}
{{dsc inc|cpp/utility/optional/dsc bad_optional_access}}
{{dsc end}}

===Helpers ===
{{dsc begin}}
{{dsc inc|cpp/utility/optional/dsc nullopt}}
{{dsc inc|cpp/utility/optional/dsc in_place}}
{{dsc end}}

===[[cpp/utility/optional/deduction_guides|Deduction guides]]===

===Notes===
{{ftm begin|std=1|comment=1}}
{{ftm|std=C++17|value=201606L|__cpp_lib_optional|{{ttt|std::optional}}}}
{{ftm|std=C++20|value=202106L|__cpp_lib_optional|Fully constexpr|dr=1}}
{{ftm|std=C++23|value=202110L|__cpp_lib_optional|[[#Monadic operations|Monadic operations]]}}
{{ftm end}}

===Example===
{{example
|code=
#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
}}

===See also===
[https://doc.rust-lang.org/std/option/index.html Optional values in Rust]
{{dsc begin}}
{{dsc inc|cpp/utility/dsc variant}}
{{dsc inc|cpp/utility/dsc any}}
{{dsc end}}

{{langlinks|es|ja|ru|zh}}