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

TrapOnUnderflow = [bool]

Property

Product: 

Fast Math Parser

Class: 

ErrorInfo

Configures whether a floating-point underflow raises a catchable uCalc error instead of silently returning 0.

Remarks

By default, uCalc follows the standard IEEE 754 behavior for floating-point underflow: an operation that results in a value too small to be represented returns 0 without interrupting execution. The RaiseErrorOnUnderflow method allows you to override this, instructing the engine to treat underflow as a catchable uCalc error.

This provides a way to enforce stricter arithmetic rules and detect calculations that lose precision, which can be critical in scientific or financial applications.

Default Behavior vs. Error Raising

SettingExpressionEvalStr ResultEval Result
RaiseErrorOnUnderflow(false)1e-320"0"0.0
RaiseErrorOnUnderflow(true)1e-320"Floating point underflow"0.0

Note: The numeric-only Eval() method will still return 0 even when this flag is enabled. To capture the error, you must use a method that can return a string, like EvalStr(), or use a custom error handler with AddErrorHandler().

For bulk configuration of all floating-point error types, use the FloatingPointErrorsToRaise() method.

💡 Comparative Analysis: State-Based Errors vs. Native Exceptions

Most programming languages handle arithmetic issues through hardware-level signals that map to language exceptions (e.g., ArithmeticException in C#). While powerful, try/catch blocks can introduce significant performance overhead, making them unsuitable for performance-critical loops where errors might be common.

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

Examples

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