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:

maxon::OK: No error had occurred.
maxon::FAILED: An error had occurred.

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:

maxon::ResultBase::GetValue(): Returns the stored value.
maxon::Result::GetError(): Returns the stored error.
maxon::ResultBase::GetValueAndError(): Returns the value and error.

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:

maxon::ResultOk: Used for functions that cannot fail but will be checked for errors nevertheless.
maxon::ResultMem: Used for functions that can only fail in out-of-memory situations.
maxon::ResultRef: Used to wrap a returned C++ pointer and to check for out-of-memory situations.
maxon::ResultPtr: Similar to maxon::ResultRef.

// 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)
{
  iferr_scope;
 
  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);
  };
};

Table of Contents

About

Result

Result Class

Special Classes

Further Reading