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: 

Item

The universal, polymorphic object representing any symbol defined within a uCalc instance, such as a function, variable, or operator.

Remarks

🔬 uCalc.Item: The Polymorphic Symbol Object

The uCalc.Item class is the common currency of the uCalc engine. It is a versatile, polymorphic handle that represents any symbol defined within a uCalc instance, from a simple variable to a complex function, operator, or transformer rule.

Think of it as a super-charged version of .NET's System.Object or C++'s std::any, but with a rich, built-in API for introspection and dynamic manipulation tailored for a parsing environment.

✨ Item vs. Native Reflection

In languages like C# or Java, runtime introspection is handled by a reflection API with distinct classes for different symbol types (e.g., MethodInfo, FieldInfo, PropertyInfo). uCalc simplifies this with a unified model.

  • Unified Handle: The Item class provides a single, consistent interface for all symbol types. You don't need to cast to different *Info objects.
  • Dynamic Nature: Item objects represent symbols created at runtime, often from user input, a capability that goes beyond compile-time reflection.
  • Performance: As an integrated feature, interacting with Item objects is highly optimized for the uCalc engine's internal data structures.

📖 Class Members Overview

This section provides a summary of the properties and methods available on an Item object.

🧐 Core Introspection

These properties provide access to the fundamental metadata of a symbol.

MemberDescription
NameRetrieves the programmatic name of the symbol (e.g., "MyVar", "Cos").
DescriptionGets or sets a user-defined text description for attaching metadata.
DataTypeRetrieves the DataType object representing the item's type.
TextRetrieves the original definition string ("source code") used to create the item.

🔎 Behavior & Type Checking

These members allow you to query the characteristics and behavior of a symbol.

MemberDescription
IsPropertyChecks if the item possesses a specific characteristic (e.g., Function, Operator, Locked).
CountGets the number of sub-elements, such as function parameters or array elements.
PrecedenceGets or sets the precedence level for an operator, which determines its order of operations.
TypeOfTokenGets or sets the lexical category for an item that is a token definition.

💾 Value Management

These methods provide a bridge for moving data between the host application and the uCalc engine.

MemberDescription
ValueA versatile method to get or set a variable's value, with overloads for double and string expressions.
Value<Type>A family of type-safe accessors for specific data types (e.g., ValueInt32, ValueBool, ValueStr).
ValueAddrGets a direct memory pointer to the item's value for high-performance interoperability.

⛓️ Symbol Table & Lifecycle Management

These methods allow you to manage the symbol itself within the uCalc instance.

MemberDescription
ReleasePermanently removes the symbol from the uCalc instance and frees its resources.
RenameChanges the programmatic name of the symbol at runtime.
NextOverloadRetrieves the next item in a sequence of overloaded or shadowed symbols that share the same name.
OwnedEnables RAII-style automatic memory release for an object, primarily for C++.
uCalcRetrieves the parent uCalc instance that owns this item.

🔧 Advanced & Low-Level

MemberDescription
FunctionAddressGets or sets the memory address of a native callback function associated with the item.
RegexGets or sets the regular expression pattern for an item that represents a token.
HandleRetrieves the internal, low-level identifier for the item (for diagnostics).
MemoryIndexReturns a stable, session-unique integer that identifies the item (for diagnostics).

Examples

A succinct example of creating a variable in the default instance and retrieving its value.
				
					using uCalcSoftware;

var uc = new uCalc();
using (var myVar = new uCalc.Item("Variable: x = 42")) {
   Console.WriteLine($"Created variable '{myVar.Name}' with value: {myVar.Value()}");
}
				
			
Created variable 'x' with value: 42
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::Item myVar("Variable: x = 42");
      myVar.Owned(); // Causes myVar to be released when it goes out of scope
      cout << "Created variable '" << myVar.Name() << "' with value: " << myVar.Value() << endl;
   }
}
				
			
Created variable 'x' with value: 42
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using myVar As New uCalc.Item("Variable: x = 42")
         Console.WriteLine($"Created variable '{myVar.Name}' with value: {myVar.Value()}")
      End Using
   End Sub
End Module
				
			
Created variable 'x' with value: 42
uCalc.Item constructor
				
					using uCalcSoftware;

var uc = new uCalc();

// Note that x is defined in the default instance
// while f(x) is defined in the uc instance.
var MyVar = new uCalc.Item("Variable: x = 123");
var MyFunc = new uCalc.Item(uc, "Function: f(x) = x^2");

Console.WriteLine(uCalc.DefaultInstance.Eval("x"));
Console.WriteLine(uc.Eval("f(5)"));

MyVar.Release();
MyFunc.Release();

				
			
123
25
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;

   // Note that x is defined in the default instance
   // while f(x) is defined in the uc instance.
   uCalc::Item MyVar("Variable: x = 123");
   uCalc::Item MyFunc(uc, "Function: f(x) = x^2");

   cout << uCalc::DefaultInstance().Eval("x") << endl;
   cout << uc.Eval("f(5)") << endl;

   MyVar.Release();
   MyFunc.Release();

}
				
			
123
25
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      '// Note that x is defined in the default instance
      '// while f(x) is defined in the uc instance.
      Dim MyVar As New uCalc.Item("Variable: x = 123")
      Dim MyFunc As New uCalc.Item(uc, "Function: f(x) = x^2")
      
      Console.WriteLine(uCalc.DefaultInstance.Eval("x"))
      Console.WriteLine(uc.Eval("f(5)"))
      
      MyVar.Release()
      MyFunc.Release()
      
   End Sub
End Module
				
			
123
25
Previous
Next