uCalc API Version: 5.7.0-preview.1 Released: 7/30/2026

Warning

uCalc API Preview Release Notice:This preview documentation describes the intended behavior of the API. It is not fully accurate or complete.The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.Use of the preview version in your production code is not recommended.

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

How to enable error raising for invalid operations.

ID: 406

See: TrapOnInvalid = [bool] 
				
					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
Explore 600+ other examples
				
					#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
Explore 600+ other examples
				
					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
Explore 600+ other examples
A practical example using an error handler to provide a custom, user-friendly message when an invalid operation occurs.

ID: 407

See: TrapOnInvalid = [bool] 
				
					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).
Explore 600+ other examples
				
					#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).
Explore 600+ other examples
				
					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).
Explore 600+ other examples
Internal test verifying the behavior of all `RaiseErrorOn...` flag methods.

ID: 408

See: TrapOnInvalid = [bool] 
				
					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
Explore 600+ other examples
				
					#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
Explore 600+ other examples
				
					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
Explore 600+ other examples
RaiseErrorOnDivideByZero

ID: 80

See: Error = [ErrorInfo], TrapOnDivideByZero = [bool], TrapOnInvalid = [bool], TrapOnOverflow = [bool], TrapOnUnderflow = [bool] 
				
					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
Explore 600+ other examples
				
					#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
Explore 600+ other examples
				
					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
Explore 600+ other examples