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: 

Item

Creates a uCalc item, the fundamental object representing any symbol like a function, variable, or operator.

Remarks

The uCalc.Item constructor provides a low-level, direct way to create symbols within a uCalc engine instance. An Item is the fundamental building block for all named entities in uCalc, acting as a unified handle for functions, variables, operators, data types, and more.

While you can create items directly with this constructor, the recommended approach for most use cases is to use the specialized, more readable methods on the uCalc object, such as:

The constructor is functionally equivalent to calling uCalc.Define and is primarily useful when you need to construct an Item object in a context where you don't have an explicit uCalc instance readily available (in which case it uses the default instance).

⚙️ Constructor Overloads

  1. Item(string definition, ADDR address = 0)Creates an item in the default uCalc instance (uCalc.Default).

    • definition: A string containing the full definition, e.g., "Variable: x = 10" or "Function: f(x) = x*2".
    • address: (Optional) A memory address for binding the item to a native variable or function.

  2. Item(uCalc uc, string definition, ADDR address = 0)Creates an item within a specific uCalc instance.

    • uc: The target uCalc engine instance.
    • The other parameters are the same as above.

  3. Item(Item.Empty)Creates an empty placeholder Item object. This is a lightweight handle that does not allocate any significant engine resources. It can be assigned a real item later.

💡 Lifetime Management

In C++, an Item object can be made to auto-release its resources when it goes out of scope by calling Owned after it is created. In C#, the standard using statement should be used to achieve the same result.

🆚 Comparative Analysis: uCalc.Item vs. Native Reflection

In languages like C# (.NET), reflection is handled by a family of distinct classes (MethodInfo, FieldInfo, PropertyInfo, etc.). In uCalc, the Item class serves as a unified introspection object for all engine symbols.

Aspect.NET ReflectionuCalc.Item
Object ModelSeparate classes for each symbol type.A single, unified Item class.
IntrospectionUse is or GetType() checks.Use IsProperty() to check type (e.g., IsProperty(ItemIs::Function)).
CreationSymbols are defined at compile time.Symbols are created dynamically at runtime.
ExtensibilityLimited to what the language supports.Fully extensible with custom functions, operators, and types.

This unified model simplifies working with the uCalc engine, as you only need to learn one object model (Item) to inspect, modify, or release any symbol.

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
Language-specific auto-releasing of Item object
				
					using uCalcSoftware;

var uc = new uCalc();
// Language specific - auto-releasing Item object
Console.WriteLine("auto-releasing Item (language-specific)");

{ // MyVar resources will NOT be released when MyVar goes out of scope
   var MyVar = new uCalc.Item("Variable: x = 123");
   // Call MyVar.Release() explicitly if want to release it here
}

{ // MyVar resouces will be released automatically when MyVar goes of scope
   using var MyVar = new uCalc.Item("Variable: x = 123");

   // No need for MyVar.Release(), it will automatically be released
}

				
			
auto-releasing Item (language-specific)
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Language specific - auto-releasing Item object
   cout << "auto-releasing Item (language-specific)" << endl;

   { // MyVar resources will NOT be released when MyVar goes out of scope
      auto MyVar = new uCalc::Item("Variable: x = 123");
      // Call MyVar.Release() explicitly if want to release it here
   }

   { // MyVar resouces will be released automatically when MyVar goes of scope
      
      uCalc::Item MyVar("Variable: x = 123");
      // No need for MyVar.Release(), it will automatically be released
   }

}
				
			
auto-releasing Item (language-specific)
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Language specific - auto-releasing Item object
      Console.WriteLine("auto-releasing Item (language-specific)")
      #If False
         { '// MyVar resources will NOT be released when MyVar goes out of scope
         Dim MyVar = new uCalc.Item("Variable: x = 123")
         '// Call MyVar.Release() explicitly if want to release it here
         }
         
         { '// MyVar resouces will be released automatically when MyVar goes of scope
         
         
         '// No need for MyVar.Release(), it will automatically be released
         }
         #End If
      End Sub
   End Module
				
			
auto-releasing Item (language-specific)
Previous
Next