Open Search
    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;
    }
    Int64 Int
    signed 32/64 bit int, size depends on the platform
    Definition: apibase.h:213
    return OK
    Definition: apibase.h:2746
    #define MAXON_SOURCE_LOCATION
    Definition: memoryallocationbase.h:67

    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
    {
    const maxon::Error error = res.GetError();
    const maxon::String errorMessage = error.GetMessage();
    DiagnosticOutput("Error: @", errorMessage);
    }
    Definition: string.h:1235
    PyObject * error
    Definition: codecs.h:206
    Py_UCS4 * res
    Definition: unicodeobject.h:1113
    #define DiagnosticOutput(formatString,...)
    Definition: debugdiagnostics.h:176
    static const ERROR_FAILED FAILED
    Definition: resultbase.h:68

    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);
    };
    };
    Definition: resultbase.h:193
    PyFrameObject * f
    Definition: ceval.h:26
    Float64 Float
    Definition: apibase.h:222
    #define iferr_scope
    Definition: resultbase.h:1389
    #define iferr_return
    Definition: resultbase.h:1524

    Further Reading