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.

TrapOnOverflow = [bool]

Property

Product: 

Fast Math Parser

Class: 

ErrorInfo

Configures the engine to raise a catchable uCalc error upon floating-point overflow instead of silently returning infinity.

Remarks

By default, uCalc follows the standard IEEE 754 behavior for floating-point exceptions: an operation that results in a value exceeding the maximum representable number for a double returns inf (infinity) without interrupting execution. The RaiseErrorOnOverflow method allows you to override this behavior, instructing the engine to treat this event as a catchable uCalc error.

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

This method is a convenience wrapper for setting a specific flag via the more general FloatingPointErrorsToRaise method. The following two calls are equivalent:

// Using the convenience methoduc.RaiseErrorOnOverflow(true);// Using the general-purpose methoduc.FloatingPointErrorsToRaise(uCalc.ErrorCode.FloatOverflow);

⚖️ Comparative Analysis: uCalc Errors vs. Native Exceptions

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, making them unsuitable for use inside performance-critical loops where invalid user input might be common.

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 defined with AddErrorHandler. 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 toggle overflow error reporting on and off.
				
					using uCalcSoftware;

var uc = new uCalc();
// 1. Default behavior: returns 'inf'
Console.WriteLine(uc.EvalStr("1e308 * 10"));

// 2. Enable error raising for overflow
uc.Error.TrapOnOverflow = true;
Console.WriteLine(uc.EvalStr("1e308 * 10"));

// 3. Disable it again to revert to default
uc.Error.TrapOnOverflow = false;
Console.WriteLine(uc.EvalStr("1e308 * 10"));
				
			
inf
Floating point overflow
inf
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // 1. Default behavior: returns 'inf'
   cout << uc.EvalStr("1e308 * 10") << endl;

   // 2. Enable error raising for overflow
   uc.Error().TrapOnOverflow(true);
   cout << uc.EvalStr("1e308 * 10") << endl;

   // 3. Disable it again to revert to default
   uc.Error().TrapOnOverflow(false);
   cout << uc.EvalStr("1e308 * 10") << endl;
}
				
			
inf
Floating point overflow
inf
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// 1. Default behavior: returns 'inf'
      Console.WriteLine(uc.EvalStr("1e308 * 10"))
      
      '// 2. Enable error raising for overflow
      uc.Error.TrapOnOverflow = true
      Console.WriteLine(uc.EvalStr("1e308 * 10"))
      
      '// 3. Disable it again to revert to default
      uc.Error.TrapOnOverflow = false
      Console.WriteLine(uc.EvalStr("1e308 * 10"))
   End Sub
End Module
				
			
inf
Floating point overflow
inf
A practical example demonstrating all four related floating-point error configuration methods.
				
					using uCalcSoftware;

var uc = new uCalc();
Console.WriteLine($"Divide by Zero (Default): {uc.EvalStr("1/0")}");
uc.Error.TrapOnDivideByZero = true;
Console.WriteLine($"Divide by Zero (Error Enabled): {uc.EvalStr("1/0")}");

Console.WriteLine("");
Console.WriteLine($"Invalid Operation (Default): {uc.EvalStr("Sqrt(-1)")}");
uc.Error.TrapOnInvalid = true;
Console.WriteLine($"Invalid Operation (Error Enabled): {uc.EvalStr("Sqrt(-1)")}");

Console.WriteLine("");
Console.WriteLine($"Overflow (Default): {uc.EvalStr("5*10^308")}");
uc.Error.TrapOnOverflow = true;
Console.WriteLine($"Overflow (Error Enabled): {uc.EvalStr("5*10^308")}");

Console.WriteLine("");
Console.WriteLine($"Underflow (Default): {uc.EvalStr("10^-308/10000")}");
uc.Error.TrapOnUnderflow = true;
Console.WriteLine($"Underflow (Error Enabled): {uc.EvalStr("10^-308/10000")}");
				
			
Divide by Zero (Default): inf
Divide by Zero (Error Enabled): Division by 0

Invalid Operation (Default): nan
Invalid Operation (Error Enabled): Invalid operation

Overflow (Default): inf
Overflow (Error Enabled): Floating point overflow

Underflow (Default): 0
Underflow (Error Enabled): Floating point underflow
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   cout << "Divide by Zero (Default): " << uc.EvalStr("1/0") << endl;
   uc.Error().TrapOnDivideByZero(true);
   cout << "Divide by Zero (Error Enabled): " << uc.EvalStr("1/0") << endl;

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

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

   cout << "" << endl;
   cout << "Underflow (Default): " << uc.EvalStr("10^-308/10000") << endl;
   uc.Error().TrapOnUnderflow(true);
   cout << "Underflow (Error Enabled): " << uc.EvalStr("10^-308/10000") << endl;
}
				
			
Divide by Zero (Default): inf
Divide by Zero (Error Enabled): Division by 0

Invalid Operation (Default): nan
Invalid Operation (Error Enabled): Invalid operation

Overflow (Default): inf
Overflow (Error Enabled): Floating point overflow

Underflow (Default): 0
Underflow (Error Enabled): Floating point underflow
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Console.WriteLine($"Divide by Zero (Default): {uc.EvalStr("1/0")}")
      uc.Error.TrapOnDivideByZero = true
      Console.WriteLine($"Divide by Zero (Error Enabled): {uc.EvalStr("1/0")}")
      
      Console.WriteLine("")
      Console.WriteLine($"Invalid Operation (Default): {uc.EvalStr("Sqrt(-1)")}")
      uc.Error.TrapOnInvalid = true
      Console.WriteLine($"Invalid Operation (Error Enabled): {uc.EvalStr("Sqrt(-1)")}")
      
      Console.WriteLine("")
      Console.WriteLine($"Overflow (Default): {uc.EvalStr("5*10^308")}")
      uc.Error.TrapOnOverflow = true
      Console.WriteLine($"Overflow (Error Enabled): {uc.EvalStr("5*10^308")}")
      
      Console.WriteLine("")
      Console.WriteLine($"Underflow (Default): {uc.EvalStr("10^-308/10000")}")
      uc.Error.TrapOnUnderflow = true
      Console.WriteLine($"Underflow (Error Enabled): {uc.EvalStr("10^-308/10000")}")
   End Sub
End Module
				
			
Divide by Zero (Default): inf
Divide by Zero (Error Enabled): Division by 0

Invalid Operation (Default): nan
Invalid Operation (Error Enabled): Invalid operation

Overflow (Default): inf
Overflow (Error Enabled): Floating point overflow

Underflow (Default): 0
Underflow (Error Enabled): Floating point underflow
Internal Test: An overflow error is intercepted by a custom error handler.
				
					using uCalcSoftware;

var uc = new uCalc();

static void MyErrorHandler(Handle_uCalc h) {
   var uc = new uCalc(h);
   Console.WriteLine("--- Error Handler Caught ---");
   Console.WriteLine($"  Code: {(int)uc.Error.Code}");
   Console.WriteLine($"  Message: {uc.Error.Message}");
   // Abort is the default response, no need to set it.
}


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

// Configure the engine to raise an error on overflow
uc.Error.TrapOnOverflow = true;

// This evaluation will now be intercepted by our handler
Console.WriteLine("Evaluating expression '1e999'...");
uc.EvalStr("1e999"); // This triggers the callback
Console.WriteLine("Evaluation finished.");
				
			
Evaluating expression '1e999'...
--- Error Handler Caught ---
  Code: 4
  Message: Floating point overflow
Evaluation finished.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MyErrorHandler(Handle_uCalc h) {
   auto uc = uCalc(h);
   cout << "--- Error Handler Caught ---" << endl;
   cout << "  Code: " << (int)uc.Error().Code() << endl;
   cout << "  Message: " << uc.Error().Message() << endl;
   // Abort is the default response, no need to set it.
}

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

   // Configure the engine to raise an error on overflow
   uc.Error().TrapOnOverflow(true);

   // This evaluation will now be intercepted by our handler
   cout << "Evaluating expression '1e999'..." << endl;
   uc.EvalStr("1e999"); // This triggers the callback
   cout << "Evaluation finished." << endl;
}
				
			
Evaluating expression '1e999'...
--- Error Handler Caught ---
  Code: 4
  Message: Floating point overflow
Evaluation finished.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MyErrorHandler(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      Console.WriteLine("--- Error Handler Caught ---")
      Console.WriteLine($"  Code: {CInt(uc.Error.Code)}")
      Console.WriteLine($"  Message: {uc.Error.Message}")
      '// Abort is the default response, no need to set it.
   End Sub
   
   Public Sub Main()
      Dim uc As New uCalc()
      '// Register the custom error handler
      uc.Error.AddHandler(AddressOf MyErrorHandler)
      
      '// Configure the engine to raise an error on overflow
      uc.Error.TrapOnOverflow = true
      
      '// This evaluation will now be intercepted by our handler
      Console.WriteLine("Evaluating expression '1e999'...")
      uc.EvalStr("1e999") '// This triggers the callback
      Console.WriteLine("Evaluation finished.")
   End Sub
End Module
				
			
Evaluating expression '1e999'...
--- Error Handler Caught ---
  Code: 4
  Message: Floating point overflow
Evaluation finished.
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
Internal Test: Verifies that only the division by zero flag is affected, while other floating-point exceptions like overflow remain unchanged by default.
				
					using uCalcSoftware;

var uc = new uCalc();
// Enable only the division by zero error
uc.Error.TrapOnDivideByZero = true;

// This should now raise a uCalc error
Console.WriteLine($"Test 1 (Div by Zero): {uc.EvalStr("1/0")}");

// This should still return 'inf' by default, as we didn't enable overflow errors
Console.WriteLine($"Test 2 (Overflow): {uc.EvalStr("1e308 * 2")}");

// For comparison, enable overflow errors as well
uc.Error.TrapOnOverflow = true;
Console.WriteLine($"Test 3 (Overflow with error): {uc.EvalStr("1e308 * 2")}");
				
			
Test 1 (Div by Zero): Division by 0
Test 2 (Overflow): inf
Test 3 (Overflow with error): Floating point overflow
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Enable only the division by zero error
   uc.Error().TrapOnDivideByZero(true);

   // This should now raise a uCalc error
   cout << "Test 1 (Div by Zero): " << uc.EvalStr("1/0") << endl;

   // This should still return 'inf' by default, as we didn't enable overflow errors
   cout << "Test 2 (Overflow): " << uc.EvalStr("1e308 * 2") << endl;

   // For comparison, enable overflow errors as well
   uc.Error().TrapOnOverflow(true);
   cout << "Test 3 (Overflow with error): " << uc.EvalStr("1e308 * 2") << endl;
}
				
			
Test 1 (Div by Zero): Division by 0
Test 2 (Overflow): inf
Test 3 (Overflow with error): Floating point overflow
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Enable only the division by zero error
      uc.Error.TrapOnDivideByZero = true
      
      '// This should now raise a uCalc error
      Console.WriteLine($"Test 1 (Div by Zero): {uc.EvalStr("1/0")}")
      
      '// This should still return 'inf' by default, as we didn't enable overflow errors
      Console.WriteLine($"Test 2 (Overflow): {uc.EvalStr("1e308 * 2")}")
      
      '// For comparison, enable overflow errors as well
      uc.Error.TrapOnOverflow = true
      Console.WriteLine($"Test 3 (Overflow with error): {uc.EvalStr("1e308 * 2")}")
   End Sub
End Module
				
			
Test 1 (Div by Zero): Division by 0
Test 2 (Overflow): inf
Test 3 (Overflow with error): Floating point overflow
Previous
Next