AZ::Outcome< ValueT, ErrorT > Class Template Reference

#include <Outcome.h>

Inherits AZStd::expected< ValueT, AZStd::conditional_t<!AZStd::is_void_v< AZStd::unexpect_t >, AZStd::unexpect_t, AZStd::unexpect_t > >.

Public Types
using	ValueType = typename BaseType::value_type
using	ErrorType = typename BaseType::error_type

Public Member Functions
AZ_FORCE_INLINE	Outcome ()
AZ_FORCE_INLINE	Outcome (const SuccessType &success)
	Constructs successful outcome, where value is copy-constructed.
AZ_FORCE_INLINE	Outcome (SuccessType &&success)
	Constructs successful outcome, where value is move-constructed.
AZ_FORCE_INLINE	Outcome (const FailureType &failure)
	Constructs failed outcome, where error is copy-constructed.
AZ_FORCE_INLINE	Outcome (FailureType &&failure)
	Constructs failed outcome, where error is move-constructed.
AZ_FORCE_INLINE	Outcome (const Outcome &other)
	Copy constructor.
AZ_FORCE_INLINE	Outcome (Outcome &&other)
	Move constructor.
AZ_FORCE_INLINE Outcome &	operator= (const Outcome &other)
	Copy-assignment from other outcome.
AZ_FORCE_INLINE Outcome &	operator= (const SuccessType &success)
	Copy value into outcome. Outcome is now successful.
AZ_FORCE_INLINE Outcome &	operator= (const FailureType &failure)
	Copy error into outcome. Outcome is now failed.
AZ_FORCE_INLINE Outcome &	operator= (Outcome &&other)
	Move-assignment from other outcome.
AZ_FORCE_INLINE Outcome &	operator= (SuccessType &&success)
	Move value into outcome. Outcome is now successful.
AZ_FORCE_INLINE Outcome &	operator= (FailureType &&failure)
	Move error into outcome. Outcome is now failed.
AZ_FORCE_INLINE bool	IsSuccess () const
	Returns whether outcome was a success, containing a valid value.
AZ_FORCE_INLINE	operator bool () const
template<class Value_Type = ValueType, class = AZStd::enable_if_t<!AZStd::is_void_v<Value_Type>>>
AZ_FORCE_INLINE Value_Type &	GetValue ()
template<class Value_Type = ValueType, class = AZStd::enable_if_t<!AZStd::is_void_v<Value_Type>>>
AZ_FORCE_INLINE const Value_Type &	GetValue () const
template<class Value_Type = ValueType, class = AZStd::enable_if_t<!AZStd::is_void_v<Value_Type>>>
AZ_FORCE_INLINE Value_Type &&	TakeValue ()
template<class U , class Value_Type = ValueType, class = AZStd::enable_if_t<!AZStd::is_void_v<Value_Type>>>
AZ_FORCE_INLINE Value_Type	GetValueOr (U &&defaultValue) const
template<class Error_Type = ErrorType, class = AZStd::enable_if_t<!AZStd::is_void_v<Error_Type>>>
AZ_FORCE_INLINE Error_Type &	GetError ()
template<class Error_Type = ErrorType, class = AZStd::enable_if_t<!AZStd::is_void_v<Error_Type>>>
AZ_FORCE_INLINE const Error_Type &	GetError () const
template<class Error_Type = ErrorType, class = AZStd::enable_if_t<!AZStd::is_void_v<Error_Type>>>
AZ_FORCE_INLINE Error_Type &&	TakeError ()

Detailed Description

template<class ValueT, class ErrorT = AZStd::unexpect_t>
class AZ::Outcome< ValueT, ErrorT >

Outcome is intended for use as the return type of a function that may fail. A successful outcome contains the desired value, while a failed outcome contains an error. Either the value exists or the error exists, the other type is never even constructed.

Check the outcome's IsSuccess() before accessing its contents via GetValue() or GetError().

Outcome performs no dynamic allocations and holds the value or error type within its own memory footprint.

Parameters

ValueT	The value type contained in a successful outcome. void is an acceptable value type.
ErrorT	The error type contained in a failed outcome. void is an acceptable error type.

An outcome is constructed with the aid of helper functions Success<ValueT>(ValueT&& value) and Failure<ErrorT>(ErrorT&& error):

AZ::Outcome<int, const char*> successfulOutcome = AZ::Success(9);
AZ::Outcome<int, const char*> failedOutcome     = AZ::Failure("can't do that");

Example Usage:

// Returning AZ::Outcome from a function...
// If successful, outcome contains valid FILE*.
// If failed, outcome contains an int corresponding to the system-specific error.
AZ::Outcome<FILE*, int> FileOpen(const char* filepath, const char* mode)
{
    FILE* file = fopen(filepath, mode);
    if (file)
    {
        // Returning successful outcome
        return AZ::Success(file);
    }
    else
    {
        // Returning failed outcome
        return AZ::Failure(errno);
    }
}
 
// Receiving AZ::Outcome from a function...
void ContrivedExample()
{
    AZ::Outcome<FILE*, int> fileOutcome = FileOpen("contrived.txt", "r");
    if (fileOutcome.IsSuccess())
    {
        // when IsSuccess() == true, outcome contains value
        DoSomethingWithFile(fileOutcome.GetValue());
    }
    else
    {
        // when IsSuccess() == false, outcome contains error
        Log("FileOpen failed (error %d): %s", fileOutcome.GetError(), filepath);
    }
}

Constructor & Destructor Documentation

Outcome()

template<class ValueT , class ErrorT >

AZ_FORCE_INLINE AZ::Outcome< ValueT, ErrorT >::Outcome

Default construction is only allowed to support generic interactions with Outcome objects of all template arguments; user Outcome must be either in success state or failure state

Member Function Documentation

GetError()

template<class ValueT , class ErrorT >

template<class Error_Type , class >

AZ_FORCE_INLINE Error_Type & AZ::Outcome< ValueT, ErrorT >::GetError

Returns error for failed outcome. Behavior is undefined if outcome was a success.

GetValue()

template<class ValueT , class ErrorT >

template<class Value_Type , class >

AZ_FORCE_INLINE Value_Type & AZ::Outcome< ValueT, ErrorT >::GetValue

Returns value from successful outcome. Behavior is undefined if outcome was a failure.

GetValueOr()

template<class ValueT , class ErrorT >

template<class U , class Value_Type , class >

AZ_FORCE_INLINE Value_Type AZ::Outcome< ValueT, ErrorT >::GetValueOr

(

U &&

defaultValue

)

const

Returns value from successful outcome. defaultValue is returned if outcome was a failure.

TakeError()

template<class ValueT , class ErrorT >

template<class Error_Type , class >

AZ_FORCE_INLINE Error_Type && AZ::Outcome< ValueT, ErrorT >::TakeError

Returns error for failed outcome as rvalue reference. Note that outcome's error may have its contents stolen, rendering it invalid for further access. Behavior is undefined if outcome was a success.

TakeValue()

template<class ValueT , class ErrorT >

template<class Value_Type , class >

AZ_FORCE_INLINE Value_Type && AZ::Outcome< ValueT, ErrorT >::TakeValue

Returns value from successful outcome as rvalue reference. Note that outcome's value may have its contents stolen, rendering it invalid for further access. Behavior is undefined if outcome was a failure.

---

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

• Code/Framework/AzCore/AzCore/Outcome/Outcome.h
• Code/Framework/AzCore/AzCore/Outcome/Internal/OutcomeImpl.h