This paper revises [P0323r3] by applying feedback obtained from LEWG and EWG. The previous paper contains motivation, design rationale, implementability information, sample usage, history, alternative designs, and related types. This update only contains wording and open questions because its purpose is twofold:
-
Present appropriate wording for including in the Library Fundamentals TS v3.
-
List open questions which the TS should aim to answer.
1. Wording
Below, substitute the �
character with a number or name the editor finds
appropriate for the sub-section.
1.1. �.� Unexpected objects [unexpected]
1.2. �.�.1 General [unexpected.general]
This subclause describes class template
that contain objects
representing an unexpected outcome.
1.3. �.�.2 Header < experimental / unexpected >
synopsis [unexpected.synop]
namespace std { namespace experimental { inline namespace fundamentals_v3 { // �.�.3, Unexpected object type template < class E > class unexpected ; // �.�.4, Unexpected relational operators template < class E > constexpr bool operator == ( const unexpected < E >& , const unexpected < E >& ); template < class E > constexpr bool operator != ( const unexpected < E >& , const unexpected < E >& ); }}}
A program that needs the instantiation of template
for a reference
type or
is ill-formed.
1.4. �.�.3 Unexpected object type [unexpected.object]
template < class E > class unexpected { public : unexpected () = delete ; constexpr explicit unexpected ( const E & ); constexpr explicit unexpected ( E && ); constexpr const E & value () const & ; constexpr E & value () & ; constexpr E && value () && ; constexpr E const && value () const && ; private : E val ; // exposition only };
If
is void the program is ill formed.
constexpr explicit unexpected ( const E & );
Effects: Build an
by copying the parameter to the internal storage
.
constexpr explicit unexpected ( E && );
Effects: Build an
by moving the parameter to the internal storage
.
constexpr const E & value () const & ; constexpr E & value () & ;
Returns:
.
constexpr E && value () && ; constexpr E const && value () const && ;
Returns:
.
1.5. �.�.4 Unexpected relational operators [unexpected.relational_op]
template < class E > constexpr bool operator == ( const unexpected < E >& x , const unexpected < E >& y );
Requires:
shall meet the requirements of EqualityComparable.
Returns:
.
Remarks: Specializations of this function template, for which
is a core constant expression, shall be constexpr functions.
Requires:template < class E > constexpr bool operator != ( const unexpected < E >& x , const unexpected < E >& y );
E
shall meet the requirements of EqualityComparable.
Returns:
.
Remarks: Specializations of this function template, for which
is a core constant expression, shall be constexpr functions.
1.6. �.� Expected objects [expected]
1.7. �.�.1 In general [expected.general]
This subclause describes class template expected that represents expected
objects. An
object is an object that contains the storage for
another object and manages the lifetime of this contained object
,
alternatively it could contain the storage for another unexpected object
. The contained object may not be initialized after the expected object has
been initialized, and may not be destroyed before the expected object has been
destroyed. The initialization state of the contained object is tracked by the
expected object.
1.8. �.�.2 Header < experimental / expected >
synopsis [expected.synop]
namespace std { namespace experimental { inline namespace fundamentals_v3 { // �.�.4, Expected for object types template < class T , class E > class expected ; // �.�.5, Expected specialization for void template < class E > class expected < void , E > ; // �.�.6, unexpect tag struct unexpect_t { unexpect_t () = default ; }; inline constexpr unexpect_t unexpect {}; // �.�.7, class bad_expected_access template < class E > class bad_expected_access ; // �.�.8, Specialization for void. template <> class bad_expected_access < void > ; // �.�.9, Expected relational operators template < class T , class E > constexpr bool operator == ( const expected < T , E >& , const expected < T , E >& ); template < class T , class E > constexpr bool operator != ( const expected < T , E >& , const expected < T , E >& ); // �.�.10, Comparison with T template < class T , class E > constexpr bool operator == ( const expected < T , E >& , const T & ); template < class T , class E > constexpr bool operator == ( const T & , const expected < T , E >& ); template < class T , class E > constexpr bool operator != ( const expected < T , E >& , const T & ); template < class T , class E > constexpr bool operator != ( const T & , const expected < T , E >& ); // �.�.10, Comparison with unexpected<E> template < class T , class E > constexpr bool operator == ( const expected < T , E >& , const unexpected < E >& ); template < class T , class E > constexpr bool operator == ( const unexpected < E >& , const expected < T , E >& ); template < class T , class E > constexpr bool operator != ( const expected < T , E >& , const unexpected < E >& ); template < class T , class E > constexpr bool operator != ( const unexpected < E >& , const expected < T , E >& ); // �.�.11, Specialized algorithms void swap ( expected < T , E >& , expected < T , E >& ) noexcept ( see below ); }}}
A program that necessitates the instantiation of template
with
for a reference type or for possibly cv-qualified types
,
or
or
for a reference type or
is ill-formed.
1.9. �.�.3 Definitions [expected.defs]
An instance of
is said to be valued if it contains a value of
type
. An instance of
is said to be unexpected if it
contains an object of type
.
1.10. �.�.4 expected for object types [expected.object]
template < class T , class E > class expected { public : typedef T value_type ; typedef E error_type ; typedef unexpected < E > unexpected_type ; template < class U > struct rebind { using type = expected < U , error_type > ; }; // �.�.4.1, constructors constexpr expected (); constexpr expected ( const expected & ); constexpr expected ( expected && ) noexcept ( see below ); template < class U , class G > EXPLICIT constexpr expected ( const expected < U , G >& ); template < class U , class G > EXPLICIT constexpr expected ( expected < U , G >&& ); template < class U = T > EXPLICIT constexpr expected ( U && v ); template < class ... Args > constexpr explicit expected ( in_place_t , Args && ...); template < class U , class ... Args > constexpr explicit expected ( in_place_t , initializer_list < U > , Args && ...); template < class G = E > constexpr expected ( unexpected < G > const & ); template < class G = E > constexpr expected ( unexpected < G > && ); template < class ... Args > constexpr explicit expected ( unexpect_t , Args && ...); template < class U , class ... Args > constexpr explicit expected ( unexpect_t , initializer_list < U > , Args && ...); // �.�.4.2, destructor ~ expected (); // �.�.4.3, assignment expected & operator = ( const expected & ); expected & operator = ( expected && ) noexcept ( see below ); template < class U = T > expected & operator = ( U && ); template < class G = E > expected & operator = ( const unexpected < G >& ); template < class G = E > expected & operator = ( unexpected < G >&& ) noexcept ( see below ); template < class ... Args > void emplace ( Args && ...); template < class U , class ... Args > void emplace ( initializer_list < U > , Args && ...); // �.�.4.4, swap void swap ( expected & ) noexcept ( see below ); // �.�.4.5, observers constexpr const T * operator -> () const ; constexpr T * operator -> (); constexpr const T & operator * () const & ; constexpr T & operator * () & ; constexpr const T && operator * () const && ; constexpr T && operator * () && ; constexpr explicit operator bool () const noexcept ; constexpr bool has_value () const noexcept ; constexpr const T & value () const & ; constexpr T & value () & ; constexpr const T && value () const && ; constexpr T && value () && ; constexpr const E & error () const & ; constexpr E & error () & ; constexpr const E && error () const && ; constexpr E && error () && ; template < class U > constexpr T value_or ( U && ) const & ; template < class U > T value_or ( U && ) && ; private : bool has_val ; // exposition only union { value_type val ; // exposition only unexpected_type unexpect ; // exposition only }; };
Valued instances of
where
and
are of object type shall
contain a value of type
or a value of type
within its own storage. These
values are referred to as the contained or the unexpected value of the
object. Implementations are not permitted to use additional storage,
such as dynamic memory, to allocate its contained or unexpected value. The
contained or unexpected value shall be allocated in a region of the
storage suitably aligned for the type
and
. Members
,
and
are provided for exposition
only. Implementations need not provide those members.
indicates
whether the expected object’s contained value has been initialized (and not yet
destroyed); when
is true
points to the contained value, and when
it is false
points to the erroneous value.
must be
or shall be object type and shall satisfy the requirements of
(Table 27).
shall be object type and shall satisfy the requirements of
(Table 27).
1.11. �.�.4.1 Constructors [expected.object.ctor]
constexpr expected ();
Effects: Initializes the contained value as if direct-non-list-initializing an
object of type
with the expression
(if
is not
).
Postconditions:
contains a value.
Throws: Any exception thrown by the default constructor of
(nothing if
is
).
Remarks: If value-initialization of
is a constexpr constructor or
is
this constructor shall be constexpr. This constructor shall be defined as
deleted unless
or
is
.
constexpr expected ( const expected & rhs );
Effects: If
contains a value, initializes the contained value as if
direct-non-list-initializing an object of type
with the expression
(if
is not
).
If
does not contain a value initializes the unexpected value as if
direct-non-list-initializing an object of type
with the
expression
.
Postconditions:
.
Throws: Any exception thrown by the selected constructor of
if
is not
or by the selected constructor of
.
Remarks: This constructor shall be defined as deleted unless
or
is
and
. If
is true
or
is
and
is true
,
this constructor shall be a constexpr constructor.
constexpr expected ( expected && rhs ) noexcept ( see below );
Effects: If
contains a value initializes the contained value as if
direct-non-list-initializing an object of type
with the expression
(if
is not
).
If
does not contain a value initializes the unexpected value as if
direct-non-list-initializing an object of type
with the
expression
.
is unchanged.
Postconditions:
.
Throws: Any exception thrown by the selected constructor of
if
is not
or by the selected constructor of
.
Remarks: The expression inside
is equivalent to:
T
and
. This constructor shall not participate in
overload resolution unless
. If
is true
or
is
and
is true
,
this constructor shall be a constexpr constructor.
template < class U , class G > EXPLICIT constexpr expected ( const expected < U , G >& rhs );
Effects: If
contains a value initializes the contained value as if
direct-non-list-initializing an object of type
with the expression
(if
is not
).
If
does not contain a value initializes the unexpected value as if
direct-non-list-initializing an object of type
with the
expression
.
Postconditions:
.
Throws: Any exception thrown by the selected constructor of
if
is not
or by the selected constructor of
.
Remarks: This constructor shall not participate in overload resolution unless:
-
isis_constructible_v < T , const U &> true
or
andT
areU
,void -
isis_constructible_v < E , const G &> true
, -
isis_constructible_v < T , expected < U , G >&> false
or
andT
areU
,void -
isis_constructible_v < T , expected < U , G >&&> false
or
andT
areU
,void -
isis_constructible_v < T , const expected < U , G >&> false
or
andT
areU
,void -
isis_constructible_v < T , const expected < U , G >&&> false
or
andT
areU
,void -
isis_convertible_v < expected < U , G >& , T > false
or
andT
areU
,void -
isis_convertible_v < expected < U , G >&& , T > false
or
andT
areU
,void -
isis_convertible_v < const expected < U , G >& , T > false
or
andT
areU
, andvoid -
isis_convertible_v < const expected < U , G >&& , T > false
or
andT
areU
.void
The constructor is explicit if and only if
is not
and
is false or
is
false.
template < class U , class G > EXPLICIT constexpr expected ( expected < U , G >&& rhs );
Effects: If
contains a value initializes the contained value as if
direct-non-list-initializing an object of type
with the expression
or nothing if
is
.
If
does not contain a value initializes the unexpected value as if
direct-non-list-initializing an object of type
with the
expression
.
is unchanged
Postconditions:
.
Throws: Any exception thrown by the selected constructor of
if
is not
or by the selected constructor of
.
Remarks: This constructor shall not participate in overload resolution unless:
-
isis_constructible_v < T , U &&> true
, -
isis_constructible_v < E , G &&> true
, -
isis_constructible_v < T , expected < U , G >&> false
or
andT
areU
,void -
isis_constructible_v < T , expected < U , G >&&> false
or
andT
areU
,void -
isis_constructible_v < T , const expected < U , G >&> false
or
andT
areU
,void -
isis_constructible_v < T , const expected < U , G >&&> false
or
andT
areU
,void -
isis_convertible_v < expected < U , G >& , T > false
or
andT
areU
,void -
isis_convertible_v < expected < U , G >&& , T > false
or
andT
areU
,void -
isis_convertible_v < const expected < U , G >& , T > false
or
andT
areU
, andvoid -
isis_convertible_v < const expected < U , G >&& , T > false
or
andT
areU
.void
The constructor is explicit if and only if
is false
or
is false.
template < class U = T > EXPLICIT constexpr expected ( U && v );
Effects: Initializes the contained value as if direct-non-list-initializing an
object of type
with the expression
.
Postconditions:
contains a value.
Throws: Any exception thrown by the selected constructor of
.
Remarks: If
's selected constructor is a constexpr constructor, this
constructor shall be a constexpr constructor. This constructor shall not
participate in overload resolution unless
is not
and
is true
,
is false
,
is false, and
is false. The constructor is explicit if
and only if
is false.
template < class ... Args > constexpr explicit expected ( in_place_t , Args && ... args );
Effects: Initializes the contained value as if direct-non-list-initializing an
object of type
with the arguments
if
is not
.
Postconditions:
contains a value.
Throws: Any exception thrown by the selected constructor of
if
is not
.
Remarks: If
's constructor selected for the initialization is a constexpr
constructor, this constructor shall be a constexpr constructor. This
constructor shall not participate in overload resolution unless
is
and
or
is not
and
.
template < class U , class ... Args > constexpr explicit expected ( in_place_t , initializer_list < U > il , Args && ... args );
Effects: Initializes the contained value as if direct-non-list-initializing an
object of type
with the arguments
.
Postconditions:
contains a value.
Throws: Any exception thrown by the selected constructor of
.
Remarks: If
's constructor selected for the initialization is a constexpr
constructor, this constructor shall be a constexpr constructor. This
constructor shall not participate in overload resolution unless
is not
and
.
template < class G = E > EXPLICIT constexpr expected ( unexpected < G > const & e );
Effects: Initializes the unexpected value as if direct-non-list-initializing
an object of type
with the expression
.
Postconditions:
does not contain a value.
Throws: Any exception thrown by the selected constructor of
Remark: If
's selected constructor is a constexpr constructor,
this constructor shall be a constexpr constructor. This constructor shall not
participate in overload resolution unless
. The
constructor is explicit if and only if
is false.
template < class G = E > EXPLICIT constexpr expected ( unexpected < G >&& e );
Effects: Initializes the unexpected value as if direct-non-list-initializing
an object of type
with the expression
.
Postconditions:
does not contain a value.
Throws: Any exception thrown by the selected constructor of
Remark: If
's selected constructor is a constexpr constructor,
this constructor shall be a constexpr constructor. The expression inside
is equivalent to:
. This
constructor shall not participate in overload resolution unless
. The constructor is explicit if and only if
is false.
template < class ... Args > constexpr explicit expected ( unexpect_t , Args && ... args );
Effects: Initializes the unexpected value as if direct-non-list-initializing
an object of
with the arguments
.
Postconditions:
does not contain a value.
Throws: Any exception thrown by the selected constructor of
Remarks: If
's constructor selected for the initialization is a
constexpr constructor, this constructor shall be a constexpr constructor. This
constructor shall not participate in overload resolution unless
.
template < class U , class ... Args > constexpr explicit expected ( unexpect_t , initializer_list < U > il , Args && ... args );
Effects: Initializes the unexpected value as if direct-non-list-initializing
an object of
with the arguments
.
Postconditions:
does not contain a value.
Throws: Any exception thrown by the selected constructor of
.
Remarks: If
's constructor selected for the initialization is a
constexpr constructor, this constructor shall be a constexpr constructor. This
constructor shall not participate in overload resolution unless
.
1.12. �.�.4.2 Destructor [expected.object.dtor]
~ expected ();
Effects: If
is not
and
and
contains a value, calls
. If
and
does not contain a value, calls
.
Remarks: If
is
or
is true
then this destructor shall be a
trivial destructor.
1.13. �.�.4.3 Assignment [expected.object.assign]
expected < T , E >& operator = ( const expected < T , E >& rhs ) noexcept ( see below );
Effects:
If
contains a value and
contains a value,
-
assigns
to the contained value* rhs
ifval
is notT
;void
otherwise, if
does not contain a value and
does not contain a
value,
-
assigns
to the unexpected valueunexpected ( rhs . error ())
;unexpect
otherwise, if
contains a value and
does not contain a value,
-
if
isT void -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected < E >
. Eitherunexpected ( rhs . error ()) -
The didn’t throw, so mark the expected as holding a
(which can’t throw), orunexpected < E > -
the constructor did throw, an nothing was changed.
-
-
otherwise
is notT
, ifvoid is_nothrow_copy_constructible_v < E > -
destroys the contained value by calling
,val . T ::~ T () -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected < E >
.unexpected ( rhs . error ())
-
-
otherwise if
is_nothrow_move_constructible_v < E > -
constructs a new
on the stack fromunexpected < E > tmp
(this can throw),* rhs -
destroys the contained value by calling
,val . T ::~ T () -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected < E >
.unexpected ( rhs . error ())
-
otherwise as
-
constructs a new
on the stack fromT tmp
(this can throw),* this -
destroys the contained value by calling
,val . T ::~ T () -
initializes the contained value as if direct-non-list-initializing an object of type
withunexpected < E >
. Either,unexpected ( rhs . error ()) -
the last constructor didn’t throw, so mark the expected as holding a
(which can’t throw), orunexpected < E > -
the last constructor did throw, so move-construct the
from the stackT
back into the expected storage (which can’t throw astmp
isis_nothrow_move_constructible_v < T > true
), and rethrow the exception.
-
otherwise
does not contain a value and
contains a value
-
if
isT
destroys the unexpected value by callingvoid unexpect . ~ unexpected < E > () -
otherwise
is notT
, ifvoid is_nothrow_copy_constructible_v < T > -
destroys the unexpected value by calling
unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
;* rhs
-
-
otherwise
is notT
, ifvoid is_nothrow_copy_constructible_v < T > -
destroys the unexpected value by calling
unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
;move ( * rhs )
-
-
otherwise if
is_nothrow_move_constructible_v < T > -
constructs a new
on the stack fromT tmp
(this can throw),* rhs -
destroys the unexpected value by calling
unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
;move ( tmp )
-
-
otherwise as
is_nothrow_move_constructible_v < E > -
constructs a new
on the stack fromunexpected < E > tmp
(which can throw),unexpected ( this -> error ()) -
destroys the unexpected value by calling
,unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
. Either,* rhs -
the constructor didn’t throw, so mark the expected as holding a
(which can’t throw), orT -
the constructor did throw, so move-construct the
from the stackunexpected < E >
back into the expected storage (which can’t throw astmp
isis_nothrow_move_constructible_v < E > true
), and rethrow the exception.
-
Returns:
.
Postconditions:
.
Throws: any exception throw by the selected operations.
Remarks: If any exception is thrown, the values of
remain unchanged.
If an exception is thrown during the call to
's or
's copy
constructor, no effect. If an exception is thrown during the call to
's or
's copy assignment, the state of its contained value is as defined
by the exception safety guarantee of
's or
's copy assignment.
This operator shall be defined as deleted unless
-
isT
andvoid
andis_copy_assignable_v < E >
oris_copy_constructible_v < E > -
is notT
andvoid
andis_copy_assignable_v < T >
andis_copy_constructible_v < T >
andis_copy_assignable_v < E >
and (is_copy_constructible_v < E >
oris_nothrow_move_constructible_v < E >
).is_nothrow_move_constructible_v < T >
expected < T , E >& operator = ( expected < T , E >&& rhs ) noexcept ( see below );
Effects:
If
contains a value and
contains a value,
-
move assign
to the contained value* rhs
ifval
is notT
;void
otherwise, if
does not contain a value and
does not contain a
value,
-
move assign
to the unexpected valueunexpected ( rhs . error ())
;unexpect
otherwise, if
contains a value and
does not contain a value,
-
if
isT void -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected < E >
. Eitherunexpected ( move ( rhs ). error ()) -
the constructor didn’t throw, so mark the expected as holding a
(which can’t throw), orunexpected < E > -
the constructor did throw, and nothing was changed.
-
-
otherwise if
is_nothrow_move_constructible_v < E > -
destroys the contained value by calling
,val . T ::~ T () -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected < E >
;unexpected ( move ( rhs ). error ()))
-
-
otherwise as
is_nothrow_move_constructible_v < T > -
move constructs a new
on the stack fromT tmp
(which can’t throw as* this
is nothrow-move-constructible),T -
destroys the contained value by calling
,val . T ::~ T () -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected_type < E >
. Either,unexpected ( move ( rhs ). error ())) -
The constructor didn’t throw, so mark the expected as holding a
(which can’t throw), orunexpected_type < E > -
The constructor did throw, so move-construct the
from the stackT
back into the expected storage (which can’t throw astmp
is nothrow-move-constructible), and rethrow the exception.T
-
otherwise
does not contain a value and
contains a value,
-
if
isT
destroys the unexpected value by callingvoid unexpect . ~ unexpected < E > () -
otherwise, if
is_nothrow_move_constructible_v < T > -
destroys the unexpected value by calling
,unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
;* move ( rhs )
-
-
otherwise as
is_nothrow_move_constructible_v < E > -
move constructs a new
on the stack fromunpepected_type < E > tmp
(which can’t throw asunexpected ( this -> error ())
is nothrow-move-constructible),E -
destroys the unexpected value by calling
,unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
. Either,* move ( rhs ) -
The constructor didn’t throw, so mark the expected as holding a
(which can’t throw), orT -
The constructor did throw, so move-construct the
from the stackunexpected < E >
back into the expected storage (which can’t throw astmp
is nothrow-move-constructible), and rethrow the exception.E
-
Returns:
.
Postconditions:
.
Remarks: The expression inside noexcept is equivalent to:
.
If any exception is thrown, the values of
remain
unchanged. If an exception is thrown during the call to
's copy constructor,
no effect. If an exception is thrown during the call to
's copy assignment,
the state of its contained value is as defined by the exception safety guarantee
of
's copy assignment. If an exception is thrown during the call to
's
copy assignment, the state of its contained unexpected value is as defined by
the exception safety guarantee of
's copy assignment.
This operator shall be defined as deleted unless
and
and
and
.
template < class U > expected < T , E >& operator = ( U && v );
Effects:
If
contains a value, assigns
to the contained value
;
otherwise, if
-
destroys the unexpected value by calling
,unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
andforward < U > ( v ) -
set
tohas_val true
;
otherwise as
-
move constructs a new
on the stack fromunexpected < E > tmp
(which can’t throw asunexpected ( this -> error ())
is nothrow-move-constructible),E -
destroys the contained value by calling
,unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
. Either,forward < U > ( v ) -
the constructor didn’t throw, so mark the expected as holding a
(which can’t throw), that is setT
tohas_val true
, or -
the constructor did throw, so move construct the
from the stackunexpected < E >
back into the expected storage (which can’t throw astmp
is nothrow-move-constructible), and re-throw the exception.E
-
Returns:
.
Postconditions:
contains a value.
Remarks: If any exception is thrown, the value of
remains
unchanged. If an exception is thrown during the call to
's constructor, no
effect. If an exception is thrown during the call to
's copy assignment, the
state of its contained value is as defined by the exception safety guarantee of
's copy assignment.
This function shall not participate in overload resolution unless:
-
isis_same_v < T , void > false
and -
isis_same_v < expected < T , E > , decay_t < U >> false
and -
isconjunction_v < is_scalar < T > , is_same < T , decay_t < U >>> false
, -
isis_constructible_v < T , U > true
, -
isis_assignable_v < T & , U > true
and -
isis_nothrow_move_constructible_v < E > true
.
expected < T , E >& operator = ( unexpected < E > const & e ) noexcept ( see below );
Effects:
If
does not contain a value, assigns
to the
unexpected value
;
otherwise,
-
destroys the contained value by calling
ifval . ~ T ()
is notT
,void -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected < E >
and setunexpected ( forward < expected < T , E >> ( rhs ))
tohas_val false
.
Returns:
.
Postconditions:
does not contain a value.
Remarks: If any exception is thrown, value of valued remains unchanged.
This signature shall not participate in overload resolution unless
and
.
expected < T , E >& operator = ( unexpected < E > && e );
Effects:
If
does not contain a value, move assign
to
the unexpected value
;
otherwise,
-
destroys the contained value by calling
ifval . ~ T ()
is notT
,void -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected < E >
and setunexpected ( move ( forward < expected < T , E >> ( rhs )))
tohas_val false
.
Returns:
.
Postconditions:
does not contain a value.
Remarks: If any exception is thrown, value of valued remains unchanged.
This signature shall not participate in overload resolution unless
and
.
void expected < void , E >:: emplace ();
Effects:
If
doesn’t contains a value
-
destroys the unexpected value by calling
,unexpect . ~ unexpected < E > () -
set
tohas_val true
Postconditions:
contains a value.
Throws: nothing
template < class ... Args > void emplace ( Args && ... args );
Effects:
If
contains a value, assigns the contained value
as if
constructing an object of type
with the arguments
otherwise, if
-
destroys the unexpected value by calling
,unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
andstd :: forward < Args > ( args )... -
set
tohas_val true
;
otherwise if
-
constructs a new
on the stack fromT tmp
(which can throw),std :: forward < Args > ( args )... -
destroys the unexpected value by calling
,unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
(which can not throw) andmove ( tmp ) -
set
tohas_val true
;
otherwise as
-
move constructs a new
on the stack fromunexpected < E > tmp
(which can’t throw),unexpected ( this -> error ()) -
destroys the unexpected value by calling
,unexpect . ~ unexpected < E > () -
initializes the contained value as if direct-non-list-initializing an object of type
withT
. Either,std :: forward < Args > ( args )... -
the constructor didn’t throw, so mark the expected as holding a
(which can’t throw), that is setT
tohas_val true
, or -
the constructor did throw, so move-construct the
from the stackunexpected < E >
back into the expected storage (which can’t throw astmp
is nothrow-move-constructible), and re-throw the exception.E
-
Postconditions:
contains a value.
Throws: Any exception thrown by the selected assignment of
.
Remarks: If an exception is thrown during the call to
's assignment,
nothing changes.
This signature shall not participate in overload resolution unless
.
template < class U , class ... Args > void emplace ( initializer_list < U > il , Args && ... args );
Effects: if
contains a value, assigns the contained value
as if
constructing an object of type
with the arguments
, otherwise destroys the unexpected value by calling
and initializes the contained value as if
constructing an object of type
with the arguments
.
Postconditions:
contains a value.
Throws: Any exception thrown by the selected assignment of
.
Remarks: If an exception is thrown during the call to
's assignment nothing
changes.
The function shall not participate in overload resolution unless:
is not
and
.
1.14. �.�.4.4 Swap [expected.object.swap]
void swap ( expected < T , E >& rhs ) noexcept ( see below );
Effects: if
contains a value and
contains a value,
-
calls
,using std :: swap ; swap ( val , rhs . val )
otherwise if
does not contain a value and
does not contain a value,
-
calls
,using std :: swap ; swap ( err , rhs . err )
otherwise if
does not contains a value and
contains a value,
-
calls
,rhs . swap ( * this )
otherwise,
contains a value and
does not contains a value,
-
if
isT void -
initializes the unexpected value as if direct-non-list-initializing an object of type
withunexpected < E >
. Eitherunexpected ( move ( rhs )) -
the constructor didn’t throw, so mark the expected as holding a
, destroys the unexpected value by callingunexpected < E >
setrhs . unexpect . ~ unexpected < E > ()
torhs . has_val true
. -
the constructor did throw, rethrow the exception.
-
-
otherwise
is notT
, ifvoid
,is_nothrow_move_constructible_v < E > -
the unexpected value of
is moved to a temporary variablerhs
of typetmp
,unpected_type -
followed by destruction of the unexpected value as if by
,rhs . unexpect . unexpected < E >::~ unexpected < E > () -
the contained value of
is direct-initialized fromrhs
,std :: move ( * other ) -
followed by destruction of the contained value as if by
,rhs . val -> T ::~ T () -
the unexpected value of
is direct-initialized fromthis
, after this,std :: move ( tmp )
does not contain a value; andthis
contains a value.rhs
-
-
otherwise if
,is_nothrow_move_constructible_v < T > -
the contained value of
is moved to a temporary variablerhs
of typetmp
,T -
followed by destruction of the contained value as if by
,rhs . val . T ::~ T () -
the unexpected value of
is direct-initialized fromrhs
,unexpected ( std :: move ( other . error ())) -
followed by destruction of the unexpected value as if by
,rhs . unexpect -> unexpected < E >::~ unexpected < E > () -
the contained value of
is direct-initialized fromthis
, after this,std :: move ( tmp )
does not contain a value; andthis
contains a value.rhs
-
Throws: Any exceptions that the expressions in the Effects clause throw.
Adapt
Remarks once Effects are good.
Remarks: The expression inside noexcept is equivalent to:
. The function shall not
participate in overload resolution unless: LValues of type
shall be
, LValues of type
shall be
and
or
.
1.15. �.�.4.5 Observers [expected.object.observe]
constexpr const T * operator -> () const ; T * operator -> ();
Requires:
contains a value.
Returns:
.
Remarks: Unless
is a user-defined type with overloaded unary
,
the first operator shall be a constexpr function.
The operator shall not participate in overload resolution unless:
is not
.
constexpr const T & operator * () const & ; T & operator * () & ;
Requires:
contains a value.
Returns:
.
Remarks: The first operator shall be a constexpr function.
The operator shall not participate in overload resolution unless:
is not
.
constexpr T && operator * () && ; constexpr const T && operator * () const && ;
Requires:
contains a value.
Returns:
.
Remarks: This operator shall be a constexpr function.
The operator shall not participate in overload resolution unless:
is not
.
constexpr explicit operator bool () noexcept ;
Returns:
.
Remarks: This operator shall be a constexpr function.
constexpr bool has_value () const noexcept ;
Returns:
.
Remarks: This function shall be a constexpr function.
constexpr void expected < void , E >:: value () const ;
Throws:
if
does not contain a value.
constexpr const T & expected :: value () const & ; constexpr T & expected :: value () & ;
Returns:
, if
contains a value.
Throws:
if
does not contain a value.
Remarks: These functions shall be constexpr functions.
The operator shall not participate in overload resolution unless:
is not
.
constexpr T && expected :: value () && ; constexpr const T && expected :: value () const && ;
Returns:
, if
contains a value.
Throws:
if
does not contain a value.
Remarks: These functions shall be constexpr functions.
The operator shall not participate in overload resolution unless:
is not
.
constexpr const E & error () const & ; constexpr E & error () & ;
Requires:
does not contain a value.
Returns:
.
Remarks: The first function shall be a constexpr function.
constexpr E && error () && ; constexpr const E && error () const && ;
Requires:
does not contain a value.
Returns:
.
Remarks: The first function shall be a constexpr function.
template < class U > constexpr T value_or ( U && v ) const & ;
Effects: Equivalent to
.
Remarks: If
and
is
false the program is ill-formed.
template < class U > T value_or ( U && v ) && ;
Effects: Equivalent to
.
Remarks: If
and
is
false the program is ill-formed.
1.16. �.�.6 unexpect
tag [expected.unexpect]
struct unexpect_t { explicit unexpect_t () = default ; }; inline constexpr unexpect_t unexpect {};
1.17. �.�.7 Template Class bad_expected_access
[expected.bad_expected_access]
template < class E > class bad_expected_access : public bad_expected_access < void > { public : explicit bad_expected_access ( E ); virtual const char * what () const noexcept override ; E & error () & ; const E & error () const & ; E && error () && ; const E && error () const && ; private : E val ; // exposition only };
Wondering if we just need an
overload as we do for
.
The template class
defines the type of objects thrown as
exceptions to report the situation where an attempt is made to access the value
of a unexpected expected object.
bad_expected_access :: bad_expected_access ( E e );
Effects: Constructs an object of class
storing the
parameter.
Postconditions:
returns an implementation-defined NTBS.
const E & error () const & ; E & error () & ;
Effects: Equivalent to:
E && error () && ; const E && error () const && ;
Effects: Equivalent to:
virtual const char * what () const noexcept override ;
Returns: An implementation-defined NTBS.
1.18. �.�.7 Template Class bad_expected_access < void >
[expected.bad_expected_access_base]
template <> class bad_expected_access < void > : public exception { public : explicit bad_expected_access (); };
The template class
defines the type of objects
thrown as exceptions to report the situation where an attempt is made to access
the value of a unexpected expected object.
1.19. �.�.8 Expected Relational operators [expected.relational_op]
template < class T , class E > constexpr bool operator == ( const expected < T , E >& x , const expected < T , E >& y );
Requires:
(if not
) and
shall meet the requirements of EqualityComparable.
Returns: If
, false
; otherwise if
,
; otherwise true
if
is
or
otherwise.
Remarks: Specializations of this function template, for which
is
or
and
are core
constant expression, shall be constexpr functions.
template < class T , class E > constexpr bool operator != ( const expected < T , E >& x , const expected < T , E >& y );
Requires:
(if not
) and
shall meet the requirements
of EqualityComparable.
Returns: If
, true
; otherwise if
,
; otherwise true
if
is
or
.
Remarks: Specializations of this function template, for which
is
or
and
are core
constant expression, shall be constexpr functions.
1.20. �.�.9 Comparison with T
[expected.comparison_T]
template < class T , class E > constexpr bool operator == ( const expected < T , E >& x , const T & v ); template < class T , class E > constexpr bool operator == ( const T & v , const expected < T , E >& x );
Requires:
is not
and the expression
shall be well-formed
and its result shall be convertible to
. [ Note:
need not be EqualityComparable. - end note]
Effects: Equivalent to:
.
template < class T , class E > constexpr bool operator != ( const expected < T , E >& x , const T & v ); template < class T , class E > constexpr bool operator != ( const T & v , const expected < T , E >& x );
Requires:
is not
and the expression
shall be well-formed
and its result shall be convertible to
. [ Note:
need not be EqualityComparable. - end note]
Effects: Equivalent to:
.
1.21. �.�.10 Comparison with unexpected < E >
[expected.comparison_unexpected_E]
template < class T , class E > constexpr bool operator == ( const expected < T , E >& x , const unexpected < E >& e ); template < class T , class E > constexpr bool operator == ( const unexpected < E >& e , const expected < T , E >& x );
Requires: The expression
shall be well-formed and
its result shall be convertible to
. [ Note:
need not be EqualityComparable. - end note]
Effects: Equivalent to:
.
template < class T , class E > constexpr bool operator != ( const expected < T , E >& x , const unexpected < E >& e ); template < class T , class E > constexpr bool operator != ( const unexpected < E >& e , const expected < T , E >& x );
Requires: The expression
shall be well-formed and
its result shall be convertible to
. [ Note:
need not be EqualityComparable. - end note]
Effects: Equivalent to:
.
1.22. �.�.11 Specialized algorithms [expected.specalg]
template < class T , class E > void swap ( expected < T , E >& x , expected < T , E >& y ) noexcept ( noexcept ( x . swap ( y )));
Effects: Calls
.
Remarks: This function shall not participate in overload resolution unless
is
or
is true
,
is true
and
is true
and
is true
2. Open Questions
is a vocabulary type with an opinionated design and a proven
record under varied forms in a multitude of codebases. Its current form has
undergone multiple revisions and received substantial feedback, falling roughly
in the following categories:
-
Ergonomics: is this the right way to expose such functionality?
-
Disappointment: should we expose this in the Standard, given C++'s existing error handling mechanisms?
-
STL usage: should the Standard Template Library adopt this class, at which pace, and where?
LEWG and EWG have nonetheless reached consensus that a class of this general approach is probably desirable, and the only way to truly answer these questions is to try it out in a TS and ask for explicit feedback from developers. The authors hope that developers will provide new information which they’ll be able to communicate to the Committee.
Here are open questions, and questions which the Committee thinks are settled and which new information can justify revisiting.
2.1. Ergonomics
-
Name:
-
Is
the right name?expected -
Does it express intent both as a consumer and a producer?
-
-
Is
a salient property ofE
?expected -
Is
clear on what it expresses as a return type?expected < void , E > -
Would it make sense for
to support containing bothexpected
andT
(in some designs, either one of them being optional), or is this usecase better handled by a separate proposal?E -
Is the order of parameters
appropriate?< T , E > -
Is usage of
"viral" in a codebase, or can it be adopted incrementally?expected -
Comparisons:
-
Are
and==
useful?!= -
Should other comparisons be provided?
-
What usages of
mandate putting instances in aexpected
, or other such container?map -
Should
be provided?hash -
What usages of
mandate putting instances in anexpected
, or other such container?unordered_map -
Should
always be comparable ifexpected < T , E >
is comparable, even ifT
is not comparable?E
-
-
Error type
:E -
has no default. Should it?E -
Should
be specialized for particularexpected
types such asE
, and how?exception_ptr -
Should
handleexpected
types with a built-in "success" value any differently, and how?E -
is not implicitly constructible from anexpected
, even when unambiguous fromE
, because as a vocabulary type it wants unexpected error construction to be verbose, and require hopping through anT
. Is the verbosity extraneous?unexpected
-
-
Does usage of this class cause a meaningful performance impact compared to using error codes?
-
The accessor design offers a terse unchecked dereference operator (expected to be used alongside the implicit
conversion), as well asbool
andvalue ()
accessors which are checked. Is that a gotcha, or is it similar enough to classes such aserror ()
to be unsurprising?optional -
Is
the right thing to throw?bad_expected_access -
Should some members be
?[[ nodiscard ]]
2.2. Disappointment
C++ already supports exceptions and error codes,
would be a third
kind of error handling.
-
where does
work better than either exceptions or error handling?expected -
was designed to be particularly well suited to APIs which require their immediate caller to consider an error scenario. Do it succeed in that purpose?expected -
Do codebases successfully compose these three types of error handling?
-
Is debuggability any harder?
-
Is it easy to teach C++ as a whole with a third type of error handling?
2.3. STL Usage
-
Should
be used in the STL at the same time as it gets standardized?expected -
Where, considering
may be a good place to change APIs?std2