Namespaces
Variants

    cpp/experimental/optional: Difference between revisions

    From cppreference.com
    ← Older edit
    improve desc, resurrect ''engaged''/''disengaged'' wording
    Andreas Krug (talk | contribs)
    8,213 edits
    m fmt
     
    (25 intermediate revisions by 9 users not shown)
    Line 1: Line 1:
    {{cpp/title|optional}}
    {{cpp/title|optional}}
    {{cpp/utility/optional/navbar}}
    {{cpp//optional/navbar}}
    {{ddcl | header=optional | notes={{mark since c++14}} |
    {{|=optional|{{mark since c++}}
     
    |
    template< class T >
    template< class T >
    class optional;
    class optional;
    }}
    }}


    The class template {{tt|std::optional}} manages an ''optional'' contained value. The value may be in either initialized or uninitialized state.
    The class template {{tt|std::optional}} manages an ''optional'' contained value.value may be .


    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|std::pair<T,bool>}}, {{tt|optional}} handles expensive to construct objects well and is more readable, as the intent is expressed explicitly.
    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|std::pair<T,bool>}}, {{tt|optional}} handles expensive to construct objects well and is more readable, as the intent is expressed explicitly.


    The value is guaranteed to be allocated within the {{tt|optional}} object itself, i.e. no dynamic memory allocation ever takes place. Thus, {{tt|optional}} object models an object, not a pointer, even though the {{lc|operator*()}} and {{lc|operator->()}} are defined.
    {{tt|optional}} not a .


    A {{tt|optional}} object with a value in initialized state is called ''engaged'', whereas if the value is in uninitialized state, the object is called ''disengaged''.
    {{tt|optional}} a value'', the value is , the .


    The {{tt|optional}} object is ''engaged'' on the following conditions:
    {{|}} object ''''


    * The object is initialized with a value of type {{tt|T}}
    The {{tt|}}


    * The object is assigned an ''engaged'' {{tt|optional}}.
    * The object is assigned {{tt|optional}} .


    The object is ''disengaged'' on the following conditions:
    The object '''' the following conditions:


    * The object is default-initialized.
    * The object is default-initialized.
     
    * The object is initialized with a value of {{lc|std::nullopt_t}} or {{tt|optional}} object .
    * The object is initialized with a value of {{lc|std::nullopt_t}} or a ''disengaged'' {{tt|optional}} object.
    * The object is assigned a value of {{lc|std::nullopt_t}} or {{tt|optional}} .
     
    * The object is assigned a value of {{lc|std::nullopt_t}} or a ''disengaged'' {{tt|optional}}.


    ===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 {{concept|Destructible}} }}
    {{par|T|the type of the value to manage initialization state for. The type must meet the requirements of {{|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/utility/optional/dsc constructor}}
    {{dsc inc|cpp//optional/dsc constructor}}
    {{dsc inc | cpp/utility/optional/dsc destructor}}
    {{dsc inc|cpp//optional/dsc destructor}}
    {{dsc inc | cpp/utility/optional/dsc operator{{=}}}}
    {{dsc inc|cpp//optional/dsc operator{{=}}}}


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


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


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


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

    Latest revision as of 09:34, 28 November 2023

     
    C++
     
    Experimental
    Technical Specification
    Filesystem library (filesystem TS)
    Library fundamentals (library fundamentals TS)
    Library fundamentals 2 (library fundamentals TS v2)
    Library fundamentals 3 (library fundamentals TS v3)
    Extensions for parallelism (parallelism TS)
    Extensions for parallelism 2 (parallelism TS v2)
    Extensions for concurrency (concurrency TS)
    Extensions for concurrency 2 (concurrency TS v2)
    Concepts (concepts TS)
    Ranges (ranges TS)
    Reflection (reflection TS)
    Mathematical special functions (special functions TR)
    Experimental Non-TS
    Pattern Matching
    Linear Algebra
    std::execution
    Contracts
    2D Graphics
     
    Library fundamentals
     
    std::experimental::optional
     
    Merged into ISO C++ The functionality described on this page was merged into the mainline ISO C++ standard as of 3/2016, see std::optional (since C++17)
    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 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 a value of std::experimental::nullopt_t or an optional object that does not contain a value.
    • The object is assigned from a value of std::experimental::nullopt_t or from an optional that 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) [edit]
    		destroys the contained value, if there is one
    (public member function) [edit]
    		assigns contents
    (public member function) [edit]
    Observers
    		accesses the contained value
    (public member function) [edit]
    		checks whether the object contains a value
    (public member function) [edit]
    		returns the contained value
    (public member function) [edit]
    		returns the contained value if available, another value otherwise
    (public member function) [edit]
    Modifiers
    		exchanges the contents
    (public member function) [edit]
    		constructs the contained value in-place
    (public member function) [edit]

    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) [edit]
    		creates an optional object
    (function template) [edit]
    		specializes the std::swap algorithm
    (function) [edit]

    Helper classes

    		 specializes the std::hash algorithm
    (class template specialization) [edit]
    (library fundamentals TS)
    		 indicator of optional type with uninitialized state
    (class) [edit]
    (library fundamentals TS)
    		 disambiguation tag type for in-place construction of optional types
    (class) [edit]
    (library fundamentals TS)
    		 exception indicating checked access to an optional that doesn't contain a value
    (class) [edit]

    Helper objects

    (library fundamentals TS)
    		 an object of type nullopt_t
    (function) [edit]
    (library fundamentals TS)
    		 an object of type std::experimental::in_place_t
    (function) [edit]