Namespaces
Variants

    cpp/experimental/optional: Difference between revisions

    From cppreference.com
    ← Older edit
    drop ''engaged''/''disengaged'' wording. ''initialized''/''uninitialized'' is much clearer (though a bit imprecise)
    Andreas Krug (talk | contribs)
    8,213 edits
    m fmt
     
    (34 intermediate revisions by 11 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|optional}} manages an ''optional'' contained value. The value may be in either initialized or initialized state during the lifetime of {{tt|optional}} object. The class manages the initialization state of the contained value and its lifetime. The value is guaranteed to be allocated within the {{tt|optional}} object itself, i.e. no dynamic memory allocation ever takes place.
    The class template {{tt|optional}} manages an ''optional'' contained value. value may or be .


    The contained value of an {{tt|optional}} object is in initialized state on the following conditions:
    value of {{tt|optional}} is the


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


    * The object is assigned an {{tt|optional}} object with an initialized value.
    object an {{tt|optional}} object an .


    The contained value is uninitialized on the following conditions:
    is the


    * The object is default-initialized.
     
    * The object is initialized
    .


    * The object is initialized with a value of {{c|std::nullopt_t}} or a {{tt|optional}} object with an uninitialized value.
    The object a value:


    * The object is assigned a value of {{c|std::nullopt_t}} or a {{tt|optional}} object with an uninitialized value.
    * The object is
    a value of {{|std::nullopt_t}} or {{tt|optional}} object
    an value.


    ===Template parameters===
    ===Template parameters===
    {{param list begin}}
    {{begin}}
    {{param list item | T | the type of the value to manage initialization state for. The type must meet the requirements of {{concept|Destructible}} }}
    {{|T|the type of the value to manage initialization state for. The type must meet the requirements of {{|Destructible}}}}
    {{param list end}}
    {{end}}


    ===Member types===
    ===Member types===
    {{dcl list begin}}
    {{begin}}
    {{dcl list hitem | Member type | Definition}}
    {{hitem|Member type|Definition}}
    {{dcl list item | {{tt|value_type}} | {{tt|T}} }}
    {{|{{tt|value_type}}|{{tt|T}}}}
    {{dcl list end}}
    {{end}}


    ===Member functions===
    ===Member functions===
    {{dcl list begin}}
    {{begin}}
    {{dcl list template | cpp/utility/optional/dcl list constructor}}
    {{|cpp//optional/constructor}}
    {{dcl list template | cpp/utility/optional/dcl list destructor}}
    {{|cpp//optional/destructor}}
    {{dcl list template | cpp/utility/optional/dcl list operator{{=}}}}
    {{|cpp//optional/operator{{=}}}}


    {{dcl list h2 | Observers}}
    {{h2|Observers}}
    {{dcl list template | cpp/utility/optional/dcl list operator*}}
    {{|cpp//optional/operator*}}
    {{dcl list template | cpp/utility/optional/dcl list operator bool}}
    {{|cpp//optional/operator bool}}
    {{dcl list template | cpp/utility/optional/dcl list value}}
    {{|cpp//optional/value}}
    {{dcl list template | cpp/utility/optional/dcl list value_or}}
    {{|cpp//optional/value_or}}


    {{dcl list h2 | Modifiers}}
    {{h2|Modifiers}}
    {{dcl list template | cpp/utility/optional/dcl list swap}}
    {{|cpp//optional/swap}}
    {{dcl list template | cpp/utility/optional/dcl list emplace}}
    {{|cpp//optional/emplace}}
    {{dcl list end}}
    {{
     
    end}}


    ===Non-member functions===
    ===Non-member functions===
    {{dcl list begin}}
    {{begin}}
    {{dcl list template | cpp/utility/optional/dcl list operator_cmp}}
    {{|cpp//optional/operator_cmp}}
    {{dcl list template | cpp/utility/optional/dcl list make_optional}}
    {{|cpp//optional/make_optional}}
    {{dcl list template | cpp/utility/optional/dcl list swap2}}
    {{|cpp//optional/swap2}}
    {{dcl list end}}
    {{end}}


    ===Helper classes===
    ===Helper classes===
    {{dcl list begin}}
    {{begin}}
    {{dcl list template | cpp/utility/optional/dcl list hash}}
    {{|cpp//optional/hash}}
    {{dcl list end}}
    {{
     
    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]