uCalc API Version: 2.1.3-preview.2 Released: 6/16/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.

Code = [ErrorCode]

Property

Product: 

Fast Math Parser

Class: 

ErrorInfo

Retrieves the numeric code, as an ErrorCode enum member, for the most recently triggered error.

Remarks

The Code property is the primary mechanism for identifying the specific type of error that occurred during parsing or evaluation. It is almost always used from within a custom error handler callback registered via AddErrorHandler.

How It Works

The method returns an integer that directly corresponds to a member of the ErrorCode enumeration. This allows you to write clear, conditional logic to handle different error scenarios programmatically.

For example, you can check if the error was due to a missing variable and attempt to resolve it:

if (uc.Error.Code == ErrorCode.Undefined_Identifier) {  //... handle the missing variable}

Error State Lifecycle

An error code is set when an error is raised (either internally by uCalc or manually by your code). This error state persists until one of the following actions occurs, at which point the error is cleared and Error.Code will return ErrorCode::None (0):

  • A successful call to Parse, Eval, or EvalStr.
  • A successful call to any Define* method, such as DefineVariable or DefineFunction.

This behavior ensures that error information from a failed operation does not incorrectly affect the status of a subsequent, successful operation.

Comparative Analysis

  • vs. C# Exceptions: In C#, errors are typically handled by catching specific exception types (e.g., catch (DivideByZeroException)). This involves stack unwinding, which can have a performance cost. uCalc's model uses callbacks and error codes, which avoids this overhead. This is particularly advantageous when parsing user input, where syntax errors are common and expected, not exceptional.
  • vs. C-Style Error Codes: Traditional C APIs often return integer error codes that the caller must check after every function call. uCalc centralizes this logic into a single handler, making the main application code cleaner and less cluttered with repetitive error-checking blocks.

In summary, Error.Code provides a structured, efficient, and centralized way to manage and respond to errors within the uCalc engine.

Examples

Checking the error code for a simple syntax error
				
					using uCalcSoftware;

var uc = new uCalc();
var result = uc.Eval("MyVar * 10");
Console.WriteLine("An error has occurred!");
Console.WriteLine($"Error #: {(int)uc.Error.Code}");
Console.WriteLine($"Error Message: {uc.Error.Message}");
Console.WriteLine($"Error Location: {uc.Error.Location}");
Console.WriteLine($"Error Expression: {uc.Error.Expression}");
				
			
An error has occurred!
Error #: 258
Error Message: Undefined identifier
Error Location: 0
Error Expression: MyVar * 10
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto result = uc.Eval("MyVar * 10");
   cout << "An error has occurred!" << endl;
   cout << "Error #: " << (int)uc.Error().Code() << endl;
   cout << "Error Message: " << uc.Error().Message() << endl;
   cout << "Error Location: " << uc.Error().Location() << endl;
   cout << "Error Expression: " << uc.Error().Expression() << endl;
}
				
			
An error has occurred!
Error #: 258
Error Message: Undefined identifier
Error Location: 0
Error Expression: MyVar * 10
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim result = uc.Eval("MyVar * 10")
      Console.WriteLine("An error has occurred!")
      Console.WriteLine($"Error #: {CInt(uc.Error.Code)}")
      Console.WriteLine($"Error Message: {uc.Error.Message}")
      Console.WriteLine($"Error Location: {uc.Error.Location}")
      Console.WriteLine($"Error Expression: {uc.Error.Expression}")
   End Sub
End Module
				
			
An error has occurred!
Error #: 258
Error Message: Undefined identifier
Error Location: 0
Error Expression: MyVar * 10
Checking the error code for a simple syntax error using a callback.
				
					using uCalcSoftware;

var uc = new uCalc();

static void MyHandler(Handle_uCalc h) {
   var uc = new uCalc(h);
   // Retrieve the error code as an integer for display
   int code = (int)uc.Error.Code;
   Console.WriteLine($"Caught Error Code: {code}");

   // Compare the error code against the ErrorCode enum for logic
   if (uc.Error.Code == ErrorCode.Syntax_Error) {
      Console.WriteLine("This was a syntax error.");
   }
}


// Register the error handler
uc.Error.AddHandler(MyHandler);

// Intentionally cause a syntax error, which will trigger the handler
Console.WriteLine(uc.EvalStr("5 *"));
				
			
Caught Error Code: 257
This was a syntax error.
Syntax error
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MyHandler(Handle_uCalc h) {
   auto uc = uCalc(h);
   // Retrieve the error code as an integer for display
   int code = (int)uc.Error().Code();
   cout << "Caught Error Code: " << code << endl;

   // Compare the error code against the ErrorCode enum for logic
   if (uc.Error().Code() == ErrorCode::Syntax_Error) {
      cout << "This was a syntax error." << endl;
   }
}

int main() {
   uCalc uc;
   // Register the error handler
   uc.Error().AddHandler(MyHandler);

   // Intentionally cause a syntax error, which will trigger the handler
   cout << uc.EvalStr("5 *") << endl;
}
				
			
Caught Error Code: 257
This was a syntax error.
Syntax error
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MyHandler(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      '// Retrieve the error code as an integer for display
      Dim code As Integer = uc.Error.Code
      Console.WriteLine($"Caught Error Code: {code}")
      
      '// Compare the error code against the ErrorCode enum for logic
      If uc.Error.Code = ErrorCode.Syntax_Error Then
         Console.WriteLine("This was a syntax error.")
      End If
   End Sub
   
   Public Sub Main()
      Dim uc As New uCalc()
      '// Register the error handler
      uc.Error.AddHandler(AddressOf MyHandler)
      
      '// Intentionally cause a syntax error, which will trigger the handler
      Console.WriteLine(uc.EvalStr("5 *"))
   End Sub
End Module
				
			
Caught Error Code: 257
This was a syntax error.
Syntax error
Creating an error handler that automatically defines variables on the fly by checking for an 'Undefined Identifier' error.
				
					using uCalcSoftware;

var uc = new uCalc();

static void AutoDefineHandler(Handle_uCalc h) {
   var uc = new uCalc(h);
   // Check if the error is specifically an undefined identifier
   if (uc.Error.Code == ErrorCode.Undefined_Identifier) {
      // If so, define the missing variable and instruct uCalc to resume
      Console.WriteLine($"Auto-defining variable: '{uc.Error.Symbol}'");
      uc.DefineVariable(uc.Error.Symbol);
      uc.Error.Response = ErrorHandlerResponse.Resume;
   }
}


uc.Error.AddHandler(AutoDefineHandler);

// 'x' doesn't exist, but the handler will intercept the error and create it.
var Result = uc.EvalStr("x = 10; x * 5");
Console.WriteLine($"Result: {Result}");
				
			
Auto-defining variable: 'x'
Result: 50
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call AutoDefineHandler(Handle_uCalc h) {
   auto uc = uCalc(h);
   // Check if the error is specifically an undefined identifier
   if (uc.Error().Code() == ErrorCode::Undefined_Identifier) {
      // If so, define the missing variable and instruct uCalc to resume
      cout << "Auto-defining variable: '" << uc.Error().Symbol() << "'" << endl;
      uc.DefineVariable(uc.Error().Symbol());
      uc.Error().Response(ErrorHandlerResponse::Resume);
   }
}

int main() {
   uCalc uc;
   uc.Error().AddHandler(AutoDefineHandler);

   // 'x' doesn't exist, but the handler will intercept the error and create it.
   auto Result = uc.EvalStr("x = 10; x * 5");
   cout << "Result: " << Result << endl;
}
				
			
Auto-defining variable: 'x'
Result: 50
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub AutoDefineHandler(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      '// Check if the error is specifically an undefined identifier
      If uc.Error.Code = ErrorCode.Undefined_Identifier Then
         '// If so, define the missing variable and instruct uCalc to resume
         Console.WriteLine($"Auto-defining variable: '{uc.Error.Symbol}'")
         uc.DefineVariable(uc.Error.Symbol)
         uc.Error.Response = ErrorHandlerResponse.Resume
      End If
   End Sub
   
   Public Sub Main()
      Dim uc As New uCalc()
      uc.Error.AddHandler(AddressOf AutoDefineHandler)
      
      '// 'x' doesn't exist, but the handler will intercept the error and create it.
      Dim Result = uc.EvalStr("x = 10; x * 5")
      Console.WriteLine($"Result: {Result}")
   End Sub
End Module
				
			
Auto-defining variable: 'x'
Result: 50
Internal Test: Verifies that the error code is correctly cleared after a successful operation.
				
					using uCalcSoftware;

var uc = new uCalc();
// Trigger an error and check the code
uc.EvalStr("1+");
Console.WriteLine($"1. Error code after failure: {(int)uc.Error.Code}");

// A successful evaluation should clear the error code
uc.EvalStr("1+1");
Console.WriteLine($"2. Error code after success: {(int)uc.Error.Code}");

// Trigger a different type of error
uc.Error.TrapOnDivideByZero = true;
uc.EvalStr("1/0");
Console.WriteLine($"3. Error code after new failure: {(int)uc.Error.Code}");

// A successful definition should also clear the error code
uc.DefineVariable("x=5");
Console.WriteLine($"4. Error code after successful definition: {(int)uc.Error.Code}");
				
			
1. Error code after failure: 257
2. Error code after success: 0
3. Error code after new failure: 8
4. Error code after successful definition: 0
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Trigger an error and check the code
   uc.EvalStr("1+");
   cout << "1. Error code after failure: " << (int)uc.Error().Code() << endl;

   // A successful evaluation should clear the error code
   uc.EvalStr("1+1");
   cout << "2. Error code after success: " << (int)uc.Error().Code() << endl;

   // Trigger a different type of error
   uc.Error().TrapOnDivideByZero(true);
   uc.EvalStr("1/0");
   cout << "3. Error code after new failure: " << (int)uc.Error().Code() << endl;

   // A successful definition should also clear the error code
   uc.DefineVariable("x=5");
   cout << "4. Error code after successful definition: " << (int)uc.Error().Code() << endl;
}
				
			
1. Error code after failure: 257
2. Error code after success: 0
3. Error code after new failure: 8
4. Error code after successful definition: 0
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Trigger an error and check the code
      uc.EvalStr("1+")
      Console.WriteLine($"1. Error code after failure: {uc.Error.Code.ToString("D")}")
      
      '// A successful evaluation should clear the error code
      uc.EvalStr("1+1")
      Console.WriteLine($"2. Error code after success: {uc.Error.Code.ToString("D")}")
      
      '// Trigger a different type of error
      uc.Error.TrapOnDivideByZero = true
      uc.EvalStr("1/0")
      Console.WriteLine($"3. Error code after new failure: {uc.Error.Code.ToString("D")}")
      
      '// A successful definition should also clear the error code
      uc.DefineVariable("x=5")
      Console.WriteLine($"4. Error code after successful definition: {uc.Error.Code.ToString("D")}")
   End Sub
End Module
				
			
1. Error code after failure: 257
2. Error code after success: 0
3. Error code after new failure: 8
4. Error code after successful definition: 0
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
Retrieves the generic message for a specific error code and compares it to the last error message.
				
					using uCalcSoftware;

var uc = new uCalc();
// Retrieve the built-in message for a specific error code, without triggering an error.
Console.WriteLine($"Generic 'Undefined Identifier' message: {uc.Error.GetMessage(ErrorCode.Undefined_Identifier)}");

// Now, trigger a specific error by using an undefined variable.
uc.EvalStr("MyUndefinedVar + 5");

// Check the message and number for the last error that occurred.
Console.WriteLine($"Last error message: {uc.Error.Message}");
Console.WriteLine($"Last error number: {(int)uc.Error.Code}");
				
			
Generic 'Undefined Identifier' message: Undefined identifier
Last error message: Undefined identifier
Last error number: 258
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Retrieve the built-in message for a specific error code, without triggering an error.
   cout << "Generic 'Undefined Identifier' message: " << uc.Error().GetMessage(ErrorCode::Undefined_Identifier) << endl;

   // Now, trigger a specific error by using an undefined variable.
   uc.EvalStr("MyUndefinedVar + 5");

   // Check the message and number for the last error that occurred.
   cout << "Last error message: " << uc.Error().Message() << endl;
   cout << "Last error number: " << (int)uc.Error().Code() << endl;
}
				
			
Generic 'Undefined Identifier' message: Undefined identifier
Last error message: Undefined identifier
Last error number: 258
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Retrieve the built-in message for a specific error code, without triggering an error.
      Console.WriteLine($"Generic 'Undefined Identifier' message: {uc.Error.GetMessage(ErrorCode.Undefined_Identifier)}")
      
      '// Now, trigger a specific error by using an undefined variable.
      uc.EvalStr("MyUndefinedVar + 5")
      
      '// Check the message and number for the last error that occurred.
      Console.WriteLine($"Last error message: {uc.Error.Message}")
      Console.WriteLine($"Last error number: {CType(uc.Error.Code, Integer)}")
   End Sub
End Module
				
			
Generic 'Undefined Identifier' message: Undefined identifier
Last error message: Undefined identifier
Last error number: 258
Internal Test: Verifies that the error state is correctly cleared after a subsequent successful operation.
				
					using uCalcSoftware;

var uc = new uCalc();
// Internal Test: Verify error state is cleared
Console.WriteLine("--- Testing Error State Lifecycle ---");

// 1. Trigger a division-by-zero error.
uc.Error.TrapOnDivideByZero = true;
uc.EvalStr("1 / 0");
Console.WriteLine($"Message after 1/0: '{uc.Error.Message}'");
Console.WriteLine($"Error number is not None: {uc.Error.Code != ErrorCode.None}");

// 2. Perform a successful operation, which should clear the previous error state.
uc.EvalStr("1 + 1");

// 3. Verify the error message and number have been reset.
Console.WriteLine($"Message after successful op: '{uc.Error.Message}'");
Console.WriteLine($"Error number is now None: {uc.Error.Code == ErrorCode.None}");
				
			
--- Testing Error State Lifecycle ---
Message after 1/0: 'Division by 0'
Error number is not None: True
Message after successful op: 'No error'
Error number is now None: True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

int main() {
   uCalc uc;
   // Internal Test: Verify error state is cleared
   cout << "--- Testing Error State Lifecycle ---" << endl;

   // 1. Trigger a division-by-zero error.
   uc.Error().TrapOnDivideByZero(true);
   uc.EvalStr("1 / 0");
   cout << "Message after 1/0: '" << uc.Error().Message() << "'" << endl;
   cout << "Error number is not None: " << tf(uc.Error().Code() != ErrorCode::None) << endl;

   // 2. Perform a successful operation, which should clear the previous error state.
   uc.EvalStr("1 + 1");

   // 3. Verify the error message and number have been reset.
   cout << "Message after successful op: '" << uc.Error().Message() << "'" << endl;
   cout << "Error number is now None: " << tf(uc.Error().Code() == ErrorCode::None) << endl;
}
				
			
--- Testing Error State Lifecycle ---
Message after 1/0: 'Division by 0'
Error number is not None: True
Message after successful op: 'No error'
Error number is now None: True
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Internal Test: Verify error state is cleared
      Console.WriteLine("--- Testing Error State Lifecycle ---")
      
      '// 1. Trigger a division-by-zero error.
      uc.Error.TrapOnDivideByZero = true
      uc.EvalStr("1 / 0")
      Console.WriteLine($"Message after 1/0: '{uc.Error.Message}'")
      Console.WriteLine($"Error number is not None: {uc.Error.Code <> ErrorCode.None}")
      
      '// 2. Perform a successful operation, which should clear the previous error state.
      uc.EvalStr("1 + 1")
      
      '// 3. Verify the error message and number have been reset.
      Console.WriteLine($"Message after successful op: '{uc.Error.Message}'")
      Console.WriteLine($"Error number is now None: {uc.Error.Code = ErrorCode.None}")
   End Sub
End Module
				
			
--- Testing Error State Lifecycle ---
Message after 1/0: 'Division by 0'
Error number is not None: True
Message after successful op: 'No error'
Error number is now None: True
Practical: Creates a robust error handler that automatically defines variables on-the-fly when an 'Undefined Identifier' error occurs.
				
					using uCalcSoftware;

var uc = new uCalc();

// This error handler allows you to use variables that were not
// explicitly defined previously by defining unrecognized identifiers
// as variables instead of returning an error.
static void AutoVariableDef(Handle_uCalc h) {
   var uc = new uCalc(h);
   if (uc.Error.Code == ErrorCode.Undefined_Identifier) {
      uc.DefineVariable(uc.Error.Symbol);
      uc.Error.Response = ErrorHandlerResponse.Resume;
   }
}


uc.Error.AddHandler(AutoVariableDef);
// The handler will automatically define 'AutoTest' on first use.
Console.WriteLine(uc.Eval("AutoTest = 123"));
Console.WriteLine(uc.Eval("AutoTest * 1000"));
				
			
123
123000
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

// This error handler allows you to use variables that were not
// explicitly defined previously by defining unrecognized identifiers
// as variables instead of returning an error.
void ucalc_call AutoVariableDef(Handle_uCalc h) {
   auto uc = uCalc(h);
   if (uc.Error().Code() == ErrorCode::Undefined_Identifier) {
      uc.DefineVariable(uc.Error().Symbol());
      uc.Error().Response(ErrorHandlerResponse::Resume);
   }
}

int main() {
   uCalc uc;
   uc.Error().AddHandler(AutoVariableDef);
   // The handler will automatically define 'AutoTest' on first use.
   cout << uc.Eval("AutoTest = 123") << endl;
   cout << uc.Eval("AutoTest * 1000") << endl;
}
				
			
123
123000
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   '// This error handler allows you to use variables that were not
   '// explicitly defined previously by defining unrecognized identifiers
   '// as variables instead of returning an error.
   Public Sub AutoVariableDef(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      If uc.Error.Code = ErrorCode.Undefined_Identifier Then
         uc.DefineVariable(uc.Error.Symbol)
         uc.Error.Response = ErrorHandlerResponse.Resume
      End If
   End Sub
   
   Public Sub Main()
      Dim uc As New uCalc()
      uc.Error.AddHandler(AddressOf AutoVariableDef)
      '// The handler will automatically define 'AutoTest' on first use.
      Console.WriteLine(uc.Eval("AutoTest = 123"))
      Console.WriteLine(uc.Eval("AutoTest * 1000"))
   End Sub
End Module
				
			
123
123000
Previous
Next