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.

(Constructor)

Constructor

Product: 

Fast Math Parser

Class: 

Expression

Creates a new, compiled expression object from a string, ready for repeated evaluation.

Remarks

The Expression constructor is one of two primary ways to create a compiled expression object, the other being the uCalc.Parse method. An Expression object represents a pre-parsed, optimized form of a string formula, designed for efficient, repeated evaluation.

Key Distinction: Constructor vs. uCalc.Parse()

The fundamental difference lies in the context used for parsing:

  • var ... = new uCalc.Expression();: When you use the constructor, the expression is parsed within the context of the default uCalc instance (uCalc.Default). Any variables, functions, or operators defined in the default instance are available.
  • uc.Parse(...): This method parses the expression within the context of the specific uCalc instance (uc) it was called from. This is the preferred method when working with multiple, isolated parser environments.

Constructor Overloads

  1. var MyExpr = new uCalc.Expression(expression [, returnType]);Creates an expression using the default uCalc instance. This is the most common constructor.

    • expression: The string containing the formula to parse.
    • returnType: An optional DataType object specifying the expression's expected result type.

  2. var MyExpr = new uCalc.Expression(ucalcInstance, expression [, returnType]);Creates an expression using a specific uCalc instance for context, bypassing the default instance.

  3. var MyExpr() = new uCalc.Expression();Creates an empty Expression object. You must call the Parse method on this object later to associate it with a formula.

  4. var MyExpr = new uCalc.Expression(uCalc.Expression.Empty);Creates an empty placeholder handle that does not allocate significant resources. It can be assigned a real instance later.

Lifetime Management & Auto-Release

An Expression object holds compiled resources and should be released when no longer needed to free memory. This can be done manually with Release() or automatically through language-specific scoping mechanisms:

  • C#: Use the using statement: using var myExpr = new uCalc.Expression("1+1");
  • C++: Set the last arg to true: uCalc::Expression myExpr("1+1", true);

Comparative Analysis

  • vs. Eval()/EvalStr(): Methods like EvalStr are convenient for one-off calculations but are inefficient in loops because they parse the string on every call. The two-step process of creating an Expression object once and then calling Evaluate() repeatedly is significantly faster for performance-critical tasks.

  • vs. Other Libraries: While many libraries provide an eval function, uCalc's Expression object is deeply integrated into its parent uCalc instance. This means it can leverage custom functions, operators, variables, and even pre-processing transformers, offering a level of flexibility beyond simple mathematical evaluators.

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
Shows how the constructor's context (default vs. specific instance) affects variable resolution during parsing.
				
					using uCalcSoftware;

var uc = new uCalc();
// Set up two different uCalc contexts with the same variable name 'x'.
uCalc.DefaultInstance.DefineVariable("x = 1.2");
uc.DefineVariable("x = 10");

Console.WriteLine("--- Testing Expression Contexts ---");

// 1. Expression created in the *default* context uses x = 1.2
using (var exprDefault = new uCalc.Expression("x + 5")) {
   Console.WriteLine($"Default context (x=1.2): {exprDefault.Evaluate()}");

   // 2. Expression created in a *specific* context ('uc') uses x = 10
   using (var exprSpecific = new uCalc.Expression(uc, "x + 5")) {
      Console.WriteLine($"Specific context (x=10):  {exprSpecific.Evaluate()}");

      // 3. Create empty, then parse later (uses default context for the Parse call)
      using (var exprEmpty = new uCalc.Expression()) {
         exprEmpty.Parse("x * 10");
         Console.WriteLine($"Empty then parsed (x=1.2):{exprEmpty.Evaluate()}");
      }
   }
}
				
			
--- Testing Expression Contexts ---
Default context (x=1.2): 6.2
Specific context (x=10):  15
Empty then parsed (x=1.2):12
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Set up two different uCalc contexts with the same variable name 'x'.
   uCalc::DefaultInstance().DefineVariable("x = 1.2");
   uc.DefineVariable("x = 10");

   cout << "--- Testing Expression Contexts ---" << endl;

   // 1. Expression created in the *default* context uses x = 1.2
   {
      uCalc::Expression exprDefault("x + 5");
      exprDefault.Owned(); // Causes exprDefault to be released when it goes out of scope
      cout << "Default context (x=1.2): " << exprDefault.Evaluate() << endl;

      // 2. Expression created in a *specific* context ('uc') uses x = 10
      {
         uCalc::Expression exprSpecific(uc, "x + 5");
         exprSpecific.Owned(); // Causes exprSpecific to be released when it goes out of scope
         cout << "Specific context (x=10):  " << exprSpecific.Evaluate() << endl;

         // 3. Create empty, then parse later (uses default context for the Parse call)
         {
            uCalc::Expression exprEmpty;
            exprEmpty.Owned(); // Causes exprEmpty to be released when it goes out of scope
            exprEmpty.Parse("x * 10");
            cout << "Empty then parsed (x=1.2):" << exprEmpty.Evaluate() << endl;
         }
      }
   }
}
				
			
--- Testing Expression Contexts ---
Default context (x=1.2): 6.2
Specific context (x=10):  15
Empty then parsed (x=1.2):12
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Set up two different uCalc contexts with the same variable name 'x'.
      uCalc.DefaultInstance.DefineVariable("x = 1.2")
      uc.DefineVariable("x = 10")
      
      Console.WriteLine("--- Testing Expression Contexts ---")
      
      '// 1. Expression created in the *default* context uses x = 1.2
      Using exprDefault As New uCalc.Expression("x + 5")
         Console.WriteLine($"Default context (x=1.2): {exprDefault.Evaluate()}")
         
         '// 2. Expression created in a *specific* context ('uc') uses x = 10
         Using exprSpecific As New uCalc.Expression(uc, "x + 5")
            Console.WriteLine($"Specific context (x=10):  {exprSpecific.Evaluate()}")
            
            '// 3. Create empty, then parse later (uses default context for the Parse call)
            Using exprEmpty As New uCalc.Expression()
               exprEmpty.Parse("x * 10")
               Console.WriteLine($"Empty then parsed (x=1.2):{exprEmpty.Evaluate()}")
            End Using
         End Using
      End Using
   End Sub
End Module
				
			
--- Testing Expression Contexts ---
Default context (x=1.2): 6.2
Specific context (x=10):  15
Empty then parsed (x=1.2):12
Expression constructor
				
					using uCalcSoftware;

var uc = new uCalc();
uCalc.DefaultInstance.DefineVariable("x = 1.2");
uc.DefineVariable("x = 3.2");

var MyExprA = new uCalc.Expression();
var MyExprB = new uCalc.Expression("x+4.25");
var MyExprC = new uCalc.Expression("x+4.25", uCalc.DefaultInstance.DataTypeOf("int"));
var MyExprD = new uCalc.Expression(uc, "x+4.25");

MyExprA.Parse("x*100");

Console.WriteLine(MyExprA.Evaluate());
Console.WriteLine(MyExprB.Evaluate());
Console.WriteLine(MyExprC.Evaluate());
Console.WriteLine(MyExprD.Evaluate());

// Release expressions when no longer needed (see other example for auto-release)
MyExprA.Release();
MyExprB.Release();
MyExprC.Release();
MyExprD.Release();
				
			
120
5.45
5
7.45
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::DefaultInstance().DefineVariable("x = 1.2");
   uc.DefineVariable("x = 3.2");

   uCalc::Expression MyExprA;
   uCalc::Expression MyExprB("x+4.25");
   uCalc::Expression MyExprC("x+4.25", uCalc::DefaultInstance().DataTypeOf("int"));
   uCalc::Expression MyExprD(uc, "x+4.25");

   MyExprA.Parse("x*100");

   cout << MyExprA.Evaluate() << endl;
   cout << MyExprB.Evaluate() << endl;
   cout << MyExprC.Evaluate() << endl;
   cout << MyExprD.Evaluate() << endl;

   // Release expressions when no longer needed (see other example for auto-release)
   MyExprA.Release();
   MyExprB.Release();
   MyExprC.Release();
   MyExprD.Release();
}
				
			
120
5.45
5
7.45
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uCalc.DefaultInstance.DefineVariable("x = 1.2")
      uc.DefineVariable("x = 3.2")
      
      Dim MyExprA As New uCalc.Expression()
      Dim MyExprB As New uCalc.Expression("x+4.25")
      Dim MyExprC As New uCalc.Expression("x+4.25", uCalc.DefaultInstance.DataTypeOf("int"))
      Dim MyExprD As New uCalc.Expression(uc, "x+4.25")
      
      MyExprA.Parse("x*100")
      
      Console.WriteLine(MyExprA.Evaluate())
      Console.WriteLine(MyExprB.Evaluate())
      Console.WriteLine(MyExprC.Evaluate())
      Console.WriteLine(MyExprD.Evaluate())
      
      '// Release expressions when no longer needed (see other example for auto-release)
      MyExprA.Release()
      MyExprB.Release()
      MyExprC.Release()
      MyExprD.Release()
   End Sub
End Module
				
			
120
5.45
5
7.45
Previous
Next