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