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.

Introduction

Product: 

Fast Math Parser

Class: 

Expression

An overview of the compiled expression object, the core component for high-performance, repeated evaluation.

Remarks

⚡️ The Expression Class: A Compiled Formula

The Expression class represents a pre-parsed, compiled, and reusable formula. It is the cornerstone of uCalc's high-performance evaluation model, allowing you to separate the computationally expensive task of parsing a string from the lightning-fast task of executing it.

An Expression object is created by calling uCalc.Parse or by using the Expression constructor. Once created, it can be evaluated repeatedly with different variable values, achieving performance that approaches native compiled code.

🚀 The "Parse-Once, Evaluate-Many" Pattern

The primary purpose of the Expression object is to enable the "Parse-Once, Evaluate-Many" pattern, which is critical for performance in loops or other repetitive calculations.

  • The Inefficient Way: Calling uCalc.EvalStr inside a loop forces the engine to re-parse the same string on every iteration.
  • The uCalc Way: Parse the string once into an Expression object before the loop, and call a method like Evaluate or Execute on that object inside the loop.

For a detailed guide, see the Optimizing Performance tutorial.

🔗 Context and Lifetime

  • Evaluation Context: Every Expression is intrinsically linked to the parent uCalc instance that created it. This parent instance provides the context of variables, functions, and operators needed for evaluation. You can retrieve this parent using the uCalc property.
  • Memory Management: An Expression object holds native resources and must be released to prevent memory leaks. This is best done using language-idiomatic scoping mechanisms like using in C# or RAII via the Owned method in C++. For manual control, you can use the Release method.

Class Members

Below is a list of members for the Expression class.

Core Evaluation Methods

MemberDescription
EvaluateEvaluates a pre-parsed expression, returning a numeric result. This is the high-performance second step in the parse-evaluate workflow.
EvaluateBoolEvaluates a pre-parsed boolean expression, returning the native true or false result efficiently.
EvaluateDblRapidly evaluates a pre-parsed expression, optimized specifically for double-precision floating-point results.
EvaluateInt32Evaluates a pre-parsed expression and returns the result as a 32-bit integer.
EvaluateStrEvaluates a pre-parsed expression and returns the result of any data type as a string.
EvaluateVoidEvaluates the expression and returns a native pointer to the result's memory location.
ExecuteExecutes a pre-parsed expression without returning a value, optimized for operations valued for their side effects rather than their result.

Construction & Management

MemberDescription
ConstructorCreates a new, compiled expression object from a string, ready for repeated evaluation.
ParseParses a new expression.
CloneCreates an identical, yet completely independent, copy of a parsed expression object.
ReleaseFrees the memory and resources associated with a compiled expression object, making it invalid for future use.
OwnedManages automatic resource release for an object, enabling RAII-style lifetime management primarily for C++.

Introspection & Metadata

MemberDescription
DataTypeRetrieves the resulting data type of a parsed expression without needing to evaluate it.
uCalcReturns the parent uCalc instance that owns this expression, providing access to its evaluation context.
HandleReturns the internal handle of the Expression object, a unique identifier used by the library for low-level operations.
MemoryIndexReturns a stable, predictable integer index for the expression object, useful for diagnostics and tracking object lifetime.

Examples

Demonstrates the basic creation and immediate evaluation of an expression object.
				
					using uCalcSoftware;

var uc = new uCalc();
// Basic construction and evaluation using the default uCalc instance.
using (var MyExpr = new uCalc.Expression("10 * (2 + 3)")) {
   Console.WriteLine(MyExpr.Evaluate());
}
				
			
50
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Basic construction and evaluation using the default uCalc instance.
   {
      uCalc::Expression MyExpr("10 * (2 + 3)");
      MyExpr.Owned(); // Causes MyExpr to be released when it goes out of scope
      cout << MyExpr.Evaluate() << endl;
   }
}
				
			
50
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Basic construction and evaluation using the default uCalc instance.
      Using MyExpr As New uCalc.Expression("10 * (2 + 3)")
         Console.WriteLine(MyExpr.Evaluate())
      End Using
   End Sub
End Module
				
			
50
Illustrates the core relationship between the uCalc engine, an Item (variable), and a compiled Expression.
				
					using uCalcSoftware;

var uc = new uCalc();
var VariableX = uc.DefineVariable("x");
var Expression = "x^2 * 10"; // Replace this with your expression

Console.WriteLine("--- Efficient: Parse() once, then Evaluate() in a loop ---");
var ParsedExpr = uc.Parse(Expression);
for (double x = 1; x <= 10; x++) {
   VariableX.Value(x);
   Console.WriteLine(ParsedExpr.Evaluate());
}

ParsedExpr.Release();
VariableX.Release();
				
			
--- Efficient: Parse() once, then Evaluate() in a loop ---
10
40
90
160
250
360
490
640
810
1000
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto VariableX = uc.DefineVariable("x");
   auto Expression = "x^2 * 10"; // Replace this with your expression

   cout << "--- Efficient: Parse() once, then Evaluate() in a loop ---" << endl;
   auto ParsedExpr = uc.Parse(Expression);
   for (double x = 1; x <= 10; x++) {
      VariableX.Value(x);
      cout << ParsedExpr.Evaluate() << endl;
   }

   ParsedExpr.Release();
   VariableX.Release();
}
				
			
--- Efficient: Parse() once, then Evaluate() in a loop ---
10
40
90
160
250
360
490
640
810
1000
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim VariableX = uc.DefineVariable("x")
      Dim Expression = "x^2 * 10" '// Replace this with your expression
      
      Console.WriteLine("--- Efficient: Parse() once, then Evaluate() in a loop ---")
      Dim ParsedExpr = uc.Parse(Expression)
      For x  As Double = 1 To 10
         VariableX.Value(x)
         Console.WriteLine(ParsedExpr.Evaluate())
      Next
      
      ParsedExpr.Release()
      VariableX.Release()
   End Sub
End Module
				
			
--- Efficient: Parse() once, then Evaluate() in a loop ---
10
40
90
160
250
360
490
640
810
1000
Previous
Next