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.

Parse

Method

Product: 

Fast Math Parser

Class: 

uCalcBase

Compiles a string expression into an intermediate, reusable object for high-performance evaluation.

Syntax

Parse(string, DataType)

Parameters

expression
string
The string containing the mathematical or logical expression to compile.
returnType
DataType
(Default = Empty)
Optional. The explicit return data type for the expression. If omitted, the type is inferred from the expression's content.

Return

Expression

An Expression object representing the compiled, ready-to-evaluate form of the input string.

Remarks

The Parse method is the first step in uCalc's high-performance, two-stage evaluation model. It takes a string expression and compiles it into a reusable Expression object. This object can then be evaluated repeatedly using methods like Evaluate or EvaluateStr.

🚀 The Performance Advantage: Parse Once, Evaluate Many

The most significant advantage of this two-step process is performance. Parsing an expression—analyzing its syntax and building an execution plan—is computationally more expensive than evaluating it. If you need to calculate the same formula multiple times (e.g., in a loop with changing variable values), using Parse is far more efficient than calling Eval or EvalStr repeatedly.

  • Inefficient (Repeated Parsing): for (i = 1 to 1000) result = uc.Eval("x*2+y");
  • Efficient (Parse Once): var p = uc.Parse("x*2+y"); for (i = 1 to 1000) result = p.Evaluate();

⚙️ Syntax and Features

The expression string passed to Parse can leverage the full power of the uCalc engine:

  • It can contain built-in or user-defined Functions and Operators.
  • It is automatically pre-processed by rules defined in the ExpressionTransformer, allowing you to create custom syntax.
  • The return type of the expression can be explicitly set or automatically inferred. If no type can be deduced, the instance's DefaultDataType (typically Double) is used.

🧠 Memory Management

An Expression object created by Parse holds resources and must be released when no longer needed to prevent memory leaks. You can manage its lifecycle in two ways:

  1. Explicit Release: Manually call the Expression.Release() method.
  2. Scoped Release (Recommended): Use language-specific constructs for automatic resource management.
    • C#: Create the object within a using statement.
    • C++: Create the Expression object on the stack (RAII).
// Recommended C# approach for automatic cleanupusing (var myExpr = new uCalc.Expression(uc.Parse("1+5"))) {// ... use myExpr ...} // myExpr is automatically released here

⚖️ Comparative Analysis

  • vs. Eval() in Scripting Languages (Python, JS): While eval() combines parsing and evaluation into one step, uCalc's Parse exposes the intermediate compiled object. This gives developers granular control, enabling performance optimizations and introspection (e.g., checking an expression's return type before evaluating it).

  • vs. C# Expression Trees: Building expression trees in C# from strings is complex. Parse provides a simple, direct way to achieve a similar result at runtime from dynamic user input.

  • vs. uCalc.Eval() and uCalc.EvalStr(): These methods are convenient for single-use evaluations. Use Parse when you anticipate evaluating the same expression structure more than once.

Examples

A simple demonstration of parsing an expression and then evaluating it.
				
					using uCalcSoftware;

var uc = new uCalc();
Console.WriteLine("Parsing the expression '100 / 4'...");
using (var parsedExpr = new uCalc.Expression("100 / 4")) {
   //var parsedExpr = uc.Parse("100 / 4");

   Console.WriteLine("Evaluating the result...");
   Console.WriteLine($"Result: {parsedExpr.Evaluate()}");
}
				
			
Parsing the expression '100 / 4'...
Evaluating the result...
Result: 25
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   cout << "Parsing the expression '100 / 4'..." << endl;
   {
      uCalc::Expression parsedExpr("100 / 4");
      parsedExpr.Owned(); // Causes parsedExpr to be released when it goes out of scope
      //var parsedExpr = uc.Parse("100 / 4");

      cout << "Evaluating the result..." << endl;
      cout << "Result: " << parsedExpr.Evaluate() << endl;
   }
}
				
			
Parsing the expression '100 / 4'...
Evaluating the result...
Result: 25
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Console.WriteLine("Parsing the expression '100 / 4'...")
      Using parsedExpr As New uCalc.Expression("100 / 4")
         '//var parsedExpr = uc.Parse("100 / 4");
         
         Console.WriteLine("Evaluating the result...")
         Console.WriteLine($"Result: {parsedExpr.Evaluate()}")
      End Using
   End Sub
End Module
				
			
Parsing the expression '100 / 4'...
Evaluating the result...
Result: 25
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
Displaying Integer (Int32) results with Evaluate32
				
					using uCalcSoftware;

var uc = new uCalc();
var VariableX = uc.DefineVariable("x");

var ParsedExpr = uc.Parse("x / 2", "Integer"); // Causes output of "x / 2" to convert to an integer

// NOTE: EvaluateInt32 should only be used when Parse() explicitly specifies Integer
// (Or Int, or Int32) as the second argument, or if the expression evaluates to an integer
// (such as evaluating a variable that was explicitly defined as integer;
// other arithmetic operators typically evaluate to Double floating point).

for (double x = 1; x <= 10; x++) {
   VariableX.Value(x);
   Console.WriteLine("x = " + VariableX.ValueStr() + "  Result = " + (ParsedExpr.EvaluateInt32()).ToString());
}

ParsedExpr.Release();
VariableX.Release();
				
			
x = 1  Result = 0
x = 2  Result = 1
x = 3  Result = 1
x = 4  Result = 2
x = 5  Result = 2
x = 6  Result = 3
x = 7  Result = 3
x = 8  Result = 4
x = 9  Result = 4
x = 10  Result = 5
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto VariableX = uc.DefineVariable("x");

   auto ParsedExpr = uc.Parse("x / 2", "Integer"); // Causes output of "x / 2" to convert to an integer

   // NOTE: EvaluateInt32 should only be used when Parse() explicitly specifies Integer
   // (Or Int, or Int32) as the second argument, or if the expression evaluates to an integer
   // (such as evaluating a variable that was explicitly defined as integer;
   // other arithmetic operators typically evaluate to Double floating point).

   for (double x = 1; x <= 10; x++) {
      VariableX.Value(x);
      cout << "x = " + VariableX.ValueStr() + "  Result = " + to_string(ParsedExpr.EvaluateInt32()) << endl;
   }

   ParsedExpr.Release();
   VariableX.Release();
}
				
			
x = 1  Result = 0
x = 2  Result = 1
x = 3  Result = 1
x = 4  Result = 2
x = 5  Result = 2
x = 6  Result = 3
x = 7  Result = 3
x = 8  Result = 4
x = 9  Result = 4
x = 10  Result = 5
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim VariableX = uc.DefineVariable("x")
      
      Dim ParsedExpr = uc.Parse("x / 2", "Integer") '// Causes output of "x / 2" to convert to an integer
      
      '// NOTE: EvaluateInt32 should only be used when Parse() explicitly specifies Integer
      '// (Or Int, or Int32) as the second argument, or if the expression evaluates to an integer
      '// (such as evaluating a variable that was explicitly defined as integer;
      '// other arithmetic operators typically evaluate to Double floating point).
      
      For x  As Double = 1 To 10
         VariableX.Value(x)
         Console.WriteLine("x = " + VariableX.ValueStr() + "  Result = " + (ParsedExpr.EvaluateInt32()).ToString())
      Next
      
      ParsedExpr.Release()
      VariableX.Release()
   End Sub
End Module
				
			
x = 1  Result = 0
x = 2  Result = 1
x = 3  Result = 1
x = 4  Result = 2
x = 5  Result = 2
x = 6  Result = 3
x = 7  Result = 3
x = 8  Result = 4
x = 9  Result = 4
x = 10  Result = 5
Previous
Next