Namespaces
Variants

    cpp/experimental/optional: Difference between revisions

    From cppreference.com
    ← Older edit
    No edit summary
    Andreas Krug (talk | contribs)
    8,213 edits
    m fmt
     
    (13 intermediate revisions by 6 users not shown)
    Line 1: Line 1:
    {{cpp/title|n=experimental::|optional}}
    {{cpp/title|optional}}
    {{cpp/experimental/optional/navbar}}
    {{cpp/experimental/optional/navbar}}
    {{fmbox | style=font-size: 0.8em; background-color:#ffffbb | text=After reviewing national body comments to N3690, this library component was voted out from C++14 working paper into a separate Technical Specification. It is not a part of the draft C++14 as of n3797.}}
    {{fmbox|style=font-size: 0.8em|text=C++into the C++ as of {{|::}}
    {{fmbox | style=font-size: 0.8em; background-color:#ffffbb | text=At the moment the documentation is written according to the specification in N3690}}<!-- Have there been any changes? This needs checking-->
     
    {{ddcl | header=optional | since=libfund_ts |
    {{ddcl|header=optional|since=libfund_ts|
    template< class T >
    template< class T >
    class optional;
    class optional;
    }}
    }}


    The class template {{tt|std::experimental::optional}} manages an ''optional'' contained value, i.e. a value that semantically may not be present.
    The class template {{tt|std::experimental::optional}} manages an ''optional'' contained value, i.e. a value that 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|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, an {{tt|optional}} object models an object, not a pointer, even though the {{lc|operator*()}} and {{lc|operator->()}} are defined.
    {{tt|optional}} not a .


    The value inside an {{tt|optional}} object may be in either an initialized or uninitialized state.  An {{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''.
    value {{tt|optional}} object an {{tt|optional}} object a , 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::experimental::nullopt_t}} or {{tt|optional}} object .
    * The object is initialized with a value of {{lc|std::experimental::nullopt_t}} or a ''disengaged'' {{tt|optional}} object.
    * The object is assigned a value of {{lc|std::experimental::nullopt_t}} or {{tt|optional}} .
     
    * The object is assigned a value of {{lc|std::experimental::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/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}}


    ===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 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]