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.

Working with Variables

Product: 

Class: 

Learn how to define, use, and programmatically manipulate variables within the uCalc expression engine.

Remarks

💾 Working with Variables

Variables are named placeholders that store values for use in your expressions. They are fundamental to creating dynamic and reusable logic in uCalc. Unlike constants, the value of a variable can be changed at any time.

1. Defining and Using Variables

The easiest way to create a variable is with the DefineVariable method. You can define its name, data type, and initial value in a single, readable string.

// Define a variable 'rate' with an initial value of 0.05uc.DefineVariable("rate = 0.05");// Use the variable in an expressionConsole.WriteLine(uc.EvalStr("100 * rate")); // Output: 5

Type Inference and Explicit Typing

uCalc automatically infers the data type from the initial value:

  • x = 10 becomes a numeric type (usually Double).
  • name = 'Alice' becomes a String.

You can also explicitly declare a type using the As keyword, which is useful for ensuring type safety or optimizing memory usage.

// Explicitly define an integer variableuc.DefineVariable("counter As Int = 0");

2. Interacting from Host Code

For high-performance applications, especially those involving loops, repeatedly calling EvalStr to set a variable's value is inefficient because it requires parsing a string every time. The recommended approach is to get a handle to the variable's Item object and modify its value directly from your host code (C#, C++, etc.).

// Get a handle to the variable when you define itvar myVar = uc.DefineVariable("x");// Parse an expression that uses the variable ONCEvar expr = uc.Parse("x * 2");// In a loop, update the value directly and evaluate the pre-parsed expressionfor ( i = 1; i <= 3; i++) {     myVar.Value(i); // This is a fast, direct value update    Console.WriteLine($"Result: {expr.Evaluate()}"); // This is a fast evaluation}

This two-step pattern (parse once, update and evaluate many times) is the key to achieving high performance with uCalc.

💡 Why uCalc? (Comparative Analysis)

  • vs. C#/C++: Variables in compiled languages are defined at compile-time. uCalc's variables are created at runtime, allowing you to build dynamic systems where variables can be defined based on user input, configuration files, or other runtime conditions.

  • vs. Dynamic Languages (Python, JavaScript): While also dynamic, uCalc provides a sandboxed environment with a clear distinction between the host application and the script engine. The programmatic interaction via Item.Value() offers a highly optimized bridge between these two worlds.

  • Host Memory Binding: For ultimate performance, uCalc allows you to bind a variable directly to a memory address in your host application using an optional parameter in DefineVariable. This creates a zero-copy link, which is a powerful feature for tight integrations.

Examples

A basic example of defining a variable and using it in an expression.
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineVariable("x = 10");
Console.WriteLine(uc.EvalStr("x * 5"));
				
			
50
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineVariable("x = 10");
   cout << uc.EvalStr("x * 5") << endl;
}
				
			
50
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("x = 10")
      Console.WriteLine(uc.EvalStr("x * 5"))
   End Sub
End Module
				
			
50
Calculates simple interest using pre-defined variables for a real-world scenario.
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineVariable("principal = 5000");
uc.DefineVariable("rate = 0.05");
uc.DefineVariable("years = 4");
Console.WriteLine($"Interest: {uc.EvalStr("principal * rate * years")}");
				
			
Interest: 1000
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineVariable("principal = 5000");
   uc.DefineVariable("rate = 0.05");
   uc.DefineVariable("years = 4");
   cout << "Interest: " << uc.EvalStr("principal * rate * years") << endl;
}
				
			
Interest: 1000
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("principal = 5000")
      uc.DefineVariable("rate = 0.05")
      uc.DefineVariable("years = 4")
      Console.WriteLine($"Interest: {uc.EvalStr("principal * rate * years")}")
   End Sub
End Module
				
			
Interest: 1000
Internal Test: Tests programmatic updates to a variable from host code in a loop, a common high-performance pattern.
				
					using uCalcSoftware;

var uc = new uCalc();
var myVar = uc.DefineVariable("x");
var expr = uc.Parse("x * 2");

var i = 0;
for ( i = 1; i <= 5; i++) {
   myVar.Value(i);
   Console.WriteLine($"When x is {i}, result is: {expr.Evaluate()}");
}
				
			
When x is 1, result is: 2
When x is 2, result is: 4
When x is 3, result is: 6
When x is 4, result is: 8
When x is 5, result is: 10
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto myVar = uc.DefineVariable("x");
   auto expr = uc.Parse("x * 2");

   auto i = 0;
   for ( i = 1; i <= 5; i++) {
      myVar.Value(i);
      cout << "When x is " << i << ", result is: " << expr.Evaluate() << endl;
   }
}
				
			
When x is 1, result is: 2
When x is 2, result is: 4
When x is 3, result is: 6
When x is 4, result is: 8
When x is 5, result is: 10
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim myVar = uc.DefineVariable("x")
      Dim expr = uc.Parse("x * 2")
      
      Dim i = 0
      For i  = 1 To 5
         myVar.Value(i)
         Console.WriteLine($"When x is {i}, result is: {expr.Evaluate()}")
      Next
   End Sub
End Module
				
			
When x is 1, result is: 2
When x is 2, result is: 4
When x is 3, result is: 6
When x is 4, result is: 8
When x is 5, result is: 10
Previous
Next