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.

TrapOnDivideByZero = [bool]

Property

Product: 

Fast Math Parser

Class: 

ErrorInfo

Enables or disables the raising of a formal uCalc error when a division by zero occurs, overriding the default IEEE 754 behavior.

Remarks

By default, uCalc adheres to the IEEE 754 standard for floating-point arithmetic, where division by zero does not halt execution but instead returns inf (infinity). The RaiseErrorOnDivideByZero method allows you to override this behavior, instructing the engine to treat division by zero as a formal, catchable uCalc error.

This is crucial for applications requiring strict validation where non-finite values like inf or nan are considered invalid results.

⚙️ How It Works

  • RaiseErrorOnDivideByZero(true): Enables error raising.
  • RaiseErrorOnDivideByZero(false): Disables error raising, reverting to the default inf behavior.

This method is a convenient shortcut for manipulating the FloatDivisionByZero flag within the engine's error bitmask. For configuring multiple floating-point exceptions at once, see the more general FloatingPointErrorsToRaise method.

⚠️ Important Distinction: Eval vs. EvalStr

The effect of this setting depends on the evaluation function you use:

  • EvalStr / EvaluateStr: When an error is raised, these functions return the error message as a string (e.g., "Division by 0").
  • Eval / Evaluate: These functions always return a double. Even with error raising enabled, a division by zero will still result in inf. To check for an error after calling these, you must inspect uc.Error.Code.

⚖️ Comparative Analysis: uCalc Errors vs. Native Exceptions

In languages like C# or C++, arithmetic errors typically throw exceptions (e.g., DivideByZeroException), which involves a costly stack-unwinding process.

uCalc's error model is state-based and designed for performance. Instead of throwing an exception, it sets an internal error flag and can invoke a lightweight callback registered with AddErrorHandler. This approach is significantly faster and makes uCalc ideal for scenarios where errors are expected and common, such as parsing unvalidated user input in a loop, without the performance penalty of traditional try/catch blocks.

Examples

Succinctly demonstrates toggling the error-raising behavior for division by zero.
				
					using uCalcSoftware;

var uc = new uCalc();
// Default behavior: returns infinity
Console.WriteLine($"Default: {uc.EvalStr("1/0")}");

// Enable error raising
uc.Error.TrapOnDivideByZero = true;
Console.WriteLine($"Error Enabled: {uc.EvalStr("1/0")}");

// Disable error raising
uc.Error.TrapOnDivideByZero = false;
Console.WriteLine($"Error Disabled: {uc.EvalStr("1/0")}");
				
			
Default: inf
Error Enabled: Division by 0
Error Disabled: inf
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Default behavior: returns infinity
   cout << "Default: " << uc.EvalStr("1/0") << endl;

   // Enable error raising
   uc.Error().TrapOnDivideByZero(true);
   cout << "Error Enabled: " << uc.EvalStr("1/0") << endl;

   // Disable error raising
   uc.Error().TrapOnDivideByZero(false);
   cout << "Error Disabled: " << uc.EvalStr("1/0") << endl;
}
				
			
Default: inf
Error Enabled: Division by 0
Error Disabled: inf
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Default behavior: returns infinity
      Console.WriteLine($"Default: {uc.EvalStr("1/0")}")
      
      '// Enable error raising
      uc.Error.TrapOnDivideByZero = true
      Console.WriteLine($"Error Enabled: {uc.EvalStr("1/0")}")
      
      '// Disable error raising
      uc.Error.TrapOnDivideByZero = false
      Console.WriteLine($"Error Disabled: {uc.EvalStr("1/0")}")
   End Sub
End Module
				
			
Default: inf
Error Enabled: Division by 0
Error Disabled: inf
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
Adding an error handler callback
				
					using uCalcSoftware;

var uc = new uCalc();

static void MyErrorHandler(Handle_uCalc h) {
   var uc = new uCalc(h);
   Console.WriteLine("An error has occurred!");
   Console.WriteLine($"Error #: {(int)uc.Error.Code}");
   Console.WriteLine($"Error Message: {uc.Error.Message}");
   Console.WriteLine($"Error Symbol: {uc.Error.Symbol}");
   Console.WriteLine($"Error Location: {uc.Error.Location}");
   Console.WriteLine($"Error Expression: {uc.Error.Expression}");
}


uc.Error.AddHandler(MyErrorHandler);
Console.WriteLine(uc.EvalStr("123+"));
Console.WriteLine("");

uc.Error.TrapOnDivideByZero = true;
Console.WriteLine(uc.EvalStr("5/0"));
				
			
An error has occurred!
Error #: 257
Error Message: Syntax error
Error Symbol: +
Error Location: 3
Error Expression: 123+
Syntax error

An error has occurred!
Error #: 8
Error Message: Division by 0
Error Symbol: 
Error Location: 0
Error Expression: 
Division by 0
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call MyErrorHandler(Handle_uCalc h) {
   auto uc = uCalc(h);
   cout << "An error has occurred!" << endl;
   cout << "Error #: " << (int)uc.Error().Code() << endl;
   cout << "Error Message: " << uc.Error().Message() << endl;
   cout << "Error Symbol: " << uc.Error().Symbol() << endl;
   cout << "Error Location: " << uc.Error().Location() << endl;
   cout << "Error Expression: " << uc.Error().Expression() << endl;
}

int main() {
   uCalc uc;
   uc.Error().AddHandler(MyErrorHandler);
   cout << uc.EvalStr("123+") << endl;
   cout << "" << endl;

   uc.Error().TrapOnDivideByZero(true);
   cout << uc.EvalStr("5/0") << endl;
}
				
			
An error has occurred!
Error #: 257
Error Message: Syntax error
Error Symbol: +
Error Location: 3
Error Expression: 123+
Syntax error

An error has occurred!
Error #: 8
Error Message: Division by 0
Error Symbol: 
Error Location: 0
Error Expression: 
Division by 0
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub MyErrorHandler(ByVal h As Handle_uCalc)
      Dim uc As New uCalc(h)
      Console.WriteLine("An error has occurred!")
      Console.WriteLine($"Error #: {CInt(uc.Error.Code)}")
      Console.WriteLine($"Error Message: {uc.Error.Message}")
      Console.WriteLine($"Error Symbol: {uc.Error.Symbol}")
      Console.WriteLine($"Error Location: {uc.Error.Location}")
      Console.WriteLine($"Error Expression: {uc.Error.Expression}")
   End Sub
   
   Public Sub Main()
      Dim uc As New uCalc()
      uc.Error.AddHandler(AddressOf MyErrorHandler)
      Console.WriteLine(uc.EvalStr("123+"))
      Console.WriteLine("")
      
      uc.Error.TrapOnDivideByZero = true
      Console.WriteLine(uc.EvalStr("5/0"))
   End Sub
End Module
				
			
An error has occurred!
Error #: 257
Error Message: Syntax error
Error Symbol: +
Error Location: 3
Error Expression: 123+
Syntax error

An error has occurred!
Error #: 8
Error Message: Division by 0
Error Symbol: 
Error Location: 0
Error Expression: 
Division by 0
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