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.

FloatingPointErrorsToTrap = [Int32]

Property

Product: 

Fast Math Parser

Class: 

ErrorInfo

Configures which IEEE 754 floating-point exceptions will raise a uCalc error instead of returning inf or nan.

Remarks

By default, uCalc follows the standard IEEE 754 behavior for floating-point exceptions: operations like 1/0 return inf and 0/0 return nan without interrupting execution. The FloatingPointErrorsToRaise 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.

⚙️ How It Works

uc.FloatingPointErrorsToRaise, can retrieve the current integer bitmask of enabled flags.Or you can pass a bitmask of flags to enable them. You can construct the bitmask using integer values or, more readably, by combining members of the Error.Code enum that start with Float.

✅ Available Flags

The relevant flags are members of the ErrorCode enumeration:

FlagValueTriggers OnDefault Behavior
FloatDivisionByZero8Division by zero (e.g., 1/0).Returns inf.
FloatInvalid16Invalid operations (e.g., 0/0, sqrt(-1)).Returns nan.
FloatOverflow4Result exceeds the maximum representable value.Returns inf.
FloatUnderflow2Result is too small to be represented (close to zero).Returns 0.
FloatInexact1Currently not implemented.

Helper methods like RaiseOnDivideByZero provide a more direct way to toggle individual flags.

⚖️ Comparative Analysis

uCalc's Approach vs. Native Language Exceptions (try/catch)

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.

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 AddHandler. 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 demonstrating the getter and setter functionality for a single flag.
				
					using uCalcSoftware;

var uc = new uCalc();
// Get the initial state (default is 0, no errors raised)
Console.WriteLine($"Initial flags: {uc.Error.FloatingPointErrorsToTrap}");

// Enable raising an error for division by zero
uc.Error.FloatingPointErrorsToTrap = (int)ErrorCode.FloatDivisionByZero;

// Verify the new state
Console.WriteLine($"Updated flags: {uc.Error.FloatingPointErrorsToTrap}");

// Test the behavior
Console.WriteLine($"1/0 = {uc.EvalStr("1/0")}");

// Disable the flag by setting it back to 0
uc.Error.FloatingPointErrorsToTrap = 0;
Console.WriteLine($"Flags after reset: {uc.Error.FloatingPointErrorsToTrap}");
Console.WriteLine($"1/0 after reset = {uc.EvalStr("1/0")}");
				
			
Initial flags: 0
Updated flags: 8
1/0 = Division by 0
Flags after reset: 0
1/0 after reset = inf
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Get the initial state (default is 0, no errors raised)
   cout << "Initial flags: " << uc.Error().FloatingPointErrorsToTrap() << endl;

   // Enable raising an error for division by zero
   uc.Error().FloatingPointErrorsToTrap((int)ErrorCode::FloatDivisionByZero);

   // Verify the new state
   cout << "Updated flags: " << uc.Error().FloatingPointErrorsToTrap() << endl;

   // Test the behavior
   cout << "1/0 = " << uc.EvalStr("1/0") << endl;

   // Disable the flag by setting it back to 0
   uc.Error().FloatingPointErrorsToTrap(0);
   cout << "Flags after reset: " << uc.Error().FloatingPointErrorsToTrap() << endl;
   cout << "1/0 after reset = " << uc.EvalStr("1/0") << endl;
}
				
			
Initial flags: 0
Updated flags: 8
1/0 = Division by 0
Flags after reset: 0
1/0 after reset = inf
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Get the initial state (default is 0, no errors raised)
      Console.WriteLine($"Initial flags: {uc.Error.FloatingPointErrorsToTrap}")
      
      '// Enable raising an error for division by zero
      uc.Error.FloatingPointErrorsToTrap = CInt(ErrorCode.FloatDivisionByZero)
      
      '// Verify the new state
      Console.WriteLine($"Updated flags: {uc.Error.FloatingPointErrorsToTrap}")
      
      '// Test the behavior
      Console.WriteLine($"1/0 = {uc.EvalStr("1/0")}")
      
      '// Disable the flag by setting it back to 0
      uc.Error.FloatingPointErrorsToTrap = 0
      Console.WriteLine($"Flags after reset: {uc.Error.FloatingPointErrorsToTrap}")
      Console.WriteLine($"1/0 after reset = {uc.EvalStr("1/0")}")
   End Sub
End Module
				
			
Initial flags: 0
Updated flags: 8
1/0 = Division by 0
Flags after reset: 0
1/0 after reset = inf
Demonstrates enabling multiple floating-point error types and observing the results.
				
					using uCalcSoftware;

var uc = new uCalc();
Console.WriteLine("--- Default Behavior (No Errors Raised) ---");
Console.WriteLine($"1/0: {uc.EvalStr("1/0")}");
Console.WriteLine($"0/0: {uc.EvalStr("0/0")}");
Console.WriteLine($"Overflow (5*10^308): {uc.EvalStr("5*10^308")}");
Console.WriteLine($"Underflow (10^-308/10000): {uc.EvalStr("10^-308/10000")}");

Console.WriteLine("");
Console.WriteLine("--- Enable Invalid Operation & Underflow ---");
// You can pass multiple enum members to enable them simultaneously
uc.Error.SetFloatingPointErrorsToTrap(ErrorCode.FloatInvalid, ErrorCode.FloatUnderflow);
Console.WriteLine($"Current flags: {uc.Error.FloatingPointErrorsToTrap}"); // Should be 16 (Invalid) + 2 (Underflow) = 18

Console.WriteLine($"1/0: {uc.EvalStr("1/0")}"); // Not enabled, returns inf
Console.WriteLine($"0/0: {uc.EvalStr("0/0")}"); // Enabled, raises error
Console.WriteLine($"Overflow (5*10^308): {uc.EvalStr("5*10^308")}"); // Not enabled, returns inf
Console.WriteLine($"Underflow (10^-308/10000): {uc.EvalStr("10^-308/10000")}"); // Enabled, raises error
				
			
--- Default Behavior (No Errors Raised) ---
1/0: inf
0/0: nan
Overflow (5*10^308): inf
Underflow (10^-308/10000): 0

--- Enable Invalid Operation & Underflow ---
Current flags: 18
1/0: inf
0/0: Invalid operation
Overflow (5*10^308): inf
Underflow (10^-308/10000): Floating point underflow
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   cout << "--- Default Behavior (No Errors Raised) ---" << endl;
   cout << "1/0: " << uc.EvalStr("1/0") << endl;
   cout << "0/0: " << uc.EvalStr("0/0") << endl;
   cout << "Overflow (5*10^308): " << uc.EvalStr("5*10^308") << endl;
   cout << "Underflow (10^-308/10000): " << uc.EvalStr("10^-308/10000") << endl;

   cout << "" << endl;
   cout << "--- Enable Invalid Operation & Underflow ---" << endl;
   // You can pass multiple enum members to enable them simultaneously
   uc.Error().SetFloatingPointErrorsToTrap(ErrorCode::FloatInvalid, ErrorCode::FloatUnderflow);
   cout << "Current flags: " << uc.Error().FloatingPointErrorsToTrap() << endl; // Should be 16 (Invalid) + 2 (Underflow) = 18

   cout << "1/0: " << uc.EvalStr("1/0") << endl; // Not enabled, returns inf
   cout << "0/0: " << uc.EvalStr("0/0") << endl; // Enabled, raises error
   cout << "Overflow (5*10^308): " << uc.EvalStr("5*10^308") << endl; // Not enabled, returns inf
   cout << "Underflow (10^-308/10000): " << uc.EvalStr("10^-308/10000") << endl; // Enabled, raises error
}
				
			
--- Default Behavior (No Errors Raised) ---
1/0: inf
0/0: nan
Overflow (5*10^308): inf
Underflow (10^-308/10000): 0

--- Enable Invalid Operation & Underflow ---
Current flags: 18
1/0: inf
0/0: Invalid operation
Overflow (5*10^308): inf
Underflow (10^-308/10000): Floating point underflow
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Console.WriteLine("--- Default Behavior (No Errors Raised) ---")
      Console.WriteLine($"1/0: {uc.EvalStr("1/0")}")
      Console.WriteLine($"0/0: {uc.EvalStr("0/0")}")
      Console.WriteLine($"Overflow (5*10^308): {uc.EvalStr("5*10^308")}")
      Console.WriteLine($"Underflow (10^-308/10000): {uc.EvalStr("10^-308/10000")}")
      
      Console.WriteLine("")
      Console.WriteLine("--- Enable Invalid Operation & Underflow ---")
      '// You can pass multiple enum members to enable them simultaneously
      uc.Error.SetFloatingPointErrorsToTrap(ErrorCode.FloatInvalid, ErrorCode.FloatUnderflow)
      Console.WriteLine($"Current flags: {uc.Error.FloatingPointErrorsToTrap}") '// Should be 16 (Invalid) + 2 (Underflow) = 18
      
      Console.WriteLine($"1/0: {uc.EvalStr("1/0")}") '// Not enabled, returns inf
      Console.WriteLine($"0/0: {uc.EvalStr("0/0")}") '// Enabled, raises error
      Console.WriteLine($"Overflow (5*10^308): {uc.EvalStr("5*10^308")}") '// Not enabled, returns inf
      Console.WriteLine($"Underflow (10^-308/10000): {uc.EvalStr("10^-308/10000")}") '// Enabled, raises error
   End Sub
End Module
				
			
--- Default Behavior (No Errors Raised) ---
1/0: inf
0/0: nan
Overflow (5*10^308): inf
Underflow (10^-308/10000): 0

--- Enable Invalid Operation & Underflow ---
Current flags: 18
1/0: inf
0/0: Invalid operation
Overflow (5*10^308): inf
Underflow (10^-308/10000): Floating point underflow
Internal Test: Verifies that setting and clearing all possible floating-point flags works correctly.
				
					using uCalcSoftware;

var uc = new uCalc();
// Combine all flags using integer values (or bitwise OR on enums)
var allFlags = 2 | 4 | 8 | 16; // Underflow, Overflow, DivByZero, Invalid
uc.Error.FloatingPointErrorsToTrap = allFlags;
Console.WriteLine($"All flags set: {uc.Error.FloatingPointErrorsToTrap}");

// Test all conditions
Console.WriteLine($"Underflow: {uc.EvalStr("1e-320")}");
Console.WriteLine($"Overflow: {uc.EvalStr("1e320")}");
Console.WriteLine($"DivByZero: {uc.EvalStr("1/0")}");
Console.WriteLine($"Invalid: {uc.EvalStr("0/0")}");

// Clear all flags
uc.Error.FloatingPointErrorsToTrap = 0;
Console.WriteLine("");
Console.WriteLine($"All flags cleared: {uc.Error.FloatingPointErrorsToTrap}");

// Verify they are cleared
Console.WriteLine($"Underflow: {uc.EvalStr("1e-320")}");
Console.WriteLine($"Overflow: {uc.EvalStr("1e320")}");
Console.WriteLine($"DivByZero: {uc.EvalStr("1/0")}");
Console.WriteLine($"Invalid: {uc.EvalStr("0/0")}");
				
			
All flags set: 30
Underflow: Floating point underflow
Overflow: Floating point overflow
DivByZero: Division by 0
Invalid: Invalid operation

All flags cleared: 0
Underflow: 0
Overflow: inf
DivByZero: inf
Invalid: nan
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Combine all flags using integer values (or bitwise OR on enums)
   auto allFlags = 2 | 4 | 8 | 16; // Underflow, Overflow, DivByZero, Invalid
   uc.Error().FloatingPointErrorsToTrap(allFlags);
   cout << "All flags set: " << uc.Error().FloatingPointErrorsToTrap() << endl;

   // Test all conditions
   cout << "Underflow: " << uc.EvalStr("1e-320") << endl;
   cout << "Overflow: " << uc.EvalStr("1e320") << endl;
   cout << "DivByZero: " << uc.EvalStr("1/0") << endl;
   cout << "Invalid: " << uc.EvalStr("0/0") << endl;

   // Clear all flags
   uc.Error().FloatingPointErrorsToTrap(0);
   cout << "" << endl;
   cout << "All flags cleared: " << uc.Error().FloatingPointErrorsToTrap() << endl;

   // Verify they are cleared
   cout << "Underflow: " << uc.EvalStr("1e-320") << endl;
   cout << "Overflow: " << uc.EvalStr("1e320") << endl;
   cout << "DivByZero: " << uc.EvalStr("1/0") << endl;
   cout << "Invalid: " << uc.EvalStr("0/0") << endl;
}
				
			
All flags set: 30
Underflow: Floating point underflow
Overflow: Floating point overflow
DivByZero: Division by 0
Invalid: Invalid operation

All flags cleared: 0
Underflow: 0
Overflow: inf
DivByZero: inf
Invalid: nan
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Combine all flags using integer values (or bitwise OR on enums)
      Dim allFlags = 2 Or 4 Or 8 Or 16 '// Underflow, Overflow, DivByZero, Invalid
      uc.Error.FloatingPointErrorsToTrap = allFlags
      Console.WriteLine($"All flags set: {uc.Error.FloatingPointErrorsToTrap}")
      
      '// Test all conditions
      Console.WriteLine($"Underflow: {uc.EvalStr("1e-320")}")
      Console.WriteLine($"Overflow: {uc.EvalStr("1e320")}")
      Console.WriteLine($"DivByZero: {uc.EvalStr("1/0")}")
      Console.WriteLine($"Invalid: {uc.EvalStr("0/0")}")
      
      '// Clear all flags
      uc.Error.FloatingPointErrorsToTrap = 0
      Console.WriteLine("")
      Console.WriteLine($"All flags cleared: {uc.Error.FloatingPointErrorsToTrap}")
      
      '// Verify they are cleared
      Console.WriteLine($"Underflow: {uc.EvalStr("1e-320")}")
      Console.WriteLine($"Overflow: {uc.EvalStr("1e320")}")
      Console.WriteLine($"DivByZero: {uc.EvalStr("1/0")}")
      Console.WriteLine($"Invalid: {uc.EvalStr("0/0")}")
   End Sub
End Module
				
			
All flags set: 30
Underflow: Floating point underflow
Overflow: Floating point overflow
DivByZero: Division by 0
Invalid: Invalid operation

All flags cleared: 0
Underflow: 0
Overflow: inf
DivByZero: inf
Invalid: nan
Raising floating point errors with FloatingPointErrorsToTrap
				
					using uCalcSoftware;

var uc = new uCalc();
Console.WriteLine(uc.Error.FloatingPointErrorsToTrap);
Console.WriteLine(uc.EvalStr("1/0"));
Console.WriteLine(uc.EvalStr("0/0"));
Console.WriteLine(uc.EvalStr("5*10^308"));
Console.WriteLine(uc.EvalStr("10^-308/10000"));

Console.WriteLine("--- Raise Div-by-0 ---");
uc.Error.FloatingPointErrorsToTrap = (int)ErrorCode.FloatDivisionByZero;
Console.WriteLine(uc.Error.FloatingPointErrorsToTrap);
Console.WriteLine(uc.EvalStr("1/0"));
Console.WriteLine(uc.EvalStr("0/0"));
Console.WriteLine(uc.EvalStr("5*10^308"));
Console.WriteLine(uc.EvalStr("10^-308/10000"));

Console.WriteLine("--- Raise overflow ---");
uc.Error.FloatingPointErrorsToTrap = (int)ErrorCode.FloatOverflow;
Console.WriteLine(uc.Error.FloatingPointErrorsToTrap);
Console.WriteLine(uc.EvalStr("1/0"));
Console.WriteLine(uc.EvalStr("0/0"));
Console.WriteLine(uc.EvalStr("5*10^308"));
Console.WriteLine(uc.EvalStr("10^-308/10000"));

Console.WriteLine("--- Raise invalid & underflow ---");
uc.Error.SetFloatingPointErrorsToTrap(ErrorCode.FloatInvalid, ErrorCode.FloatUnderflow);
Console.WriteLine(uc.Error.FloatingPointErrorsToTrap); // ErrorCode::FloatInvalid + ErrorCode::FloatUnderflow
Console.WriteLine(uc.EvalStr("1/0"));
Console.WriteLine(uc.EvalStr("0/0"));
Console.WriteLine(uc.EvalStr("5*10^308"));
Console.WriteLine(uc.EvalStr("10^-308/10000"));
				
			
0
inf
nan
inf
0
--- Raise Div-by-0 ---
8
Division by 0
nan
inf
0
--- Raise overflow ---
4
Floating point overflow
nan
Floating point overflow
0
--- Raise invalid & underflow ---
18
inf
Invalid operation
inf
Floating point underflow
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   cout << uc.Error().FloatingPointErrorsToTrap() << endl;
   cout << uc.EvalStr("1/0") << endl;
   cout << uc.EvalStr("0/0") << endl;
   cout << uc.EvalStr("5*10^308") << endl;
   cout << uc.EvalStr("10^-308/10000") << endl;

   cout << "--- Raise Div-by-0 ---" << endl;
   uc.Error().FloatingPointErrorsToTrap((int)ErrorCode::FloatDivisionByZero);
   cout << uc.Error().FloatingPointErrorsToTrap() << endl;
   cout << uc.EvalStr("1/0") << endl;
   cout << uc.EvalStr("0/0") << endl;
   cout << uc.EvalStr("5*10^308") << endl;
   cout << uc.EvalStr("10^-308/10000") << endl;

   cout << "--- Raise overflow ---" << endl;
   uc.Error().FloatingPointErrorsToTrap((int)ErrorCode::FloatOverflow);
   cout << uc.Error().FloatingPointErrorsToTrap() << endl;
   cout << uc.EvalStr("1/0") << endl;
   cout << uc.EvalStr("0/0") << endl;
   cout << uc.EvalStr("5*10^308") << endl;
   cout << uc.EvalStr("10^-308/10000") << endl;

   cout << "--- Raise invalid & underflow ---" << endl;
   uc.Error().SetFloatingPointErrorsToTrap(ErrorCode::FloatInvalid, ErrorCode::FloatUnderflow);
   cout << uc.Error().FloatingPointErrorsToTrap() << endl; // ErrorCode::FloatInvalid + ErrorCode::FloatUnderflow
   cout << uc.EvalStr("1/0") << endl;
   cout << uc.EvalStr("0/0") << endl;
   cout << uc.EvalStr("5*10^308") << endl;
   cout << uc.EvalStr("10^-308/10000") << endl;
}
				
			
0
inf
nan
inf
0
--- Raise Div-by-0 ---
8
Division by 0
nan
inf
0
--- Raise overflow ---
4
Floating point overflow
nan
Floating point overflow
0
--- Raise invalid & underflow ---
18
inf
Invalid operation
inf
Floating point underflow
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Console.WriteLine(uc.Error.FloatingPointErrorsToTrap)
      Console.WriteLine(uc.EvalStr("1/0"))
      Console.WriteLine(uc.EvalStr("0/0"))
      Console.WriteLine(uc.EvalStr("5*10^308"))
      Console.WriteLine(uc.EvalStr("10^-308/10000"))
      
      Console.WriteLine("--- Raise Div-by-0 ---")
      uc.Error.FloatingPointErrorsToTrap = CInt(ErrorCode.FloatDivisionByZero)
      Console.WriteLine(uc.Error.FloatingPointErrorsToTrap)
      Console.WriteLine(uc.EvalStr("1/0"))
      Console.WriteLine(uc.EvalStr("0/0"))
      Console.WriteLine(uc.EvalStr("5*10^308"))
      Console.WriteLine(uc.EvalStr("10^-308/10000"))
      
      Console.WriteLine("--- Raise overflow ---")
      uc.Error.FloatingPointErrorsToTrap = CInt(ErrorCode.FloatOverflow)
      Console.WriteLine(uc.Error.FloatingPointErrorsToTrap)
      Console.WriteLine(uc.EvalStr("1/0"))
      Console.WriteLine(uc.EvalStr("0/0"))
      Console.WriteLine(uc.EvalStr("5*10^308"))
      Console.WriteLine(uc.EvalStr("10^-308/10000"))
      
      Console.WriteLine("--- Raise invalid & underflow ---")
      uc.Error.SetFloatingPointErrorsToTrap(ErrorCode.FloatInvalid, ErrorCode.FloatUnderflow)
      Console.WriteLine(uc.Error.FloatingPointErrorsToTrap) '// ErrorCode::FloatInvalid + ErrorCode::FloatUnderflow
      Console.WriteLine(uc.EvalStr("1/0"))
      Console.WriteLine(uc.EvalStr("0/0"))
      Console.WriteLine(uc.EvalStr("5*10^308"))
      Console.WriteLine(uc.EvalStr("10^-308/10000"))
   End Sub
End Module
				
			
0
inf
nan
inf
0
--- Raise Div-by-0 ---
8
Division by 0
nan
inf
0
--- Raise overflow ---
4
Floating point overflow
nan
Floating point overflow
0
--- Raise invalid & underflow ---
18
inf
Invalid operation
inf
Floating point underflow
Previous
Next