Error Result

About

The error reporting system of the MAXON API is based on the maxon::Result template. Such a maxon::Result object can contain both the actual return value of the function and an error object if an error had occurred.

Result

These default error values are used to check if a maxon::Result object contains an error or not:

Note
maxon::OK can be used as a return value. But it is not possible to use maxon::FAILED as a return value. A proper error object must be returned instead.
The return value of a function returning maxon::Result<void> should be documented as "OK on success".
// This example shows a function that does not return a value
// but can return an error in case of an invalid argument or just maxon::OK.
// Note: Real code should use a reference and not a pointer.
//----------------------------------------------------------------------------------------
// Increments the given maxon::Int value.
// Returns an NullptrError if an invalid argument is given.
// @param[in,out] number Pointer to an maxon::Int value.
// @return OK on success.
//----------------------------------------------------------------------------------------
static maxon::Result<void> IncrementValue(maxon::Int* const number)
{
if (number == nullptr)
return maxon::NullptrError(MAXON_SOURCE_LOCATION);
*number = *number + 1;
return maxon::OK;
}

Result Class

A maxon::ResultBase / maxon::Result object stores the return value and the error returned by a function.

The stored value and error are accessed with:

Note
Typically errors should be handled with iferr_scope and iferr_return, see Error Handling.
// This example checks the maxon::Result returned by GetRandomNumber() manually.
const maxon::Result<maxon::Int> res = GetRandomNumber();
// if everything is OK, just print the return value
if (res == maxon::OK)
{
const maxon::Int number = res.GetValue();
DiagnosticOutput("Number: @", number);
}
// if some error occurred, print the error
if (res == maxon::FAILED)
{
const maxon::Error error = res.GetError();
const maxon::String errorMessage = error.GetMessage();
DiagnosticOutput("Error: @", errorMessage);
}

Special Classes

For special situations these specialized return values exist:

// This example shows a function template that expects a member function
// of the given type to return an error value. If this function returns
// maxon::ResultOk it can be used in the function template and does not
// require any unneeded error handling.
template <typename T> static maxon::Result<void> PrintValue(maxon::Float f)
{
T::PrintFloat(f) iferr_return;
return maxon::OK;
}
class PrintNumbers
{
public:
static maxon::ResultOk<void> PrintFloat(maxon::Float number)
{
// This function cannot fail so it just has return type maxon::ResultOk.
DiagnosticOutput("Number: @", number);
return maxon::OK;
};
static void PrintInt(maxon::Int number)
{
// Since PrintFloat() cannot fail this function does no error handling.
const maxon::Float f = maxon::Float(number);
PrintFloat(f);
};
};

Further Reading

maxon::Result::GetError
SFINAEHelper< Error, RESULT_TYPE >::type GetError() const
Definition: resultbase.h:1032
maxon::String
Definition: string.h:1213
maxon::OK
return OK
Definition: apibase.h:2546
iferr_return
#define iferr_return
Definition: resultbase.h:1465
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
maxon::Float
Float64 Float
Definition: apibase.h:195
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:167
maxon::Result< void >
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:186
iferr_scope
#define iferr_scope
Definition: resultbase.h:1374
maxon::FAILED
static const ERROR_FAILED FAILED
Definition: resultbase.h:68
maxon::ResultOk< void >
Definition: resultbase.h:192