uCalc API Version: 2.1.3-preview.2 Released: 6/17/2026

Warning

uCalc API Preview Release Notice:The documentation describes the intended behavior of the API. The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.

Raise(ErrorCode)

Method

Product: 

Fast Math Parser

Class: 

ErrorInfo

Triggers a predefined uCalc error from within a custom callback function, returning the final response from the error handler chain.

Syntax

Raise(ErrorCode)

Parameters

errCode
ErrorCode
The predefined error to trigger, selected from the `ErrorCode` enumeration.

Return

ErrorHandlerResponse

An ErrorHandlerResponse value indicating the action requested by any registered error handlers. The callback should typically return this value to the uCalc engine to ensure the error is handled correctly.

Remarks

The ErrorRaise method provides a controlled way to trigger an error from within a callback function. Unlike a native throw statement, this method invokes uCalc's internal error handling system, allowing registered handlers to intercept, log, or even recover from the error before it halts execution.

How It Works

  1. Your callback calls ErrorRaise with a specific ErrorCode code.
  2. The uCalc engine invokes the chain of error handlers registered via AddErrorHandler.
  3. Handlers can respond with Abort, Resume, or ReRaise.
  4. ErrorRaise returns the final ErrorHandlerResponse determined by the handler chain.

Handling the Return Value

The return value from ErrorRaise is crucial. It informs your callback what action the error handlers decided upon. Your callback can inspect this value and act accordingly. For example, if an error handler successfully resolves a problem and requests to Resume, your callback can continue its logic instead of aborting.

For custom error messages, use ErrorRaiseMessage instead.

⚖️ Comparative Analysis

  • vs. Native throw (C#/C++): A native throw immediately unwinds the call stack, interrupting the flow of execution. ErrorRaise does not. It is a controlled, synchronous call into the uCalc error system. It returns a value to your callback, giving it the opportunity to react to the outcome of the error handling process without unwinding the native stack.

  • vs. C-Style Return Codes: While it returns a code, ErrorRaise is far more powerful. Instead of just signaling that an error occurred, it actively triggers a sophisticated, layered handling system (AddErrorHandler) that can dynamically resolve issues.

Examples

A succinct example that triggers a standard syntax error if the input value is negative.
				
					using uCalcSoftware;

var uc = new uCalc();

static void DoublePositive(uCalc.Callback cb) {
   // If input is negative, raise a syntax error.
   if (cb.Arg(1) < 0) {
      cb.Error.Raise(ErrorCode.Syntax_Error);
   }
   cb.Return(cb.Arg(1) * 2);
}

uc.DefineFunction("DoublePositive(x)", DoublePositive);
Console.WriteLine(uc.EvalStr("DoublePositive(10)"));
Console.WriteLine(uc.EvalStr("DoublePositive(-5)"));
				
			
20
Syntax error
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call DoublePositive(uCalcBase::Callback cb) {
   // If input is negative, raise a syntax error.
   if (cb.Arg(1) < 0) {
      cb.Error().Raise(ErrorCode::Syntax_Error);
   }
   cb.Return(cb.Arg(1) * 2);
}
int main() {
   uCalc uc;
   uc.DefineFunction("DoublePositive(x)", DoublePositive);
   cout << uc.EvalStr("DoublePositive(10)") << endl;
   cout << uc.EvalStr("DoublePositive(-5)") << endl;
}
				
			
20
Syntax error
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub DoublePositive(ByVal cb As uCalc.Callback)
      '// If input is negative, raise a syntax error.
      If cb.Arg(1) < 0 Then
         cb.Error.Raise(ErrorCode.Syntax_Error)
      End If
      cb.Return(cb.Arg(1) * 2)
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineFunction("DoublePositive(x)", AddressOf DoublePositive)
      Console.WriteLine(uc.EvalStr("DoublePositive(10)"))
      Console.WriteLine(uc.EvalStr("DoublePositive(-5)"))
   End Sub
End Module
				
			
20
Syntax error
Raising an error in a callback with ErrorRaise
				
					using uCalcSoftware;

var uc = new uCalc();

static void RaiseErrorCallback(uCalc.Callback cb) {
   if (cb.Arg(1) == 123) {
      cb.Error.Raise(ErrorCode.Unrecognized_Command);
   }
   cb.Return(cb.Arg(1));
}


uc.DefineFunction("ErrRaiseTest(Value)", RaiseErrorCallback);
Console.WriteLine(uc.EvalStr("ErrRaiseTest(111)"));
Console.WriteLine(uc.EvalStr("ErrRaiseTest(123)")); // The callback arbitrarily raises an error for 123
				
			
111
Unrecognized command
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call RaiseErrorCallback(uCalcBase::Callback cb) {
   if (cb.Arg(1) == 123) {
      cb.Error().Raise(ErrorCode::Unrecognized_Command);
   }
   cb.Return(cb.Arg(1));
}
int main() {
   uCalc uc;

   uc.DefineFunction("ErrRaiseTest(Value)", RaiseErrorCallback);
   cout << uc.EvalStr("ErrRaiseTest(111)") << endl;
   cout << uc.EvalStr("ErrRaiseTest(123)") << endl; // The callback arbitrarily raises an error for 123
}
				
			
111
Unrecognized command
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub RaiseErrorCallback(ByVal cb As uCalc.Callback)
      If cb.Arg(1) = 123 Then
         cb.Error.Raise(ErrorCode.Unrecognized_Command)
      End If
      cb.Return(cb.Arg(1))
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      
      uc.DefineFunction("ErrRaiseTest(Value)", AddressOf RaiseErrorCallback)
      Console.WriteLine(uc.EvalStr("ErrRaiseTest(111)"))
      Console.WriteLine(uc.EvalStr("ErrRaiseTest(123)")) '// The callback arbitrarily raises an error for 123
   End Sub
End Module
				
			
111
Unrecognized command
Previous
Next