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.

Introduction

Product: 

Fast Math Parser

Class: 

ErrorInfo

Provides access to detailed information about parsing or evaluation errors and allows for the registration of custom error-handling callbacks.

Remarks

💣 ErrorInfo: The Error Handling Engine

The ErrorInfo class is the central hub for uCalc's state-based error handling system. It provides detailed information about parsing and evaluation errors and allows you to register custom callbacks to intercept, inspect, and even recover from them.

This class is accessed via the Error property on a uCalc instance (e.g., uc.Error).

A Different Approach: State-Based Errors vs. Exceptions

In a parsing context, especially one dealing with user input, errors like typos or incomplete formulas are normal, not "exceptional." Traditional try/catch exception handling, which interrupts program flow and unwinds the call stack, is a heavyweight solution for such common occurrences.

uCalc uses a more lightweight and flexible model:

  1. Reactive State Checking: After an operation like EvalStr fails, it doesn't throw. Instead, it sets the error state on this ErrorInfo object. You can then check properties like Code and Message to see what went wrong.

  2. Proactive Callback Handling: For more advanced control, you can register a handler with AddHandler. This callback is invoked the moment an error occurs, giving you the power to log the issue, provide custom feedback, or even fix the problem and Resume execution.

This callback-driven model is more performant and provides a unique level of control, transforming error handling from a simple failure mechanism into a dynamic recovery system.

⚙️ Error Information Properties

These properties provide detailed context about the last error that occurred.

MemberDescription
CodeRetrieves the numeric code, as an ErrorCode enum member, for the most recently triggered error.
MessageRetrieves the descriptive message for the last error that occurred.
ExpressionReturns the full expression string that was being processed when a parsing error occurred.
LocationReturns the zero-based character position where a parsing error was detected.
SymbolReturns the specific symbol or token that triggered a parsing-stage error.

🔧 Error Handling Methods & Configuration

These members allow you to configure and control the error handling pipeline.

MemberDescription
AddHandlerRegisters a callback function to intercept, log, or resolve errors during parsing and evaluation.
ResponseDetermines the engine's behavior after an error handler callback finishes executing (e.g., Abort, Resume).
RaiseTriggers a predefined or custom error from within a callback function.
GetMessageRetrieves the generic, built-in descriptive message for a specific error code.
FloatingPointErrorsToTrapConfigures which IEEE 754 floating-point exceptions (e.g., division by zero) will raise a uCalc error.
TrapOnDivideByZeroA convenience property to enable or disable raising an error on division by zero.
TrapOnInvalidA convenience property to control whether invalid floating-point operations (e.g., sqrt(-1)) raise an error.
TrapOnOverflowA convenience property to configure the engine to raise an error upon floating-point overflow.
TrapOnUnderflowA convenience property to configure whether a floating-point underflow raises an error.

Examples

Adding an error handler callback
				
					using uCalcSoftware;

var uc = new uCalc();

static void MyErrorHandler(Handle_uCalc h) {
   var uc = new uCalc(h);
   Console.WriteLine("An error has occurred!");
   Console.WriteLine($"Error #: {(int)uc.Error.Code}");
   Console.WriteLine($"Error Message: {uc.Error.Message}");
   Console.WriteLine($"Error Symbol: {uc.Error.Symbol}");
   Console.WriteLine($"Error Location: {uc.Error.Location}");
   Console.WriteLine($"Error Expression: {uc.Error.Expression}");
}


uc.Error.AddHandler(MyErrorHandler);
Console.WriteLine(uc.EvalStr("123+"));
Console.WriteLine("");

uc.Error.TrapOnDivideByZero = true;
Console.WriteLine(uc.EvalStr("5/0"));
				
			
An error has occurred!
Error #: 257
Error Message: Syntax error
Error Symbol: +
Error Location: 3
Error Expression: 123+
Syntax error

An error has occurred!
Error #: 8
Error Message: Division by 0
Error Symbol: 
Error Location: 0
Error Expression: 
Division by 0
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MyErrorHandler(Handle_uCalc h) {
   auto uc = uCalc(h);
   cout << "An error has occurred!" << endl;
   cout << "Error #: " << (int)uc.Error().Code() << endl;
   cout << "Error Message: " << uc.Error().Message() << endl;
   cout << "Error Symbol: " << uc.Error().Symbol() << endl;
   cout << "Error Location: " << uc.Error().Location() << endl;
   cout << "Error Expression: " << uc.Error().Expression() << endl;
}

int main() {
   uCalc uc;
   uc.Error().AddHandler(MyErrorHandler);
   cout << uc.EvalStr("123+") << endl;
   cout << "" << endl;

   uc.Error().TrapOnDivideByZero(true);
   cout << uc.EvalStr("5/0") << endl;
}
				
			
An error has occurred!
Error #: 257
Error Message: Syntax error
Error Symbol: +
Error Location: 3
Error Expression: 123+
Syntax error

An error has occurred!
Error #: 8
Error Message: Division by 0
Error Symbol: 
Error Location: 0
Error Expression: 
Division by 0
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MyErrorHandler(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      Console.WriteLine("An error has occurred!")
      Console.WriteLine($"Error #: {CInt(uc.Error.Code)}")
      Console.WriteLine($"Error Message: {uc.Error.Message}")
      Console.WriteLine($"Error Symbol: {uc.Error.Symbol}")
      Console.WriteLine($"Error Location: {uc.Error.Location}")
      Console.WriteLine($"Error Expression: {uc.Error.Expression}")
   End Sub
   
   Public Sub Main()
      Dim uc As New uCalc()
      uc.Error.AddHandler(AddressOf MyErrorHandler)
      Console.WriteLine(uc.EvalStr("123+"))
      Console.WriteLine("")
      
      uc.Error.TrapOnDivideByZero = true
      Console.WriteLine(uc.EvalStr("5/0"))
   End Sub
End Module
				
			
An error has occurred!
Error #: 257
Error Message: Syntax error
Error Symbol: +
Error Location: 3
Error Expression: 123+
Syntax error

An error has occurred!
Error #: 8
Error Message: Division by 0
Error Symbol: 
Error Location: 0
Error Expression: 
Division by 0
Previous
Next