Expected< T > Class Template Reference

Overview

template<typename T>
class etcpal::Expected< T >

A type representing either a value or an etcpal_error_t code.

This class is modeled after the std::expected proposal. It is a useful companion to C++17's std::optional, when one desires a concise representation of either a value or an error code representing why that value is not present.

The proposed std::expected is generic with respect to both the value and the error type, but EtcPal's version always uses etcpal_error_t as the error. This makes it useful in the context of EtcPal itself and libraries that depend on EtcPal; if you are looking for a generically-useful expected implementation, martinmoene's version is recommended. This implementation is based heavily on that one.

Usage

Expected is almost always used as the return type of an API function. Consider a function that either creates a network socket or returns an error.

etcpal::Expected<etcpal_socket_t> CreateSocket(int family, int type);

When using this function, check whether the result contains an error:

auto socket_res = CreateSocket(AF_INET, SOCK_STREAM);
if (socket_res) // or socket_res.has_value()
{
  etcpal_socket_t socket = *socket_res; // or socket_res.value()
  // Now use the socket...
}
else
{
  printf("CreateSocket failed with result code %d, description '%s'\n", socket_res.error(),
         socket_res.result().ToCString());
}

value() throws BadExpectedAccess if the instance does not have a valid value. So you can also use an exception-handling approach:

try
{
  etcpal_socket_t socket = CreateSocket(AF_INET, SOCK_STREAM).value();
}
catch (const etcpal::BadExpectedAccess& e)
{
  printf("CreateSocket failed with result code %d, description '%s'\n", e.result().code(),
         e.result().ToCString());
}

Note that this only works for the value() function, not any of the other accessors (they assert on the correct state instead).

Inside functions that return Expected, you can use implicit conversions from the value type or etcpal_error_t to return success or failure:

// Possible implementation of CreateSocket()...
etcpal::Expected<etcpal_socket_t> CreateSocket(int family, int type)
{
   etcpal_socket_t socket;
   etcpal_error_t res = etcpal_socket(family, type, &socket);
   if (res == kEtcPalErrOk)
     return socket; // Implicitly converted to Expected, has_value() is true
   else
     return res; // Implicitly converted to Expected, has_value() is false
}

The value_or() function can be useful when you want to use a default value in case of an error condition:

etcpal::Expected<std::string> ConvertIntToString(int val);
// ...
std::string conversion = ConvertIntToString(arg).value_or("0");
// Conversion contains the successful conversion result, or "0" if the conversion failed.

Public Types
using	ValueType = T
	The value type.

Public Member Functions
template<bool B = std::is_default_constructible<T>::value, typename std::enable_if< B, int >::type = 0>
ETCPAL_CONSTEXPR_14	Expected ()
	Default constructor - enabled if T is default-constructible. More...
ETCPAL_CONSTEXPR_14	Expected (const Expected &other)=default
	Copy constructor - enabled if T is copy-constructible. More...
ETCPAL_CONSTEXPR_14	Expected (Expected &&other)=default
	Move constructor - enabled if T is move-constructible. More...
template<typename U >
ETCPAL_CONSTEXPR_14	Expected (const Expected< U > &other, ETCPAL_ENABLE_IF_ARG(std::is_constructible< T, const U & >::value &&!std::is_constructible< T, Expected< U > & >::value &&!std::is_constructible< T, Expected< U > && >::value &&!std::is_constructible< T, Expected< U > const & >::value &&!std::is_constructible< T, Expected< U > const && >::value &&!std::is_convertible< Expected< U > &, T >::value &&!std::is_convertible< Expected< U > &&, T >::value &&!std::is_convertible< Expected< U > const &, T >::value &&!std::is_convertible< Expected< U > const &&, T >::value &&!std::is_convertible< const U &, T >::value))
	Explicit conversion copy constructor - enabled for U that can be explicitly converted to T. More...
template<typename U >
ETCPAL_CONSTEXPR_14	Expected (const Expected< U > &other, ETCPAL_ENABLE_IF_ARG(std::is_constructible< T, const U & >::value &&!std::is_constructible< T, Expected< U > & >::value &&!std::is_constructible< T, Expected< U > && >::value &&!std::is_constructible< T, Expected< U > const & >::value &&!std::is_constructible< T, Expected< U > const && >::value &&!std::is_convertible< Expected< U > &, T >::value &&!std::is_convertible< Expected< U > &&, T >::value &&!std::is_convertible< Expected< U > const &, T >::value &&!std::is_convertible< Expected< U > const &&, T >::value &&std::is_convertible< const U &, T >::value))
	Implicit conversion copy constructor - enabled for U that can be implicitly converted to T. More...
template<typename U >
ETCPAL_CONSTEXPR_14	Expected (Expected< U > &&other, ETCPAL_ENABLE_IF_ARG(std::is_constructible< T, U >::value &&!std::is_constructible< T, Expected< U > & >::value &&!std::is_constructible< T, Expected< U > && >::value &&!std::is_constructible< T, Expected< U > const & >::value &&!std::is_constructible< T, Expected< U > const && >::value &&!std::is_convertible< Expected< U > &, T >::value &&!std::is_convertible< Expected< U > &&, T >::value &&!std::is_convertible< Expected< U > const &, T >::value &&!std::is_convertible< Expected< U > const &&, T >::value &&!std::is_convertible< U, T >::value))
	Explicit conversion move constructor - enabled for U that can be explicitly converted to T. More...
template<typename U >
ETCPAL_CONSTEXPR_14	Expected (Expected< U > &&other, ETCPAL_ENABLE_IF_ARG(std::is_constructible< T, U >::value &&!std::is_constructible< T, Expected< U > & >::value &&!std::is_constructible< T, Expected< U > && >::value &&!std::is_constructible< T, Expected< U > const & >::value &&!std::is_constructible< T, Expected< U > const && >::value &&!std::is_convertible< Expected< U > &, T >::value &&!std::is_convertible< Expected< U > &&, T >::value &&!std::is_convertible< Expected< U > const &, T >::value &&!std::is_convertible< Expected< U > const &&, T >::value &&std::is_convertible< U, T >::value))
	Implicit conversion move constructor - enabled for U that can be implicitly converted to T. More...
template<typename U = T>
ETCPAL_CONSTEXPR_14	Expected (U &&value, ETCPAL_ENABLE_IF_ARG(std::is_constructible< T, U && >::value &&!std::is_convertible< U &&, T >::value)) noexcept(std::is_nothrow_move_constructible< U >::value)
	Construct from value, explicit. More...
template<typename U = T>
ETCPAL_CONSTEXPR_14	Expected (U &&value, ETCPAL_ENABLE_IF_ARG(std::is_constructible< T, U && >::value &&std::is_convertible< U &&, T >::value)) noexcept(std::is_nothrow_move_constructible< U >::value)
	Construct from value, implicit. More...
ETCPAL_CONSTEXPR_14	Expected (etcpal_error_t error)
	Construct an Expected instance containing an error code.
	~Expected ()
	Calls the contained value's destructor if and only if has_value() is true.
constexpr const T *	operator-> () const
	Access members of a composite contained value. More...
T *	operator-> ()
	Access members of a composite contained value. More...
constexpr const T &	operator* () const &
	Get the underlying value. More...
T &	operator* () &
	Get the underlying value. More...
constexpr const T &&	operator* () const &&
	Get the underlying value. More...
ETCPAL_CONSTEXPR_14 T &&	operator* () &&
	Get the underlying value. More...
constexpr	operator bool () const noexcept
	Evaluate the Expected instance inline - evaluates to has_value().
constexpr bool	has_value () const noexcept
	Whether this Expected instance contains a valid value. If not, contains an error code.
ETCPAL_CONSTEXPR_14 const T &	value () const &
	Get the underlying value. More...
T &	value () &
	Get the underlying value. More...
ETCPAL_CONSTEXPR_14 const T &&	value () const &&
	Get the underlying value. More...
ETCPAL_CONSTEXPR_14 T &&	value () &&
	Get the underlying value. More...
constexpr etcpal_error_t	error_code () const noexcept
	Get the error code. More...
constexpr Error	error () const noexcept
	Get the error code as a Error object. More...
template<typename U , ETCPAL_ENABLE_IF_TEMPLATE(std::is_copy_constructible< T >::value &&std::is_convertible< U &&, T >::value) >
constexpr T	value_or (U &&def_val) const &
	Get the value, or a default value if this Expected contains an error. More...
template<typename U , ETCPAL_ENABLE_IF_TEMPLATE(std::is_move_constructible< T >::value &&std::is_convertible< U &&, T >::value) >
T	value_or (U &&def_val) &&
	Get the value, or a default value if this Expected contains an error. More...

Constructor & Destructor Documentation

Expected() [1/9]

ETCPAL_CONSTEXPR_14 Expected ( )

inline

Default constructor - enabled if T is default-constructible.

Default-constructs an instance of T. This Expected instance has a value after this constructor is called.

Expected() [2/9]

ETCPAL_CONSTEXPR_14 Expected ( const Expected< T > &  other )

default

Copy constructor - enabled if T is copy-constructible.

If other has a value, copies its value into this Expected. If other does not have a value, copies its error code into this Expected.

Expected() [3/9]

ETCPAL_CONSTEXPR_14 Expected ( Expected< T > &&  other )

default

Move constructor - enabled if T is move-constructible.

If other has a value, moves its value into this Expected. If other does not have a value, copies its error code into this Expected.

Expected() [4/9]

ETCPAL_CONSTEXPR_14 Expected ( const Expected< U > &  other, ETCPAL_ENABLE_IF_ARG( std::is_constructible< T, const U & >::value && !std::is_constructible< T, Expected< U > & >::value && !std::is_constructible< T, Expected< U > && >::value && !std::is_constructible< T, Expected< U > const & >::value && !std::is_constructible< T, Expected< U > const && >::value && !std::is_convertible< Expected< U > &, T >::value && !std::is_convertible< Expected< U > &&, T >::value && !std::is_convertible< Expected< U > const &, T >::value && !std::is_convertible< Expected< U > const &&, T >::value && !std::is_convertible< const U &, T >::value)    )

inlineexplicit

Explicit conversion copy constructor - enabled for U that can be explicitly converted to T.

If other has a value, copies its value into this Expected. If other does not have a value, copies its error code into this Expected.

Expected() [5/9]

ETCPAL_CONSTEXPR_14 Expected ( const Expected< U > &  other, ETCPAL_ENABLE_IF_ARG( std::is_constructible< T, const U & >::value && !std::is_constructible< T, Expected< U > & >::value && !std::is_constructible< T, Expected< U > && >::value && !std::is_constructible< T, Expected< U > const & >::value && !std::is_constructible< T, Expected< U > const && >::value && !std::is_convertible< Expected< U > &, T >::value && !std::is_convertible< Expected< U > &&, T >::value && !std::is_convertible< Expected< U > const &, T >::value && !std::is_convertible< Expected< U > const &&, T >::value && std::is_convertible< const U &, T >::value)    )

inline

Implicit conversion copy constructor - enabled for U that can be implicitly converted to T.

If other has a value, copies its value into this Expected. If other does not have a value, copies its error code into this Expected.

Expected() [6/9]

ETCPAL_CONSTEXPR_14 Expected ( Expected< U > &&  other, ETCPAL_ENABLE_IF_ARG( std::is_constructible< T, U >::value && !std::is_constructible< T, Expected< U > & >::value && !std::is_constructible< T, Expected< U > && >::value && !std::is_constructible< T, Expected< U > const & >::value && !std::is_constructible< T, Expected< U > const && >::value && !std::is_convertible< Expected< U > &, T >::value && !std::is_convertible< Expected< U > &&, T >::value && !std::is_convertible< Expected< U > const &, T >::value && !std::is_convertible< Expected< U > const &&, T >::value && !std::is_convertible< U, T >::value)    )

inlineexplicit

Explicit conversion move constructor - enabled for U that can be explicitly converted to T.

If other has a value, moves its value into this Expected. If other does not have a value, copies its error code into this Expected.

Expected() [7/9]

ETCPAL_CONSTEXPR_14 Expected ( Expected< U > &&  other, ETCPAL_ENABLE_IF_ARG( std::is_constructible< T, U >::value && !std::is_constructible< T, Expected< U > & >::value && !std::is_constructible< T, Expected< U > && >::value && !std::is_constructible< T, Expected< U > const & >::value && !std::is_constructible< T, Expected< U > const && >::value && !std::is_convertible< Expected< U > &, T >::value && !std::is_convertible< Expected< U > &&, T >::value && !std::is_convertible< Expected< U > const &, T >::value && !std::is_convertible< Expected< U > const &&, T >::value && std::is_convertible< U, T >::value)    )

inline

Implicit conversion move constructor - enabled for U that can be implicitly converted to T.

If other has a value, moves its value into this Expected. If other does not have a value, copies its error code into this Expected.

Expected() [8/9]

ETCPAL_CONSTEXPR_14 Expected ( U &&  value, ETCPAL_ENABLE_IF_ARG(std::is_constructible< T, U && >::value && !std::is_convertible< U &&, T >::value)    )

inlineexplicitnoexcept

Construct from value, explicit.

Constructs an Expected from some value U which is explicitly (but not implicitly) convertible to T. The constructor is made explicit as a result. This Expected instance has a value after this constructor is called.

Parameters

value

Value to construct from.

Expected() [9/9]

ETCPAL_CONSTEXPR_14 Expected ( U &&  value, ETCPAL_ENABLE_IF_ARG(std::is_constructible< T, U && >::value && std::is_convertible< U &&, T >::value)    )

inlinenoexcept

Construct from value, implicit.

Constructs an Expected from some value U implicitly convertible to T. The constructor is not made explicit as a result. This Expected instance has a value after this constructor is called.

Parameters

value

Value to construct from.

Member Function Documentation

error()

constexpr Error error

constexprnoexcept

Get the error code as a Error object.

If has_value() is true, the behavior is undefined.

error_code()

constexpr etcpal_error_t error_code

constexprnoexcept

Get the error code.

If has_value() is true, the behavior is undefined.

operator*() [1/4]

T & operator*

(

)

&

Get the underlying value.

If has_value() is false, the behavior is undefined.

operator*() [2/4]

ETCPAL_CONSTEXPR_14 T && operator*

(

)

&&

Get the underlying value.

If has_value() is false, the behavior is undefined.

operator*() [3/4]

constexpr const T & operator* ( ) const &

constexpr

Get the underlying value.

If has_value() is false, the behavior is undefined.

operator*() [4/4]

constexpr const T && operator* ( ) const &&

constexpr

Get the underlying value.

If has_value() is false, the behavior is undefined.

operator->() [1/2]

T * operator->

Access members of a composite contained value.

If has_value() is false, the behavior is undefined.

operator->() [2/2]

constexpr const T * operator->

constexpr

Access members of a composite contained value.

If has_value() is false, the behavior is undefined.

value() [1/4]

T & value

(

)

&

Get the underlying value.

Exceptions

BadExpectedAccess

if has_value() is false.

value() [2/4]

ETCPAL_CONSTEXPR_14 T && value

(

)

&&

Get the underlying value.

Exceptions

BadExpectedAccess

if has_value() is false.

value() [3/4]

ETCPAL_CONSTEXPR_14 const T & value

(

)

const &

Get the underlying value.

Exceptions

BadExpectedAccess

if has_value() is false.

value() [4/4]

ETCPAL_CONSTEXPR_14 const T && value

(

)

const &&

Get the underlying value.

Exceptions

BadExpectedAccess

if has_value() is false.

value_or() [1/2]

T value_or ( U &&  def_val ) &&

inline

Get the value, or a default value if this Expected contains an error.

Parameters

def_val

The default value to return on error - must be convertible to T.

value_or() [2/2]

constexpr T value_or ( U &&  def_val ) const &

inlineconstexpr

Get the value, or a default value if this Expected contains an error.

Parameters

def_val

The default value to return on error - must be convertible to T.

---

The documentation for this class was generated from the following file:

• include/etcpal/cpp/error.h