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(string)

Method

Product: 

Fast Math Parser

Class: 

ErrorInfo

Raises an error from within a callback function, allowing for a custom, dynamic error message.

Syntax

Raise(string)

Parameters

errorMessage
string
The custom error message to be raised.

Return

ErrorHandlerResponse

Returns a value from the ErrorHandlerResponse enum, indicating the action taken by the error handler (e.g., Abort, Resume, or ReRaise).

Remarks

The ErrorRaiseMessage method allows a callback function to halt execution and signal an error using a custom, dynamically-generated message. This provides more context-specific feedback than ErrorRaise, which is limited to predefined error codes from the ErrorCode enumeration.

This method is the primary mechanism for custom validation logic within callbacks. When an error is raised, the uCalc engine's error handling pipeline is invoked. An error handler, registered with AddErrorHandler, can inspect the message and decide whether to Abort, Resume, or ReRaise the error.

End-user expressions can achieve similar functionality by using the built-in Error() function.

Comparative Analysis: uCalc Errors vs. Native Exceptions

In languages like C# or C++, errors are typically signaled by throwing exceptions.

C# Exception Example:

if (value > 100){    throw new ArgumentOutOfRangeException("Value cannot exceed 100.");}

This approach interrupts the program's flow and unwinds the call stack until a catch block is found.

uCalc's error system is different. It's a state-based mechanism that does not unwind the stack.

uCalc Callback Example:

if (cb.Arg(1) > 100) {    cb.ErrorRaiseMessage("Value cannot exceed 100.");}

When ErrorRaiseMessage is called:

  1. The engine's error state is set (Error.Code and ErrorMessage).
  2. The error handler callback stack is invoked.
  3. The handler can choose to recover from the error and resume execution, a powerful feature not easily replicated with standard exceptions.

This model is more lightweight and offers greater control over the execution flow, which is ideal for environments where user-input errors are common and recoverable.

Examples

A succinct example showing a function that unconditionally raises a custom error.
				
					using uCalcSoftware;

var uc = new uCalc();

static void MyHandler(Handle_uCalc h) {
   var uc = new uCalc(h);
   // This handler just logs the error and aborts
   Console.WriteLine($"Error Handler Caught: {uc.Error.Message}");
}
static void MyFunc(uCalc.Callback cb) {
   // This function always fails with a custom message
   cb.Error.Raise("Validation failed for input.");
}

uc.Error.AddHandler(MyHandler);
uc.DefineFunction("Validate()", MyFunc);
uc.EvalStr("Validate()"); // This call will trigger the error
				
			
Error Handler Caught: Validation failed for input.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MyHandler(Handle_uCalc h) {
   auto uc = uCalc(h);
   // This handler just logs the error and aborts
   cout << "Error Handler Caught: " << uc.Error().Message() << endl;
}
void ucalc_call MyFunc(uCalcBase::Callback cb) {
   // This function always fails with a custom message
   cb.Error().Raise("Validation failed for input.");
}
int main() {
   uCalc uc;
   uc.Error().AddHandler(MyHandler);
   uc.DefineFunction("Validate()", MyFunc);
   uc.EvalStr("Validate()"); // This call will trigger the error
}
				
			
Error Handler Caught: Validation failed for input.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MyHandler(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      '// This handler just logs the error and aborts
      Console.WriteLine($"Error Handler Caught: {uc.Error.Message}")
   End Sub
   Public Sub MyFunc(ByVal cb As uCalc.Callback)
      '// This function always fails with a custom message
      cb.Error.Raise("Validation failed for input.")
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.Error.AddHandler(AddressOf MyHandler)
      uc.DefineFunction("Validate()", AddressOf MyFunc)
      uc.EvalStr("Validate()") '// This call will trigger the error
   End Sub
End Module
				
			
Error Handler Caught: Validation failed for input.
Raises an error with a dynamic message if a validation check fails within a callback.
				
					using uCalcSoftware;

var uc = new uCalc();

static void ValidateValue(uCalc.Callback cb) {
   var val = cb.Arg(1);
   if (val > 100) {
      // The error message includes the problematic value, making it dynamic.
      cb.Error.Raise("Value exceeds maximum of 100. Got: " + val.ToString());
   } else {
      cb.Return(val);
   }
}

uc.DefineFunction("CheckValue(val)", ValidateValue);
Console.WriteLine(uc.EvalStr("CheckValue(50)"));
Console.WriteLine(uc.EvalStr("CheckValue(123)"));
				
			
50
Value exceeds maximum of 100. Got: 123
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call ValidateValue(uCalcBase::Callback cb) {
   auto val = cb.Arg(1);
   if (val > 100) {
      // The error message includes the problematic value, making it dynamic.
      cb.Error().Raise("Value exceeds maximum of 100. Got: " + to_string((int)val));
   } else {
      cb.Return(val);
   }
}
int main() {
   uCalc uc;
   uc.DefineFunction("CheckValue(val)", ValidateValue);
   cout << uc.EvalStr("CheckValue(50)") << endl;
   cout << uc.EvalStr("CheckValue(123)") << endl;
}
				
			
50
Value exceeds maximum of 100. Got: 123
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub ValidateValue(ByVal cb As uCalc.Callback)
      Dim val = cb.Arg(1)
      If val > 100 Then
         '// The error message includes the problematic value, making it dynamic.
         cb.Error.Raise("Value exceeds maximum of 100. Got: " + val.ToString())
      Else
         cb.Return(val)
      End If
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineFunction("CheckValue(val)", AddressOf ValidateValue)
      Console.WriteLine(uc.EvalStr("CheckValue(50)"))
      Console.WriteLine(uc.EvalStr("CheckValue(123)"))
   End Sub
End Module
				
			
50
Value exceeds maximum of 100. Got: 123
Internal Test: Demonstrates error recovery by having an error handler resume execution after a custom error is raised.
				
					using uCalcSoftware;

var uc = new uCalc();

static void RecoveryHandler(Handle_uCalc h) {
   var uc = new uCalc(h);
   Console.WriteLine($"Handler: Caught '{uc.Error.Message}'");
   // Attempt to recover by resuming execution.
   uc.Error.Response = ErrorHandlerResponse.Resume;
   Console.WriteLine("Handler: Resuming execution...");
}
static void RiskyOperation(uCalc.Callback cb) {
   var input = cb.ArgStr(1);
   if (input == "bad") {
      cb.Error.Raise("A recoverable error occurred.");
      // After the error handler resumes, this return value will be used.

   } else {
      cb.ReturnStr("Normal_OK");
   }
}

uc.Error.AddHandler(RecoveryHandler);
uc.DefineFunction("DoWork(s As String) As String", RiskyOperation);

Console.WriteLine("Result: " + uc.EvalStr("DoWork('good')"));
Console.WriteLine("---");
Console.WriteLine("Result: " + uc.EvalStr("DoWork('bad')"));
				
			
Result: Normal_OK
---
Handler: Caught 'A recoverable error occurred.'
Handler: Resuming execution...
Result: A recoverable error occurred.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call RecoveryHandler(Handle_uCalc h) {
   auto uc = uCalc(h);
   cout << "Handler: Caught '" << uc.Error().Message() << "'" << endl;
   // Attempt to recover by resuming execution.
   uc.Error().Response(ErrorHandlerResponse::Resume);
   cout << "Handler: Resuming execution..." << endl;
}
void ucalc_call RiskyOperation(uCalcBase::Callback cb) {
   auto input = cb.ArgStr(1);
   if (input == "bad") {
      cb.Error().Raise("A recoverable error occurred.");
      // After the error handler resumes, this return value will be used.

   } else {
      cb.ReturnStr("Normal_OK");
   }
}
int main() {
   uCalc uc;
   uc.Error().AddHandler(RecoveryHandler);
   uc.DefineFunction("DoWork(s As String) As String", RiskyOperation);

   cout << "Result: " + uc.EvalStr("DoWork('good')") << endl;
   cout << "---" << endl;
   cout << "Result: " + uc.EvalStr("DoWork('bad')") << endl;
}
				
			
Result: Normal_OK
---
Handler: Caught 'A recoverable error occurred.'
Handler: Resuming execution...
Result: A recoverable error occurred.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub RecoveryHandler(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      Console.WriteLine($"Handler: Caught '{uc.Error.Message}'")
      '// Attempt to recover by resuming execution.
      uc.Error.Response = ErrorHandlerResponse.Resume
      Console.WriteLine("Handler: Resuming execution...")
   End Sub
   Public Sub RiskyOperation(ByVal cb As uCalc.Callback)
      Dim input = cb.ArgStr(1)
      If input = "bad" Then
         cb.Error.Raise("A recoverable error occurred.")
         '// After the error handler resumes, this return value will be used.
         
      Else
         cb.ReturnStr("Normal_OK")
      End If
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.Error.AddHandler(AddressOf RecoveryHandler)
      uc.DefineFunction("DoWork(s As String) As String", AddressOf RiskyOperation)
      
      Console.WriteLine("Result: " + uc.EvalStr("DoWork('good')"))
      Console.WriteLine("---")
      Console.WriteLine("Result: " + uc.EvalStr("DoWork('bad')"))
   End Sub
End Module
				
			
Result: Normal_OK
---
Handler: Caught 'A recoverable error occurred.'
Handler: Resuming execution...
Result: A recoverable error occurred.
Raises an error in a callback using a customized message with ErrorRaiseMessage
				
					using uCalcSoftware;

var uc = new uCalc();

static void RaiseErrorMessageCallback(uCalc.Callback cb) {
   if (cb.Arg(1) == 123) {
      cb.Error.Raise("I do not like this value!");
      cb.Return(cb.Arg(1));
   }
}


uc.DefineFunction("ErrRaiseMsgTest(Value)", RaiseErrorMessageCallback);
Console.WriteLine(uc.EvalStr("ErrRaiseMsgTest(111)"));
Console.WriteLine(uc.EvalStr("ErrRaiseMsgTest(123)"));
				
			
111
I do not like this value!
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call RaiseErrorMessageCallback(uCalcBase::Callback cb) {
   if (cb.Arg(1) == 123) {
      cb.Error().Raise("I do not like this value!");
      cb.Return(cb.Arg(1));
   }
}
int main() {
   uCalc uc;

   uc.DefineFunction("ErrRaiseMsgTest(Value)", RaiseErrorMessageCallback);
   cout << uc.EvalStr("ErrRaiseMsgTest(111)") << endl;
   cout << uc.EvalStr("ErrRaiseMsgTest(123)") << endl;
}
				
			
111
I do not like this value!
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub RaiseErrorMessageCallback(ByVal cb As uCalc.Callback)
      If cb.Arg(1) = 123 Then
         cb.Error.Raise("I do not like this value!")
         cb.Return(cb.Arg(1))
      End If
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      
      uc.DefineFunction("ErrRaiseMsgTest(Value)", AddressOf RaiseErrorMessageCallback)
      Console.WriteLine(uc.EvalStr("ErrRaiseMsgTest(111)"))
      Console.WriteLine(uc.EvalStr("ErrRaiseMsgTest(123)"))
   End Sub
End Module
				
			
111
I do not like this value!
Previous
Next