Error Types

About

For different situations different error classes exist. These different classes help to identify the nature of the error and allow to store additional information.

Built-in Types

The default error types are defined in the core.framework.

Note
In other frameworks various specialized error types exist.
To check the type of a given error one can use maxon::IsErrorOfType().

Errors about incorrect function arguments:

Errors about incorrect function implementations:

Errors about incorrect program flow:

Specialised Errors:

General Errors:

// This example function checks every element in the given array.
// If an element is invalid, an error is added to the AggregatedError.
//----------------------------------------------------------------------------------------
// This function replaces each element of the given array with its square root.
// @param[in,out] numbers An array of maxon::Float32 values.
// @return maxon::OK on success.
//----------------------------------------------------------------------------------------
static maxon::Result<void> SquareRootElements(maxon::BaseArray<maxon::Float32>& numbers)
{
// prepare AggregatedError
// loop through all elements of the given array
const maxon::Int count = numbers.GetCount();
for (maxon::Int i = 0; i < count; ++i)
{
maxon::Float32& number = numbers[i];
if (number >= 0)
{
// replace value with its square root
number = maxon::Sqrt(number);
}
else
{
// store error for invalid element
const maxon::String errorMsg = FormatString("Negative number at index @", i);
agg.AddError(maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION, errorMsg)) iferr_return;
}
}
// if any errors were found, return the collected errors
if (agg.GetCount())
return agg;
return maxon::OK;
}
// This example reads the AggregatedError returned by a function
// and prints all sub-errors.
const maxon::Result<void> res = SquareRootElements(data);
// check for errors
if (res == maxon::FAILED)
{
const maxon::Error error = res.GetError();
// check for AggregatedError
if (error.IsInstanceOf<maxon::AggregatedError>())
{
// get AggregatedError
const maxon::AggregatedError agg = maxon::Cast<maxon::AggregatedError>(error);
// loop through all sub-errors
for (const maxon::Error subError : agg)
{
DiagnosticOutput("Sub-Error: @", subError);
}
}
}

Custom Error

All error types are based on maxon::ErrorInterface. It is possible to create custom error types based on that interface. See also Interface Basics.

A custom error interfaces is based on the maxon::ErrorInterface (see Error Class):

// This example shows the declaration of a custom error type.
// The custom error is able to store a custom error code.
// ---------------------------------------------------------------------
// Custom error class that stores an error code.
// ---------------------------------------------------------------------
class ExampleErrorInterface : MAXON_INTERFACE_BASES(maxon::ErrorInterface)
{
MAXON_INTERFACE(ExampleErrorInterface, MAXON_REFERENCE_COPY_ON_WRITE, "net.maxonexample.error.example");
public:
{
*static_cast<typename S::DirectlyReferencedType::Hxx1::ReferenceClass*>(this) = S::DirectlyReferencedType::Hxx1::ErrObj::GetInstance()();
typename S::DirectlyReferencedType::Ptr e = this->MakeWritable(false).GetPointer();
e.SetCustomErrorCode(errorCode);
}
);
// custom methods
// ---------------------------------------------------------------------
// Stores an custom error code.
// ---------------------------------------------------------------------
MAXON_METHOD void SetCustomErrorCode(maxon::Int errorCode);
// ---------------------------------------------------------------------
// Returns the stored custom error code.
// ---------------------------------------------------------------------
MAXON_METHOD maxon::Int GetCustomErrorCode() const;
};

The registration or implementation of the custom error type can be simplified with these macros:

  • ::MAXON_ERROR_REGISTERX: Registers the implementation and publishes the error object.
  • MAXON_ERROR_IMPLEMENT_AND_REGISTER: Implements and registers a whole error interface that does not introduce additional methods.
// This example shows the implementation of a custom error type.
class ExampleErrorImpl : public maxon::Component<ExampleErrorImpl, ExampleErrorInterface>
{
// use ErrorObjectClass to implement basic error functionality
MAXON_COMPONENT(NORMAL, maxon::ErrorObjectClass);
public:
maxon::Result<void> CopyFrom(const ExampleErrorImpl& src)
{
_errorCode = src._errorCode;
return maxon::OK;
}
public:
MAXON_METHOD maxon::String GetMessage() const
{
return FormatString("Error Code is @", _errorCode);
}
// custom methods
MAXON_METHOD void SetCustomErrorCode(maxon::Int errorCode)
{
_errorCode = errorCode;
}
MAXON_METHOD maxon::Int GetCustomErrorCode() const
{
return _errorCode;
}
private:
maxon::Int _errorCode;
};
// register implementation
MAXON_COMPONENT_OBJECT_REGISTER(ExampleErrorImpl, ExampleErrorObject);

The new error type can now easily be used:

// This example creates and returns an instance of the custom error.
static maxon::Result<void> CustomOperation()
{
// execute operation
const maxon::Int res = Operate();
// if no success, return error
if (res == -1)
return ExampleError(MAXON_SOURCE_LOCATION, res);
return maxon::OK;
}

Further Reading

maxon::ComponentWithBase
Definition: objectbase.h:2532
MAXON_COMPONENT_OBJECT_REGISTER
#define MAXON_COMPONENT_OBJECT_REGISTER(C,...)
Definition: objectbase.h:2355
MAXON_INTERFACE_BASES
#define MAXON_INTERFACE_BASES(...)
Definition: objectbase.h:1035
MAXON_COMPONENT
#define MAXON_COMPONENT(KIND,...)
Definition: objectbase.h:2094
maxon::String
Definition: string.h:1206
maxon::Float32
float Float32
32 bit floating point value (float)
Definition: apibase.h:183
maxon::OK
return OK
Definition: apibase.h:2547
iferr_return
#define iferr_return
Definition: resultbase.h:1434
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
maxon::BaseArray
Definition: basearray.h:366
DiagnosticOutput
#define DiagnosticOutput(formatString,...)
Definition: debugdiagnostics.h:166
MAXON_REFERENCE_COPY_ON_WRITE
#define MAXON_REFERENCE_COPY_ON_WRITE(DUMMY)
Definition: interfacebase.h:1043
maxon::src
const T & src
Definition: apibase.h:2540
maxon::Result< void >
MAXON_METHOD
#define MAXON_METHOD
Definition: interfacebase.h:855
maxon::BaseArray::GetCount
MAXON_ATTRIBUTE_FORCE_INLINE Int GetCount() const
Definition: basearray.h:527
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:189
iferr_scope
#define iferr_scope
Definition: resultbase.h:1343
SCULPTBRUSHMODE::NORMAL
@ NORMAL
Samples the surface as the user moves over it the SculptObject and returns a new hit point and normal...
maxon::FAILED
static const ERROR_FAILED FAILED
Definition: resultbase.h:68
MAXON_INTERFACE
#define MAXON_INTERFACE(Name, REFKIND, ID)
Definition: objectbase.h:1106
maxon::Result::GetError
const Error & GetError() const
Definition: resultbase.h:1026
FormatString
#define FormatString(...)
Definition: string.h:2045
maxon::AggregatedError
Definition: errorbase.h:117
MAXON_ADD_TO_COPY_ON_WRITE_REFERENCE_CLASS
#define MAXON_ADD_TO_COPY_ON_WRITE_REFERENCE_CLASS(...)
Definition: interfacebase.h:1114
MAXON_SOURCE_LOCATION_DECLARATION
#define MAXON_SOURCE_LOCATION_DECLARATION
Definition: memoryallocationbase.h:73
MAXON_SOURCE_LOCATION_FORWARD
#define MAXON_SOURCE_LOCATION_FORWARD
Definition: memoryallocationbase.h:80
maxon::Sqrt
MAXON_ATTRIBUTE_FORCE_INLINE Float32 Sqrt(Float32 val)
Calculates square root of a value. Note that the input must not be be negative, so that no exceptions...
Definition: apibasemath.h:266