Result is the standard return type of API functions. More...

#include <Result.hpp>

Inheritance diagram for ACAPI::Result< T, E >:

Public Member Functions
	Result (types::Ok< T > ok)
	Construct a new Result instance that contains OK.

	Result (types::Err< E > err, const API_Token &token)
	Construct a new Result instance that contains the specified error.

	Result (Result &&other)
	Move constructor of Result.

	Result (const Result &other)
	Copy constructor of Result.

template<typename U , typename P = T, typename = std::enable_if_t<std::is_void_v<P>>>
	Result (Result< U, E > &&other)
	Move constructor specialization.

template<typename U , typename P = T, typename = std::enable_if_t<std::is_void_v<P>>>
	Result (const Result< U, E > &other)
	Copy constructor specialization.

bool	IsOk () const

bool	IsErr () const

T	Expect (std::string_view message) const
	This function will yield the value of an Ok(T).

template<typename Func , typename Ret = Result< typename details::ResultOkType< std::invoke_result_t<Func, T> >::type, E>>
Ret	Map (Func func) const
	This function will apply a function to a contained value and will return the result of the transformation. In case the Result contains an Error, Map does nothing. Note that the passed function should return a simple value and not a Result. If you want to transform the error result of a function, use MapError.

template<typename Func , typename Ret = Result<T, typename details::ResultErrType< std::invoke_result_t<Func, E> >::type >>
Ret	MapError (Func func) const
	This function will apply a function to a contained error value and will return the result of the transformation.

template<typename Func >
Result< T, E >	Then (Func func) const
	This function executes the passed function if the Result contains an Ok value. In case the Result contains an Error value, Then does nothing.

template<typename Func >
Result< T, E >	Otherwise (Func func) const
	This function will execute a function if the Result contains an Error value.

template<typename Func , typename Ret = Result<T, typename details::ResultErrType< std::invoke_result_t<Func, E> >::type >>
Ret	OrElse (Func func) const
	This function will return the result of a transformation executed on the Error value of the Result, only if the Result contains an Error value.

const API_Token &	Token () const
	A simple getter for the Token of the AddOn which called the function that returned the Result. Mainly for internal use.

template<typename U = T>
const std::enable_if_t<!std::is_same_v< U, void >, U > &	UnwrapOr (const U &defaultValue) const &
	Unwraps the value contained in the Result. In case the Result contains an Error value, it returns a default value passed in as a parameter.

template<typename U = T>
std::enable_if_t<!std::is_same_v< U, void >, U > &&	Unwrap () &&
	Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

template<typename U = T>
const std::enable_if_t<!std::is_same_v< U, void >, U > &	Unwrap () const &
	Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

template<typename U = T>
std::enable_if_t<!std::is_same_v< U, void >, U > &	Unwrap () &
	Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

E	UnwrapErr () const
	Unwraps the error value contained in the Result. Trying to UnwrapErr the value while it contains an Ok value will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

template<typename U = T>
std::enable_if_t<!std::is_same_v< U, void >, U > &	operator* () &
	Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

template<typename U = T>
std::enable_if_t<!std::is_same_v< U, void >, U > &&	operator* () &&
	Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

template<typename U = T>
const std::enable_if_t<!std::is_same_v< U, void >, U > &	operator* () const &
	Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

template<typename U = T>
std::enable_if<!std::is_same< U, void >::value, U >::type *	operator-> ()
	Unwraps the value contained in the Result and return with a pointer to it. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

template<typename U = T>
const std::enable_if<!std::is_same< U, void >::value, U >::type *	operator-> () const
	Unwraps the value contained in the Result and return with a pointer to it. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

const storage_type &	Storage () const
	For internal use only.

storage_type &	Storage ()
	For internal use only.

Detailed Description

template<typename T, typename E = Error>
class ACAPI::Result< T, E >

Result is the standard return type of API functions.

Result is a value wrapper that can contain an error message and error code if the function failed, or a return value if the function succeeded. It supports advanced functional operations such as Map or Otherwise or can be used as a simple Optional by dereferencing the contained value. Trying to dereference the value while it contains an error will result in crash and should be avoided.

Constructor & Destructor Documentation

◆ Result() [1/6]

template<typename T , typename E = Error>

ACAPI::Result< T, E >::Result ( types::Ok< T > ok )

inline

Construct a new Result instance that contains OK.

Parameters

ok	The value which Result will contain.

◆ Result() [2/6]

template<typename T , typename E = Error>

ACAPI::Result< T, E >::Result	(	types::Err< E >	err,
		const API_Token &	token
	)

inline

Construct a new Result instance that contains the specified error.

Parameters

err	The specified error.
token	Token of the add-on.

◆ Result() [3/6]

template<typename T , typename E = Error>

ACAPI::Result< T, E >::Result ( Result< T, E > && other )

inline

Move constructor of Result.

Parameters

other Other Result instance.

◆ Result() [4/6]

template<typename T , typename E = Error>

ACAPI::Result< T, E >::Result ( const Result< T, E > & other )

inline

Copy constructor of Result.

Parameters

other Other Result instance.

◆ Result() [5/6]

template<typename T , typename E = Error>

template<typename U , typename P = T, typename = std::enable_if_t<std::is_void_v<P>>>

ACAPI::Result< T, E >::Result ( Result< U, E > && other )

inlineexplicit

Move constructor specialization.

Parameters

other Other Result instance.

◆ Result() [6/6]

template<typename T , typename E = Error>

template<typename U , typename P = T, typename = std::enable_if_t<std::is_void_v<P>>>

ACAPI::Result< T, E >::Result ( const Result< U, E > & other )

inlineexplicit

Copy constructor specialization.

Parameters

other Other Result instance.

Member Function Documentation

◆ Expect()

template<typename T , typename E = Error>

T ACAPI::Result< T, E >::Expect ( std::string_view message ) const

inline

This function will yield the value of an Ok(T).

This function will yield the value of an Ok(T) or terminate the program with an error message passed as a parameter. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Template Parameters

std::string_view Standard string_view

Parameters

message the error message handed over to the error handler.

Returns: the value of the Ok(T)
ACAPI::Result<uint32_t> r1 = Ok(3u);

uint32_t val = r1.Expect("Failed to retrieve the value"sv);

EXPECT_EQ (val, 3);

ACAPI::Result
Result is the standard return type of API functions.
Definition: Result.hpp:845

ACAPI::Result::Expect
T Expect(std::string_view message) const
This function will yield the value of an Ok(T).
Definition: Result.hpp:959

ACAPI::Result<uint32_t> result {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_THROW (result.Expect (""), GS::LogicErrorException);

APINULLGuid
constexpr API_Guid APINULLGuid
Represents an empty API guid.
Definition: API_Guid.hpp:241

ACAPI::Error
Error type for ACAPI::Result containing an error message and an error code.
Definition: Result.hpp:47

◆ IsErr()

template<typename T , typename E = Error>

bool ACAPI::Result< T, E >::IsErr ( ) const

inline

Returns: False if the result contains a value. True if it contains an error.

◆ IsOk()

template<typename T , typename E = Error>

bool ACAPI::Result< T, E >::IsOk ( ) const

inline

Returns: True if the result contains a value. False if it contains an error.

◆ Map()

template<typename T , typename E = Error>

template<typename Func , typename Ret = Result< typename details::ResultOkType< std::invoke_result_t<Func, T> >::type, E>>

Ret ACAPI::Result< T, E >::Map ( Func func ) const

inline

This function will apply a function to a contained value and will return the result of the transformation. In case the Result contains an Error, Map does nothing. Note that the passed function should return a simple value and not a Result. If you want to transform the error result of a function, use MapError.

Template Parameters

Func	the type of the function to be applied to the value contained in the Result.

Parameters

func	the function to be applied to the value contained in the Result.

Returns: the result of the transformation applied to the value by the passed function.
ACAPI::Result<TestStruct> original = Ok(2);

ACAPI::Result<std::string> mapped = original.Map (Stringify);

EXPECT_EQ (mapped.Unwrap (), "2");

ACAPI::Result::Unwrap
std::enable_if_t<!std::is_same_v< U, void >, U > && Unwrap() &&
Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will...
Definition: Result.hpp:1087

ACAPI::Result::Map
Ret Map(Func func) const
This function will apply a function to a contained value and will return the result of the transforma...
Definition: Result.hpp:983

◆ MapError()

template<typename T , typename E = Error>

template<typename Func , typename Ret = Result<T, typename details::ResultErrType< std::invoke_result_t<Func, E> >::type >>

Ret ACAPI::Result< T, E >::MapError ( Func func ) const

inline

This function will apply a function to a contained error value and will return the result of the transformation.

In case the Result contains an Ok value, MapError does nothing. Note that the passed function should return a simple value and not a Result.

Template Parameters

Func	the type of the function to be applied to the error value contained in the Result.

Parameters

func	the function to be applied to the error value contained in the Result.

Returns: the result of the transformation applied to the error value by the passed function.
// static std::int32_t ChangeMessage (ACAPI::Error val) { return val.kind; }

// ACAPI::Result<TestStruct, ACAPI::Error> original { ACAPI::Error (2, "Error Message"), APINULLGuid };

// ACAPI::Result<TestStruct, std::int32_t> mapped = original.MapError (ChangeMessage);

// std::int32_t expected = mapped.UnwrapErr ();

// EXPECT_EQ (expected, 3);

◆ operator*() [1/3]

template<typename T , typename E = Error>

template<typename U = T>

std::enable_if_t<!std::is_same_v< U, void >, U > & ACAPI::Result< T, E >::operator* ( ) &

inline

Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The value contained in the Result.
ACAPI::Result<uint32_t> result {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_THROW (*result, GS::LogicErrorException);

◆ operator*() [2/3]

template<typename T , typename E = Error>

template<typename U = T>

std::enable_if_t<!std::is_same_v< U, void >, U > && ACAPI::Result< T, E >::operator* ( ) &&

inline

Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The value contained in the Result.
ACAPI::Result<uint32_t> result {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_THROW (*result, GS::LogicErrorException);

◆ operator*() [3/3]

template<typename T , typename E = Error>

template<typename U = T>

const std::enable_if_t<!std::is_same_v< U, void >, U > & ACAPI::Result< T, E >::operator* ( ) const &

inline

Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The value contained in the Result.
ACAPI::Result<uint32_t> result {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_THROW (*result, GS::LogicErrorException);

◆ operator->() [1/2]

template<typename T , typename E = Error>

template<typename U = T>

std::enable_if<!std::is_same< U, void >::value, U >::type * ACAPI::Result< T, E >::operator-> ( )

inline

Unwraps the value contained in the Result and return with a pointer to it. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The pointer contained in the Result.

◆ operator->() [2/2]

template<typename T , typename E = Error>

template<typename U = T>

const std::enable_if<!std::is_same< U, void >::value, U >::type * ACAPI::Result< T, E >::operator-> ( ) const

inline

Unwraps the value contained in the Result and return with a pointer to it. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The pointer contained in the Result.

◆ OrElse()

template<typename T , typename E = Error>

template<typename Func , typename Ret = Result<T, typename details::ResultErrType< std::invoke_result_t<Func, E> >::type >>

Ret ACAPI::Result< T, E >::OrElse ( Func func ) const

inline

This function will return the result of a transformation executed on the Error value of the Result, only if the Result contains an Error value.

Template Parameters

Func	A function with a Result<T,E> return type. It gets the ACAPI::Result value of the Result as a parameter.

Parameters

func	The function that is executed if the Result contains an Error value.

Returns: The result of the transformation.
ACAPI::Result<uint32_t> original {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_EQ (original.OrElse (square).Unwrap (), 9);

◆ Otherwise()

template<typename T , typename E = Error>

template<typename Func >

Result< T, E > ACAPI::Result< T, E >::Otherwise ( Func func ) const

inline

This function will execute a function if the Result contains an Error value.

Template Parameters

Func	a function with void return type. It gets the ACAPI::Error value of the Result as a parameter.

Parameters

func	The function that is executed if the Result contains an Error value.

Returns: The original Result.
ACAPI::Result<uint32_t> original {ACAPI::Error (3u, "Error Message"sv), APINULLGuid};

uint32_t transformed = 0;

original.Otherwise ([&transformed] (ACAPI::Error error) {

transformed = error.kind + 1;

});

EXPECT_EQ (transformed, 4u);

◆ Storage() [1/2]

template<typename T , typename E = Error>

storage_type & ACAPI::Result< T, E >::Storage ( )

inline

For internal use only.

Returns

◆ Storage() [2/2]

template<typename T , typename E = Error>

const storage_type & ACAPI::Result< T, E >::Storage ( ) const

inline

For internal use only.

Returns

◆ Then()

template<typename T , typename E = Error>

template<typename Func >

Result< T, E > ACAPI::Result< T, E >::Then ( Func func ) const

inline

This function executes the passed function if the Result contains an Ok value. In case the Result contains an Error value, Then does nothing.

Template Parameters

Func	a function with void return type. It gets the value of the Result as a parameter.

Parameters

func	The function that is executed if the Result contains an Ok value.

Returns: The original Result.
ACAPI::Result<uint32_t> original = Ok (3u);

uint32_t squared = 0;

original.Then ([&squared] (const uint32_t& val) {

squared = val * val;

});

EXPECT_EQ (squared, 9);

ACAPI::Result::Then
Result< T, E > Then(Func func) const
This function executes the passed function if the Result contains an Ok value. In case the Result con...
Definition: Result.hpp:1016

◆ Token()

template<typename T , typename E = Error>

const API_Token & ACAPI::Result< T, E >::Token ( ) const

inline

A simple getter for the Token of the AddOn which called the function that returned the Result. Mainly for internal use.

Returns: The AddOn token.

◆ Unwrap() [1/3]

template<typename T , typename E = Error>

template<typename U = T>

std::enable_if_t<!std::is_same_v< U, void >, U > & ACAPI::Result< T, E >::Unwrap ( ) &

inline

Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The value contained in the Result.
ACAPI::Result<uint32_t> result {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_THROW (result.Unwrap (), GS::LogicErrorException);

ACAPI::Result<uint32_t> r1 = Ok (3u);

uint32_t val = r1.Unwrap();

EXPECT_EQ (val, 3);

◆ Unwrap() [2/3]

template<typename T , typename E = Error>

template<typename U = T>

std::enable_if_t<!std::is_same_v< U, void >, U > && ACAPI::Result< T, E >::Unwrap ( ) &&

inline

Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The value contained in the Result.
ACAPI::Result<uint32_t> result {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_THROW (result.Unwrap (), GS::LogicErrorException);

ACAPI::Result<uint32_t> r1 = Ok (3u);

uint32_t val = r1.Unwrap();

EXPECT_EQ (val, 3);

◆ Unwrap() [3/3]

template<typename T , typename E = Error>

template<typename U = T>

const std::enable_if_t<!std::is_same_v< U, void >, U > & ACAPI::Result< T, E >::Unwrap ( ) const &

inline

Unwraps the value contained in the Result. Trying to Unwrap the value while it contains an error will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The value contained in the Result.
ACAPI::Result<uint32_t> result {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_THROW (result.Unwrap (), GS::LogicErrorException);

ACAPI::Result<uint32_t> r1 = Ok (3u);

uint32_t val = r1.Unwrap();

EXPECT_EQ (val, 3);

◆ UnwrapErr()

template<typename T , typename E = Error>

E ACAPI::Result< T, E >::UnwrapErr ( ) const

inline

Unwraps the error value contained in the Result. Trying to UnwrapErr the value while it contains an Ok value will result in crash and should be avoided. Crashing Archicad may result in disabling the AddOn during the next Archicad startup.

Returns: The value contained in the Result.
ACAPI::Result<uint32_t> result = Ok (3u);

EXPECT_EQ (result.UnwrapErr (), ACAPI::Error (NoError, "NoError"));

ACAPI::Result::UnwrapErr
E UnwrapErr() const
Unwraps the error value contained in the Result. Trying to UnwrapErr the value while it contains an O...
Definition: Result.hpp:1140

◆ UnwrapOr()

template<typename T , typename E = Error>

template<typename U = T>

const std::enable_if_t<!std::is_same_v< U, void >, U > & ACAPI::Result< T, E >::UnwrapOr ( const U & defaultValue ) const &

inline

Unwraps the value contained in the Result. In case the Result contains an Error value, it returns a default value passed in as a parameter.

Template Parameters

U	the type of the value of the Result.

Parameters

defaultValue

the default value which gets returned if the Result contains an Error.

ACAPI::Result<uint32_t> result {ACAPI::Error (3, "Error Message"sv), APINULLGuid};

EXPECT_EQ (result.UnwrapOr (10), 10);

Returns: The contained value if the Result contains one, or the defaultValue.

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Result() [1/6]

◆ Result() [2/6]

◆ Result() [3/6]

◆ Result() [4/6]

◆ Result() [5/6]

◆ Result() [6/6]

Member Function Documentation

◆ Expect()

◆ IsErr()

◆ IsOk()

◆ Map()

◆ MapError()

◆ operator*() [1/3]

◆ operator*() [2/3]

◆ operator*() [3/3]

◆ operator->() [1/2]

◆ operator->() [2/2]

◆ OrElse()

◆ Otherwise()

◆ Storage() [1/2]

◆ Storage() [2/2]

◆ Then()

◆ Token()

◆ Unwrap() [1/3]

◆ Unwrap() [2/3]

◆ Unwrap() [3/3]

◆ UnwrapErr()

◆ UnwrapOr()