std::optional - cppreference.com

##### cppreference.com

##### Search

Create account

##### Namespaces

- Page
- Discussion

##### Variants

##### Views

- View
- Edit
- History

##### Actions

# std::optional

From cppreference.com
< cpp‎ | utility

Defined in header `<optional>` |  |
template< class T > class optional; |  | (since C++17)

The class template `std::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::nullopt_t or an `optional` object that does not contain a value.
- The object is assigned from a value of std::nullopt_t or from an `optional` that does not contain a value

There are no optional references, a program is ill-formed if it instantiates optional with a reference type.

### [edit] Template parameters

T | - | the type of the value to manage initialization state for. The type must meet the requirements of `Destructible`

### [edit] Member types

Member type | Definition
`value_type` | `T`

### [edit] Member functions

(constructor) | constructs the optional object (public member function) [edit]
(destructor) | destroys the contained value, if there is one (public member function) [edit]
operator= | assigns contents (public member function) [edit]
##### Observers
operator->operator* | accesses the contained value (public member function) [edit]
operator boolhas_value | checks whether the object contains a value (public member function) [edit]
value | returns the contained value (public member function) [edit]
value_or | returns the contained value if available, another value otherwise (public member function) [edit]
##### Modifiers
swap | exchanges the contents (public member function) [edit]
reset | destroys any contained value (public member function) [edit]
emplace | constructs the contained value in-place (public member function) [edit]

### [edit] Non-member functions

operator==operator!=operator<operator<=operator>operator>= (C++17) | compares `optional` objects (function template) [edit]
make_optional (C++17) | creates an `optional` object (function template) [edit]
std::swap(std::optional) (C++17) | specializes the std::swap algorithm (function) [edit]

### [edit] Helper classes

std::hash<std::optional> (C++17) | specializes the std::hash algorithm (class template specialization) [edit]
nullopt_t (C++17) | indicator of optional type with uninitialized state (class) [edit]
bad_optional_access (C++17) | exception indicating checked access to an optional that doesn't contain a value (class) [edit]

### [edit] Helpers

nullopt (C++17) | an object of type `nullopt_t` (constant) [edit]
in_place in_place_type in_place_index in_place_t in_place_type_t in_place_index_t (C++17) | in-place construction tag (class template) [edit]

### [edit] Example

Run this code

    #include <string>
    #include <iostream>
    #include <optional>

    // 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";
        else
            return {};
    }

    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 = create(true)) {
            std::cout << "create(true) returned " << *str << '\n';
        }
    }

Output:

    create(false) returned empty
    create(true) returned Godzilla

Retrieved from "http://en.cppreference.com/mwiki/index.php?title=cpp/utility/optional&oldid=90258"