cpp/experimental/optional: Difference between revisions
From cppreference.com
< cpp | experimental
m Text replace - "{{concept" to "{{named req" |
Andreas Krug (talk | contribs) m fmt |
||
| (One intermediate revision by the same user not shown) | |||
| Line 1: | Line 1: | ||
{{cpp/experimental/title|optional}} | {{cpp/experimental/title|optional}} | ||
{{cpp/experimental/optional/navbar}} | {{cpp/experimental/optional/navbar}} | ||
{{fmbox | class=noprint | style=font-size: 0.8em | text='''Merged into ISO C++''' The functionality described on this page was merged into the mainline ISO C++ standard as of 3/2016, see | {{fmbox|class=noprint|style=font-size: 0.8em|text='''Merged into ISO C++''' The functionality described on this page was merged into the mainline ISO C++ standard as of 3/2016, see {{ltt|cpp/utility/optional|std::optional}} {{mark since c++17}}}} | ||
{{ddcl | header=experimental/optional | since=libfund_ts | | {{ddcl|header=experimental/optional|since=libfund_ts| | ||
template< class T > | template< class T > | ||
class optional; | class optional; | ||
| Line 20: | Line 20: | ||
The {{tt|optional}} object ''contains a value'' in the following conditions: | The {{tt|optional}} object ''contains a value'' in the following conditions: | ||
* The object is initialized with a value of type {{tt|T}} | * The object is initialized with a value of type {{tt|T}} | ||
* The object is assigned from another {{tt|optional}} that ''contains a value''. | * The object is assigned from another {{tt|optional}} that ''contains a value''. | ||
| Line 27: | Line 27: | ||
* The object is default-initialized. | * The object is default-initialized. | ||
* The object is initialized with a value of {{lc|std::experimental::nullopt_t}} or an {{tt|optional}} object that ''does not contain a value''. | * The object is initialized with a value of {{lc|std::experimental::nullopt_t}} or an {{tt|optional}} object that ''does not contain a value''. | ||
* The object is assigned from a value of {{lc|std::experimental::nullopt_t}} or from an {{tt|optional}} that ''does not contain a value'' | * The object is assigned from a value of {{lc|std::experimental::nullopt_t}} or from an {{tt|optional}} that ''does not contain a value'' | ||
===Template parameters=== | ===Template parameters=== | ||
{{par begin}} | {{par begin}} | ||
{{par | T | the type of the value to manage initialization state for. The type must meet the requirements of {{named req|Destructible}} }} | {{par|T|the type of the value to manage initialization state for. The type must meet the requirements of {{named req|Destructible}}}} | ||
{{par end}} | {{par end}} | ||
===Member types=== | ===Member types=== | ||
{{dsc begin}} | {{dsc begin}} | ||
{{dsc hitem | Member type | Definition}} | {{dsc hitem|Member type|Definition}} | ||
{{dsc | {{tt|value_type}} | {{tt|T}} }} | {{dsc|{{tt|value_type}}|{{tt|T}}}} | ||
{{dsc end}} | {{dsc end}} | ||
===Member functions=== | ===Member functions=== | ||
{{dsc begin}} | {{dsc begin}} | ||
{{dsc inc | cpp/experimental/optional/dsc constructor}} | {{dsc inc|cpp/experimental/optional/dsc constructor}} | ||
{{dsc inc | cpp/experimental/optional/dsc destructor}} | {{dsc inc|cpp/experimental/optional/dsc destructor}} | ||
{{dsc inc | cpp/experimental/optional/dsc operator{{=}}}} | {{dsc inc|cpp/experimental/optional/dsc operator{{=}}}} | ||
{{dsc h2 | Observers}} | {{dsc h2|Observers}} | ||
{{dsc inc | cpp/experimental/optional/dsc operator*}} | {{dsc inc|cpp/experimental/optional/dsc operator*}} | ||
{{dsc inc | cpp/experimental/optional/dsc operator bool}} | {{dsc inc|cpp/experimental/optional/dsc operator bool}} | ||
{{dsc inc | cpp/experimental/optional/dsc value}} | {{dsc inc|cpp/experimental/optional/dsc value}} | ||
{{dsc inc | cpp/experimental/optional/dsc value_or}} | {{dsc inc|cpp/experimental/optional/dsc value_or}} | ||
{{dsc h2 | Modifiers}} | {{dsc h2|Modifiers}} | ||
{{dsc inc | cpp/experimental/optional/dsc swap}} | {{dsc inc|cpp/experimental/optional/dsc swap}} | ||
{{dsc inc | cpp/experimental/optional/dsc emplace}} | {{dsc inc|cpp/experimental/optional/dsc emplace}} | ||
{{dsc end}} | {{dsc end}} | ||
===Member objects=== | ===Member objects=== | ||
{{dsc begin}} | {{dsc begin}} | ||
{{dsc hitem | Member name | Definition}} | {{dsc hitem|Member name|Definition}} | ||
{{dsc | {{tt|val}} {{mark|private}} | pointer to the contained value (which points at a data member of the same object), the name is for exposition only}} | {{dsc|{{tt|val}} {{mark|private}}|pointer to the contained value (which points at a data member of the same object), the name is for exposition only}} | ||
{{dsc end}} | {{dsc end}} | ||
===Non-member functions=== | ===Non-member functions=== | ||
{{dsc begin}} | {{dsc begin}} | ||
{{dsc inc | cpp/experimental/optional/dsc operator_cmp}} | {{dsc inc|cpp/experimental/optional/dsc operator_cmp}} | ||
{{dsc inc | cpp/experimental/optional/dsc make_optional}} | {{dsc inc|cpp/experimental/optional/dsc make_optional}} | ||
{{dsc inc | cpp/experimental/optional/dsc swap2}} | {{dsc inc|cpp/experimental/optional/dsc swap2}} | ||
{{dsc end}} | {{dsc end}} | ||
===Helper classes=== | ===Helper classes=== | ||
{{dsc begin}} | {{dsc begin}} | ||
{{dsc inc | cpp/experimental/optional/dsc hash}} | {{dsc inc|cpp/experimental/optional/dsc hash}} | ||
{{dsc inc | cpp/experimental/optional/dsc nullopt_t}} | {{dsc inc|cpp/experimental/optional/dsc nullopt_t}} | ||
{{dsc inc | cpp/experimental/optional/dsc in_place_t}} | {{dsc inc|cpp/experimental/optional/dsc in_place_t}} | ||
{{dsc inc | cpp/experimental/optional/dsc bad_optional_access}} | {{dsc inc|cpp/experimental/optional/dsc bad_optional_access}} | ||
{{dsc end}} | {{dsc end}} | ||
===Helper objects=== | ===Helper objects=== | ||
{{dsc begin}} | {{dsc begin}} | ||
{{dsc inc | cpp/experimental/optional/dsc nullopt}} | {{dsc inc|cpp/experimental/optional/dsc nullopt}} | ||
{{dsc inc | cpp/experimental/optional/dsc in_place}} | {{dsc inc|cpp/experimental/optional/dsc in_place}} | ||
{{dsc end}} | {{dsc end}} | ||
Latest revision as of 09:34, 28 November 2023
| Defined in header <experimental/optional>
|
||
template< class T >
class optional;
|
(library fundamentals TS) | |
The class template std::experimental::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<T> at any given point in time either contains a value or does not contain a value.
If an optional<T> contains a value, the value is guaranteed to be allocated as part of the optional object footprint, i.e. no dynamic memory allocation ever takes place. Thus, an optional object models an object, not a pointer, even though the 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 a value of type
T. - The object is assigned from another
optionalthat contains a value.
The object does not contain a value in the following conditions:
- The object is default-initialized.
- The object is initialized with a value of std::experimental::nullopt_t or an
optionalobject that does not contain a value. - The object is assigned from a value of std::experimental::nullopt_t or from an
optionalthat does not contain a value.
Template parameters
| T | - | the type of the value to manage initialization state for. The type must meet the requirements of Destructible. |
Member types
| Member type | Definition |
value_type
|
T
|
Member functions
| constructs the optional object (public member function) | |
| destroys the contained value, if there is one (public member function) | |
| assigns contents (public member function) | |
Observers | |
| accesses the contained value (public member function) | |
| checks whether the object contains a value (public member function) | |
| returns the contained value (public member function) | |
| returns the contained value if available, another value otherwise (public member function) | |
Modifiers | |
| exchanges the contents (public member function) | |
| constructs the contained value in-place (public member function) | |
Member objects
| Member name | Definition |
val (private)
|
pointer to the contained value (which points at a data member of the same object), the name is for exposition only |
Non-member functions
compares optional objects (function template) | |
creates an optional object (function template) | |
| specializes the std::swap algorithm (function) |
Helper classes
| specializes the std::hash algorithm (class template specialization) | |
(library fundamentals TS) |
indicator of optional type with uninitialized state (class) |
(library fundamentals TS) |
disambiguation tag type for in-place construction of optional types (class) |
(library fundamentals TS) |
exception indicating checked access to an optional that doesn't contain a value (class) |
Helper objects
(library fundamentals TS) |
an object of type nullopt_t (function) |
(library fundamentals TS) |
an object of type std::experimental::in_place_t (function) |