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.

Description = [string]

Property

Product: 

Fast Math Parser

Class: 

Item

Gets or sets a user-defined text description for a uCalc symbol, useful for attaching metadata and for debugging.

Remarks

🏷️ Attaching Metadata with Description

The Description property provides a powerful way to attach arbitrary string metadata to any Item. This is invaluable for debugging, creating self-documenting configurations, and identifying specific components at runtime.

⚙️ Getter and Setter Behavior

This property functions as both a getter and a setter, accessed using the uCalc property syntax.

  • Getter: Retrieves the current description. If no description has been set, it returns an empty string.var desc = myItem.Description;

  • Setter: Assigns a new description string to the item.myItem.Description = "This is a test variable";

✨ Fluent Interface

The setter supports a fluent interface by returning the Item object itself. This allows you to chain multiple configuration calls together in a single, readable statement.

// Chaining .Description() with .Rename()var myItem = uc.DefineFunction("f() = 1").Description = "My Function".Rename("my_func");

🎯 Core Use Cases

  • 💡 Debugging: When working with a Transformer, you can assign a unique description to each Rule. During processing, you can query the rule that generated a match to understand exactly why a transformation occurred.

  • 📦 Runtime Metadata: Attach contextual information directly to functions, variables, or operators. This allows you to build introspection tools that can inspect a uCalc instance and generate documentation or build a dynamic user interface.

✨ Special Behavior: Tokens

When a token is defined (e.g., via uCalc.Tokens.Add()), its Description is automatically populated with the string name of its assigned TokenType (e.g., "Whitespace", "Literal"). This provides immediate, built-in metadata for lexical components.

⚖️ Comparative Analysis

Without an integrated Description property, developers often resort to less ideal solutions for tracking metadata:

  • vs. External Dictionaries: Managing a Dictionary<Item, string> is cumbersome. It requires manual synchronization, and if an Item is released, the dictionary entry can become a memory leak.
  • vs. Wrapper Classes: Creating a custom class just to add a description field adds significant boilerplate code.
  • vs. Code Comments: Standard code comments are static and cannot be accessed by the program at runtime. An Item's description is dynamic data that can be queried and displayed by your application.

uCalc's integrated approach is superior because the metadata is tightly coupled with the object itself and is consistently available across the object model. This creates a unified, easy-to-use system for runtime introspection.

Examples

Succinct: Attaches and retrieves a simple metadata description from a variable.
				
					using uCalcSoftware;

var uc = new uCalc();
var myVar = uc.DefineVariable("x = 10");
myVar.Description = "Represents the user's current score.";

Console.WriteLine($"Variable Name: {myVar.Name}");
Console.WriteLine($"Description: {myVar.Description}");
				
			
Variable Name: x
Description: Represents the user's current score.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto myVar = uc.DefineVariable("x = 10");
   myVar.Description("Represents the user's current score.");

   cout << "Variable Name: " << myVar.Name() << endl;
   cout << "Description: " << myVar.Description() << endl;
}
				
			
Variable Name: x
Description: Represents the user's current score.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim myVar = uc.DefineVariable("x = 10")
      myVar.Description = "Represents the user's current score."
      
      Console.WriteLine($"Variable Name: {myVar.Name}")
      Console.WriteLine($"Description: {myVar.Description}")
   End Sub
End Module
				
			
Variable Name: x
Description: Represents the user's current score.
Determining properties of an expression part
				
					using uCalcSoftware;

var uc = new uCalc();

static void ItemCallback(uCalc.Callback cb) {
   Console.WriteLine($"Name: {cb.Item.Name}");
   Console.WriteLine($"Data type: {cb.Item.DataType.Name}");
   Console.WriteLine($"Param count: {cb.Item.Count}");
   Console.Write("Procedure type: ");
   if (cb.Item.IsProperty(ItemIs.Operator)) {
      Console.WriteLine("Operator");
   } else if (cb.Item.IsProperty(ItemIs.Function)) {
      Console.WriteLine("Function");
   }
   Console.WriteLine(cb.Item.Text);
   Console.WriteLine(cb.Item.Description);
   Console.WriteLine("---");
}


uc.DefineFunction("AAA() As Double", ItemCallback).Description = "Does this and that";
uc.DefineFunction("BBB(x, y, z) As String", ItemCallback).Description = "Does something else";
uc.DefineOperator("{x} CCC {y} As Int32", 0, Associativity.LeftToRight, ItemCallback);

uc.EvalStr("AAA()");
uc.EvalStr("BBB(9, 8, 7)");
uc.EvalStr("5 CCC 4");

				
			
Name: aaa
Data type: double
Param count: 0
Procedure type: Function
Function: AAA() As Double
Does this and that
---
Name: bbb
Data type: string
Param count: 3
Procedure type: Function
Function: BBB(x, y, z) As String
Does something else
---
Name: ccc
Data type: int
Param count: 2
Procedure type: Operator
Operator: {x} CCC {y} As Int32

---
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call ItemCallback(uCalcBase::Callback cb) {
   cout << "Name: " << cb.Item().Name() << endl;
   cout << "Data type: " << cb.Item().DataType().Name() << endl;
   cout << "Param count: " << cb.Item().Count() << endl;
   cout << "Procedure type: ";
   if (cb.Item().IsProperty(ItemIs::Operator)) {
      cout << "Operator" << endl;
   } else if (cb.Item().IsProperty(ItemIs::Function)) {
      cout << "Function" << endl;
   }
   cout << cb.Item().Text() << endl;
   cout << cb.Item().Description() << endl;
   cout << "---" << endl;
}
int main() {
   uCalc uc;

   uc.DefineFunction("AAA() As Double", ItemCallback).Description("Does this and that");
   uc.DefineFunction("BBB(x, y, z) As String", ItemCallback).Description("Does something else");
   uc.DefineOperator("{x} CCC {y} As Int32", 0, Associativity::LeftToRight, ItemCallback);

   uc.EvalStr("AAA()");
   uc.EvalStr("BBB(9, 8, 7)");
   uc.EvalStr("5 CCC 4");

}
				
			
Name: aaa
Data type: double
Param count: 0
Procedure type: Function
Function: AAA() As Double
Does this and that
---
Name: bbb
Data type: string
Param count: 3
Procedure type: Function
Function: BBB(x, y, z) As String
Does something else
---
Name: ccc
Data type: int
Param count: 2
Procedure type: Operator
Operator: {x} CCC {y} As Int32

---
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub ItemCallback(ByVal cb As uCalc.Callback)
      Console.WriteLine($"Name: {cb.Item.Name}")
      Console.WriteLine($"Data type: {cb.Item.DataType.Name}")
      Console.WriteLine($"Param count: {cb.Item.Count}")
      Console.Write("Procedure type: ")
      If cb.Item.IsProperty(ItemIs.Operator) Then
         Console.WriteLine("Operator")
         ElseIf cb.Item.IsProperty(ItemIs.Function ) Then
            Console.WriteLine("Function")
         End If
         Console.WriteLine(cb.Item.Text)
         Console.WriteLine(cb.Item.Description)
         Console.WriteLine("---")
      End Sub
      Public Sub Main()
         Dim uc As New uCalc()
         
         uc.DefineFunction("AAA() As Double", AddressOf ItemCallback).Description = "Does this and that"
         uc.DefineFunction("BBB(x, y, z) As String", AddressOf ItemCallback).Description = "Does something else"
         uc.DefineOperator("{x} CCC {y} As Int32", 0, Associativity.LeftToRight, AddressOf ItemCallback)
         
         uc.EvalStr("AAA()")
         uc.EvalStr("BBB(9, 8, 7)")
         uc.EvalStr("5 CCC 4")
         
      End Sub
   End Module
				
			
Name: aaa
Data type: double
Param count: 0
Procedure type: Function
Function: AAA() As Double
Does this and that
---
Name: bbb
Data type: string
Param count: 3
Procedure type: Function
Function: BBB(x, y, z) As String
Does something else
---
Name: ccc
Data type: int
Param count: 2
Procedure type: Operator
Operator: {x} CCC {y} As Int32

---
Setting and retrieving a description for a single variable Item.
				
					using uCalcSoftware;

var uc = new uCalc();
var myVar = uc.DefineVariable("x = 10");
myVar.Description = "This is a test variable";

Console.WriteLine($"Name: {myVar.Name}");
Console.WriteLine($"Description: {myVar.Description}");
				
			
Name: x
Description: This is a test variable
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto myVar = uc.DefineVariable("x = 10");
   myVar.Description("This is a test variable");

   cout << "Name: " << myVar.Name() << endl;
   cout << "Description: " << myVar.Description() << endl;
}
				
			
Name: x
Description: This is a test variable
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim myVar = uc.DefineVariable("x = 10")
      myVar.Description = "This is a test variable"
      
      Console.WriteLine($"Name: {myVar.Name}")
      Console.WriteLine($"Description: {myVar.Description}")
   End Sub
End Module
				
			
Name: x
Description: This is a test variable
Previous
Next