|
|
| Line 1: |
Line 1: |
| − | {{cpp/title|optional}}
| + | #REDIRECT [[enwiki:Rust_(programming_language)]] |
| − | {{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===
| + | |
| − | {{dsc begin}}
| + | |
| − | {{dsc inc|cpp/utility/dsc variant}}
| + | |
| − | {{dsc inc|cpp/utility/dsc any}}
| + | |
| − | {{dsc end}}
| + | |
| − | | + | |
| − | {{langlinks|es|ja|ru|zh}}
| + | |
