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.

TrapOnInvalid = [bool]

Property

Product: 

Fast Math Parser

Class: 

ErrorInfo

Controls whether invalid floating-point operations (e.g., sqrt(-1)) raise a formal error or return nan.

Remarks

By default, uCalc follows the standard IEEE 754 behavior for invalid floating-point operations: operations like sqrt(-1) or 0/0 return nan (Not a Number) without interrupting execution. The RaiseErrorOnInvalid method allows you to override this behavior, instructing the engine to treat these events as catchable uCalc errors.

This provides a centralized way to enforce stricter arithmetic rules and prevent silent propagation of non-finite values through complex calculations.

⚙️ Behavior

  • Disabled (Default): An expression like uc.EvalStr("sqrt(-1)") returns the string "nan".
  • Enabled: Calling uc.RaiseErrorOnInvalid(true) changes the behavior. The same expression will now trigger a FloatInvalid error. The EvalStr call will return the error message (e.g., "Invalid operation"), and the error can be intercepted by a handler registered with AddErrorHandler.

This is a convenience method that acts as a shortcut for modifying the master bitmask controlled by FloatingPointErrorsToRaise.

⚖️ Comparative Analysis

Most programming languages handle floating-point exceptions through hardware-level signals that can be mapped to language-level exceptions (e.g., ArithmeticException in C#). While powerful, try/catch blocks can introduce significant performance overhead.

uCalc's mechanism operates within its own error system. When a floating-point error is raised, it sets an internal error state that can be checked via Error.Code or handled by a callback. This approach avoids the high cost of native exception handling, allowing for robust error checking even in tight loops where performance is paramount.

Examples

A succinct example showing how to enable error raising for invalid operations.
				
					using uCalcSoftware;

var uc = new uCalc();
// By default, invalid operations return 'nan'
Console.WriteLine(uc.EvalStr("sqrt(-1)"));

// Enable error raising for this specific case
uc.Error.TrapOnInvalid = true;

// Now, the same operation returns a descriptive error message
Console.WriteLine(uc.EvalStr("sqrt(-1)"));
				
			
nan
Invalid operation
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // By default, invalid operations return 'nan'
   cout << uc.EvalStr("sqrt(-1)") << endl;

   // Enable error raising for this specific case
   uc.Error().TrapOnInvalid(true);

   // Now, the same operation returns a descriptive error message
   cout << uc.EvalStr("sqrt(-1)") << endl;
}
				
			
nan
Invalid operation
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// By default, invalid operations return 'nan'
      Console.WriteLine(uc.EvalStr("sqrt(-1)"))
      
      '// Enable error raising for this specific case
      uc.Error.TrapOnInvalid = true
      
      '// Now, the same operation returns a descriptive error message
      Console.WriteLine(uc.EvalStr("sqrt(-1)"))
   End Sub
End Module
				
			
nan
Invalid operation
A practical example using an error handler to provide a custom, user-friendly message when an invalid operation occurs.
				
					using uCalcSoftware;

var uc = new uCalc();

static void MyErrorHandler(Handle_uCalc h) {
   var uc = new uCalc(h);
   // Check if the specific 'FloatInvalid' error was raised
   if (uc.Error.Code == ErrorCode.FloatInvalid) {
      Console.WriteLine("Error: The calculation resulted in an invalid number (e.g., square root of a negative).");
      // Stop further processing
      uc.Error.Response = ErrorHandlerResponse.Abort;
   }
}


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

// Tell uCalc to raise an error instead of returning 'nan'
uc.Error.TrapOnInvalid = true;

// This will now trigger our custom error handler's message
uc.EvalStr("sqrt(-4)");
				
			
Error: The calculation resulted in an invalid number (e.g., square root of a negative).
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MyErrorHandler(Handle_uCalc h) {
   auto uc = uCalc(h);
   // Check if the specific 'FloatInvalid' error was raised
   if (uc.Error().Code() == ErrorCode::FloatInvalid) {
      cout << "Error: The calculation resulted in an invalid number (e.g., square root of a negative)." << endl;
      // Stop further processing
      uc.Error().Response(ErrorHandlerResponse::Abort);
   }
}

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

   // Tell uCalc to raise an error instead of returning 'nan'
   uc.Error().TrapOnInvalid(true);

   // This will now trigger our custom error handler's message
   uc.EvalStr("sqrt(-4)");
}
				
			
Error: The calculation resulted in an invalid number (e.g., square root of a negative).
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MyErrorHandler(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      '// Check if the specific 'FloatInvalid' error was raised
      If uc.Error.Code = ErrorCode.FloatInvalid Then
         Console.WriteLine("Error: The calculation resulted in an invalid number (e.g., square root of a negative).")
         '// Stop further processing
         uc.Error.Response = ErrorHandlerResponse.Abort
      End If
   End Sub
   
   Public Sub Main()
      Dim uc As New uCalc()
      '// Register the custom error handler
      uc.Error.AddHandler(AddressOf MyErrorHandler)
      
      '// Tell uCalc to raise an error instead of returning 'nan'
      uc.Error.TrapOnInvalid = true
      
      '// This will now trigger our custom error handler's message
      uc.EvalStr("sqrt(-4)")
   End Sub
End Module
				
			
Error: The calculation resulted in an invalid number (e.g., square root of a negative).
Internal test verifying the behavior of all `RaiseErrorOn...` flag methods.
				
					using uCalcSoftware;

var uc = new uCalc();
// --- Division by Zero ---
Console.WriteLine(uc.EvalStr("1/0"));
uc.Error.TrapOnDivideByZero = true;
Console.WriteLine(uc.EvalStr("1/0"));

// --- Invalid Operation ---
Console.WriteLine(uc.EvalStr("Sqrt(-1)"));
uc.Error.TrapOnInvalid = true;
Console.WriteLine(uc.EvalStr("Sqrt(-1)"));

// --- Overflow ---
Console.WriteLine(uc.EvalStr("5*10^308"));
uc.Error.TrapOnOverflow = true;
Console.WriteLine(uc.EvalStr("5*10^308"));

// --- Underflow ---
Console.WriteLine(uc.EvalStr("10^-308/10000"));
uc.Error.TrapOnUnderflow = true;
Console.WriteLine(uc.EvalStr("10^-308/10000"));
				
			
inf
Division by 0
nan
Invalid operation
inf
Floating point overflow
0
Floating point underflow
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // --- Division by Zero ---
   cout << uc.EvalStr("1/0") << endl;
   uc.Error().TrapOnDivideByZero(true);
   cout << uc.EvalStr("1/0") << endl;

   // --- Invalid Operation ---
   cout << uc.EvalStr("Sqrt(-1)") << endl;
   uc.Error().TrapOnInvalid(true);
   cout << uc.EvalStr("Sqrt(-1)") << endl;

   // --- Overflow ---
   cout << uc.EvalStr("5*10^308") << endl;
   uc.Error().TrapOnOverflow(true);
   cout << uc.EvalStr("5*10^308") << endl;

   // --- Underflow ---
   cout << uc.EvalStr("10^-308/10000") << endl;
   uc.Error().TrapOnUnderflow(true);
   cout << uc.EvalStr("10^-308/10000") << endl;
}
				
			
inf
Division by 0
nan
Invalid operation
inf
Floating point overflow
0
Floating point underflow
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// --- Division by Zero ---
      Console.WriteLine(uc.EvalStr("1/0"))
      uc.Error.TrapOnDivideByZero = true
      Console.WriteLine(uc.EvalStr("1/0"))
      
      '// --- Invalid Operation ---
      Console.WriteLine(uc.EvalStr("Sqrt(-1)"))
      uc.Error.TrapOnInvalid = true
      Console.WriteLine(uc.EvalStr("Sqrt(-1)"))
      
      '// --- Overflow ---
      Console.WriteLine(uc.EvalStr("5*10^308"))
      uc.Error.TrapOnOverflow = true
      Console.WriteLine(uc.EvalStr("5*10^308"))
      
      '// --- Underflow ---
      Console.WriteLine(uc.EvalStr("10^-308/10000"))
      uc.Error.TrapOnUnderflow = true
      Console.WriteLine(uc.EvalStr("10^-308/10000"))
   End Sub
End Module
				
			
inf
Division by 0
nan
Invalid operation
inf
Floating point overflow
0
Floating point underflow
RaiseErrorOnDivideByZero
				
					using uCalcSoftware;

var uc = new uCalc();
Console.WriteLine(uc.EvalStr("1/0"));
uc.Error.TrapOnDivideByZero = true;
Console.WriteLine(uc.EvalStr("1/0"));

Console.WriteLine(uc.EvalStr("Sqrt(-1)"));
uc.Error.TrapOnInvalid = true;
Console.WriteLine(uc.EvalStr("Sqrt(-1)"));

Console.WriteLine(uc.EvalStr("5*10^308"));
uc.Error.TrapOnOverflow = true;
Console.WriteLine(uc.EvalStr("5*10^308"));

Console.WriteLine(uc.EvalStr("10^-308/10000"));
uc.Error.TrapOnUnderflow = true;
Console.WriteLine(uc.EvalStr("10^-308/10000"));
				
			
inf
Division by 0
nan
Invalid operation
inf
Floating point overflow
0
Floating point underflow
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   cout << uc.EvalStr("1/0") << endl;
   uc.Error().TrapOnDivideByZero(true);
   cout << uc.EvalStr("1/0") << endl;

   cout << uc.EvalStr("Sqrt(-1)") << endl;
   uc.Error().TrapOnInvalid(true);
   cout << uc.EvalStr("Sqrt(-1)") << endl;

   cout << uc.EvalStr("5*10^308") << endl;
   uc.Error().TrapOnOverflow(true);
   cout << uc.EvalStr("5*10^308") << endl;

   cout << uc.EvalStr("10^-308/10000") << endl;
   uc.Error().TrapOnUnderflow(true);
   cout << uc.EvalStr("10^-308/10000") << endl;
}
				
			
inf
Division by 0
nan
Invalid operation
inf
Floating point overflow
0
Floating point underflow
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Console.WriteLine(uc.EvalStr("1/0"))
      uc.Error.TrapOnDivideByZero = true
      Console.WriteLine(uc.EvalStr("1/0"))
      
      Console.WriteLine(uc.EvalStr("Sqrt(-1)"))
      uc.Error.TrapOnInvalid = true
      Console.WriteLine(uc.EvalStr("Sqrt(-1)"))
      
      Console.WriteLine(uc.EvalStr("5*10^308"))
      uc.Error.TrapOnOverflow = true
      Console.WriteLine(uc.EvalStr("5*10^308"))
      
      Console.WriteLine(uc.EvalStr("10^-308/10000"))
      uc.Error.TrapOnUnderflow = true
      Console.WriteLine(uc.EvalStr("10^-308/10000"))
   End Sub
End Module
				
			
inf
Division by 0
nan
Invalid operation
inf
Floating point overflow
0
Floating point underflow
Previous
Next