std::optional<T>::optional

From cppreference.com
< cpp‎ | utility‎ | optional
 
C++
 
Utilities library
General utilities
Date and time
Function objects
Formatting library (C++20)
(C++11)
Relational operators (deprecated in C++20)
Integer comparison functions
(C++20)(C++20)(C++20)   
(C++20)
Swap and type operations
(C++20)
(C++14)
(C++11)
(C++23)
(C++11)
(C++23)
(C++11)
(C++11)
(C++17)
Common vocabulary types
(C++11)
(C++17)
(C++17)
(C++17)
(C++11)
(C++11)
(C++17)
(C++17)
(C++23)
Elementary string conversions
(C++17)
(C++17)
(C++17)
 
std::optional
Member functions
optional::optional
(C++17)
(C++17)
(C++17)
Observers
(C++17)(C++17)
(C++17)(C++17)
(C++17)
(C++17)
Monadic operations
(C++23)
(C++23)
(C++23)
Modifiers
(C++17)
(C++17)
(C++17)
Non-member functions
(C++17)(C++17)(C++17)(C++17)(C++17)(C++17)(C++20)
(C++17)
(C++17)
Deduction guides
Helper classes
(C++17)
(C++17)
(C++17)
(C++17)
Helper objects
(C++17)
(C++17)
 
constexpr optional() noexcept;
constexpr optional( std::nullopt_t ) noexcept;
 (1) (since C++17)
constexpr optional( const optional& other );
 (2) (since C++17)
constexpr optional( optional&& other ) noexcept(/* see below */);
 (3) (since C++17)
(4)
template < class U >
optional( const optional<U>& other );
 (since C++17)
(until C++20)
(conditionally explicit)
template < class U >
constexpr optional( const optional<U>& other );
 (since C++20)
(conditionally explicit)
(5)
template < class U >
optional( optional<U>&& other );
 (since C++17)
(until C++20)
(conditionally explicit)
template < class U >
constexpr optional( optional<U>&& other );
 (since C++20)
(conditionally explicit)
template< class... Args >
constexpr explicit optional( std::in_place_t, Args&&... args );
 (6) (since C++17)
template< class U, class... Args >

constexpr explicit optional( std::in_place_t,
                             std::initializer_list<U> ilist,

                             Args&&... args );
 (7) (since C++17)
template < class U = T >
constexpr optional( U&& value );
 (8) (since C++17)
(conditionally explicit)

Constructs a new optional object.

1) Constructs an object that does not contain a value.
2) Copy constructor: If other contains a value, initializes the contained value as if direct-initializing (but not direct-list-initializing) an object of type T with the expression *other. If other does not contain a value, constructs an object that does not contain a value.
3) Move constructor: If other contains a value, initializes the contained value as if direct-initializing (but not direct-list-initializing) an object of type T with the expression std::move(*other) and does not make other empty: a moved-from optional still contains a value, but the value itself is moved from. If other does not contain a value, constructs an object that does not contain a value.
4) Converting copy constructor: If other doesn't contain a value, constructs an optional object that does not contain a value. Otherwise, constructs an optional object that contains a value, initialized as if direct-initializing (but not direct-list-initializing) an object of type T with the expression *other.
5) Converting move constructor: If other doesn't contain a value, constructs an optional object that does not contain a value. Otherwise, constructs an optional object that contains a value, initialized as if direct-initializing (but not direct-list-initializing) an object of type T with the expression std::move(*other).
6) Constructs an optional object that contains a value, initialized as if direct-initializing (but not direct-list-initializing) an object of type T from the arguments std::forward<Args>(args)....
  • If the selected constructor of T is a constexpr constructor, this constructor is a constexpr constructor.
  • The function does not participate in the overload resolution unless std::is_constructible_v<T, Args...> is true
7) Constructs an optional object that contains a value, initialized as if direct-initializing (but not direct-list-initializing) an object of type T from the arguments ilist, std::forward<Args>(args)....
  • If the selected constructor of T is a constexpr constructor, this constructor is a constexpr constructor.
  • The function does not participate in the overload resolution unless std::is_constructible_v<T, std::initializer_list<U>&, Args&&...> is true
8) Constructs an optional object that contains a value, initialized as if direct-initializing (but not direct-list-initializing) an object of type T with the expression std::forward<U>(value).

Parameters

other - another optional object whose contained value is copied
value - value with which to initialize the contained value
args... - arguments with which to initialize the contained value
ilist - initializer list with which to initialize the contained value

Exceptions

2) Throws any exception thrown by the constructor of T.
3) Throws any exception thrown by the constructor of T. Has the following
noexcept specification:  
noexcept(std::is_nothrow_move_constructible<T>::value)
.
4-8) Throws any exception thrown by the constructor of T.

Deduction guides

Example

Run this code
#include <optional>
#include <iostream>
#include <string>
int main()
{
    std::optional<int> o1, // empty
                       o2 = 1, // init from rvalue
                       o3 = o2; // copy-constructor
 
    // calls std::string( initializer_list<CharT> ) constructor
    std::optional<std::string> o4(std::in_place, {'a', 'b', 'c'});
 
    // calls std::string( size_type count, CharT ch ) constructor
    std::optional<std::string> o5(std::in_place, 3, 'A');
 
    // Move-constructed from std::string using deduction guide to pick the type
 
    std::optional o6(std::string{"deduction"});
 
    std::cout << *o2 << ' ' << *o3 << ' ' << *o4 << ' ' << *o5  << ' ' << *o6 << '\n';
}

Output: 

1 1 abc AAA deduction

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior
P0602R4 C++17 copy/move constructors may not be trivial even if underlying constructor is trivial required to propagate triviality
P2231R1 C++20 converting constructors from another optional was not constexpr
while the required operations can be in C++20 		made constexpr

See also

(C++17)
 creates an optional object
(function template)
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/utility/optional/optional&oldid=130458"