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: 

Transformer Library

Class: 

Transformer

Gets or sets a user-defined text description for the Transformer instance, useful for identifying or documenting different transformation configurations.

Remarks

🏷️ Attaching Metadata to Transformers

The Description property provides a way to attach an arbitrary string of metadata to a Transformer instance. This is invaluable for debugging complex transformation pipelines, creating self-documenting configurations, and identifying specific transformers at runtime.

⚙️ Getter and Setter Behavior

This property functions as both a getter and a setter:

  • Getter: When called with no arguments, myTransformer.Description returns the current description of the transformer. If no description has been set, it returns an empty string.

  • Setter: myTransformer.Description = "your text" sets the transformer's description. SetDescription("your text") as a method supports a fluent interface, meaning it returns the Transformer object itself, allowing you to chain method calls.

🎯 Core Use Cases

Attaching a description is a best practice for managing multiple or complex transformer instances.

  • Debugging: When an application uses multiple transformers for different purposes (e.g., one for sanitizing input, another for formatting output), you can print the Description of the active transformer to immediately understand which set of lexical rules is being applied.

  • Self-Documentation: Store a human-readable note directly on the transformer to explain its role, such as "Markdown to HTML Converter" or "SQL Injection Sanitizer". This keeps the documentation tightly coupled with the object it describes.

  • Runtime Identification: Use descriptions to programmatically identify specific transformer configurations. For example, you could iterate through a collection of transformers and select one based on its description.

💡 Why uCalc? (Comparative Analysis)

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

  • vs. Code Comments: Standard code comments are static and cannot be accessed by the program at runtime. A Transformer's description is dynamic data that can be queried, displayed, or used in application logic.

  • vs. External Dictionaries: Managing an external dictionary (e.g., Dictionary<Transformer, string>) to map transformers to their descriptions is cumbersome. It requires manual synchronization, and if a Transformer object is released, the dictionary entry can become a memory leak. uCalc's integrated approach is safer, cleaner, and more efficient.

The Description property is a consistent feature across many uCalc objects, including Rule, Item, and the main uCalc instance, providing a unified system for metadata management.

Examples

A basic example demonstrating how to set and get a description for a Transformer.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.Description = "My First Transformer";
Console.WriteLine($"Transformer Description: {t.Description}");
				
			
Transformer Description: My First Transformer
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.Description("My First Transformer");
   cout << "Transformer Description: " << t.Description() << endl;
}
				
			
Transformer Description: My First Transformer
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.Description = "My First Transformer"
      Console.WriteLine($"Transformer Description: {t.Description}")
   End Sub
End Module
				
			
Transformer Description: My First Transformer
Uses descriptions to differentiate between two transformers used for different environments, such as a verbose 'debug' transformer and a silent 'production' one.
				
					using uCalcSoftware;

var uc = new uCalc();
var text = "The value is x";

// 1. Setup Debug Transformer
var t_debug = new uCalc.Transformer();
t_debug.Description = "Debug Transformer (Verbose)";
t_debug.FromTo("x", "100 // debug value");

// 2. Setup Production Transformer
var t_prod = new uCalc.Transformer();
t_prod.Description = "Production Transformer (Clean)";
t_prod.FromTo("x", "100");

Console.WriteLine($"{t_debug.Description}: {t_debug.Transform(text)}");
Console.WriteLine($"{t_prod.Description}: {t_prod.Transform(text)}");
				
			
Debug Transformer (Verbose): The value is 100 // debug value
Production Transformer (Clean): The value is 100
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto text = "The value is x";

   // 1. Setup Debug Transformer
   uCalc::Transformer t_debug;
   t_debug.Description("Debug Transformer (Verbose)");
   t_debug.FromTo("x", "100 // debug value");

   // 2. Setup Production Transformer
   uCalc::Transformer t_prod;
   t_prod.Description("Production Transformer (Clean)");
   t_prod.FromTo("x", "100");

   cout << t_debug.Description() << ": " << t_debug.Transform(text) << endl;
   cout << t_prod.Description() << ": " << t_prod.Transform(text) << endl;
}
				
			
Debug Transformer (Verbose): The value is 100 // debug value
Production Transformer (Clean): The value is 100
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim text = "The value is x"
      
      '// 1. Setup Debug Transformer
      Dim t_debug As New uCalc.Transformer()
      t_debug.Description = "Debug Transformer (Verbose)"
      t_debug.FromTo("x", "100 // debug value")
      
      '// 2. Setup Production Transformer
      Dim t_prod As New uCalc.Transformer()
      t_prod.Description = "Production Transformer (Clean)"
      t_prod.FromTo("x", "100")
      
      Console.WriteLine($"{t_debug.Description}: {t_debug.Transform(text)}")
      Console.WriteLine($"{t_prod.Description}: {t_prod.Transform(text)}")
   End Sub
End Module
				
			
Debug Transformer (Verbose): The value is 100 // debug value
Production Transformer (Clean): The value is 100
Internal Test: Verifies that the description property is correctly copied when a Transformer is cloned.
				
					using uCalcSoftware;

var uc = new uCalc();
var t_original = new uCalc.Transformer();
t_original.Description = "Original Transformer";

// Clone the transformer
var t_cloned = t_original.Clone();

Console.WriteLine($"Original Description: {t_original.Description}");
Console.WriteLine($"Cloned Description:   {t_cloned.Description}");

// Modify the clone's description to ensure they are independent
t_cloned.Description = "Cloned and Modified";

Console.WriteLine($"Original after mod: {t_original.Description}");
Console.WriteLine($"Cloned after mod:   {t_cloned.Description}");
				
			
Original Description: Original Transformer
Cloned Description:   Original Transformer
Original after mod: Original Transformer
Cloned after mod:   Cloned and Modified
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t_original;
   t_original.Description("Original Transformer");

   // Clone the transformer
   auto t_cloned = t_original.Clone();

   cout << "Original Description: " << t_original.Description() << endl;
   cout << "Cloned Description:   " << t_cloned.Description() << endl;

   // Modify the clone's description to ensure they are independent
   t_cloned.Description("Cloned and Modified");

   cout << "Original after mod: " << t_original.Description() << endl;
   cout << "Cloned after mod:   " << t_cloned.Description() << endl;
}
				
			
Original Description: Original Transformer
Cloned Description:   Original Transformer
Original after mod: Original Transformer
Cloned after mod:   Cloned and Modified
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t_original As New uCalc.Transformer()
      t_original.Description = "Original Transformer"
      
      '// Clone the transformer
      Dim t_cloned = t_original.Clone()
      
      Console.WriteLine($"Original Description: {t_original.Description}")
      Console.WriteLine($"Cloned Description:   {t_cloned.Description}")
      
      '// Modify the clone's description to ensure they are independent
      t_cloned.Description = "Cloned and Modified"
      
      Console.WriteLine($"Original after mod: {t_original.Description}")
      Console.WriteLine($"Cloned after mod:   {t_cloned.Description}")
   End Sub
End Module
				
			
Original Description: Original Transformer
Cloned Description:   Original Transformer
Original after mod: Original Transformer
Cloned after mod:   Cloned and Modified
ParentTransformer
				
					using uCalcSoftware;

var uc = new uCalc();
var Txt = "Test a b c. x y z";

var FirstTransform = uc.NewTransformer().SetText(Txt).SetDescription("First Transformer");
var aaa = FirstTransform.FromTo("Test {etc}.", "[{etc}]");

var SecondTransform = uc.NewTransformer().SetDescription("Second Transformer");
var bbb = SecondTransform.FromTo("Test {etc}.", "({etc})");

Console.WriteLine(aaa.ParentTransformer.Description);
Console.WriteLine(FirstTransform.Transform().Text);
Console.WriteLine("");

Console.WriteLine(SecondTransform.Description);
Console.WriteLine(bbb.ParentTransformer.Transform(Txt).Text);
				
			
First Transformer
[a b c] x y z

Second Transformer
(a b c) x y z
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto Txt = "Test a b c. x y z";

   auto FirstTransform = uc.NewTransformer().SetText(Txt).SetDescription("First Transformer");
   auto aaa = FirstTransform.FromTo("Test {etc}.", "[{etc}]");

   auto SecondTransform = uc.NewTransformer().SetDescription("Second Transformer");
   auto bbb = SecondTransform.FromTo("Test {etc}.", "({etc})");

   cout << aaa.ParentTransformer().Description() << endl;
   cout << FirstTransform.Transform().Text() << endl;
   cout << "" << endl;

   cout << SecondTransform.Description() << endl;
   cout << bbb.ParentTransformer().Transform(Txt).Text() << endl;
}
				
			
First Transformer
[a b c] x y z

Second Transformer
(a b c) x y z
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim Txt = "Test a b c. x y z"
      
      Dim FirstTransform = uc.NewTransformer().SetText(Txt).SetDescription("First Transformer")
      Dim aaa = FirstTransform.FromTo("Test {etc}.", "[{etc}]")
      
      Dim SecondTransform = uc.NewTransformer().SetDescription("Second Transformer")
      Dim bbb = SecondTransform.FromTo("Test {etc}.", "({etc})")
      
      Console.WriteLine(aaa.ParentTransformer.Description)
      Console.WriteLine(FirstTransform.Transform().Text)
      Console.WriteLine("")
      
      Console.WriteLine(SecondTransform.Description)
      Console.WriteLine(bbb.ParentTransformer.Transform(Txt).Text)
   End Sub
End Module
				
			
First Transformer
[a b c] x y z

Second Transformer
(a b c) x y z
Pass()
				
					using uCalcSoftware;

var uc = new uCalc();
var FruitsXML =
"""

<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' />
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <Fruit CommonName='Mango' ScientificName='Mangifera indica' />
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' />
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' />
</Fruits>

""";

var t = uc.NewTransformer();
t.Text = FruitsXML;

var Pass1 = t.Pass();
var Pass2 = t.Pass();

Pass1.Description = "Pass A";
Pass1.FromTo("Fruits", "ListOfFruits");
Pass1.FromTo("<Fruit CommonName={@str:name} ScientificName={@str:sci_name} />", "<Fruit>{name}</Fruit>");

Pass2.Description = "Pass B";
Pass2.FromTo("{Fruit: Apple | Orange | Mango }", "{Fruit} *");
Pass2.FromTo("{Fruit: Banana | Grapes | Watermelon }", "{Fruit} **");

t.Transform();
Console.WriteLine("All passes");
Console.WriteLine("----------");
Console.WriteLine(t.Text);

Console.WriteLine(t.Pass(0).Description);
Console.WriteLine(t.Pass(1).Description);
Console.WriteLine($"Pass count: {t.PassCount()}");
Console.WriteLine("");

t.Str(FruitsXML);
Pass2.Release();
t.Transform();
Console.WriteLine("Pass1 only (Pass2 released)");
Console.WriteLine("---------------------------");
Console.WriteLine(t.Text);

				
			
All passes
----------

<ListOfFruits>
  <Fruit>Apple *</Fruit>
  <Fruit>Banana **</Fruit>
  <Fruit>Orange *</Fruit>
  <Fruit>Grapes **</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango *</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon **</Fruit>
</ListOfFruits>

Pass A
Pass B
Pass count: 2

Pass1 only (Pass2 released)
---------------------------

<ListOfFruits>
  <Fruit>Apple</Fruit>
  <Fruit>Banana</Fruit>
  <Fruit>Orange</Fruit>
  <Fruit>Grapes</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon</Fruit>
</ListOfFruits>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto FruitsXML =
   R"(
<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' />
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <Fruit CommonName='Mango' ScientificName='Mangifera indica' />
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' />
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' />
</Fruits>
)";

   auto t = uc.NewTransformer();
   t.Text(FruitsXML);

   auto Pass1 = t.Pass();
   auto Pass2 = t.Pass();

   Pass1.Description("Pass A");
   Pass1.FromTo("Fruits", "ListOfFruits");
   Pass1.FromTo("<Fruit CommonName={@str:name} ScientificName={@str:sci_name} />", "<Fruit>{name}</Fruit>");

   Pass2.Description("Pass B");
   Pass2.FromTo("{Fruit: Apple | Orange | Mango }", "{Fruit} *");
   Pass2.FromTo("{Fruit: Banana | Grapes | Watermelon }", "{Fruit} **");

   t.Transform();
   cout << "All passes" << endl;
   cout << "----------" << endl;
   cout << t.Text() << endl;

   cout << t.Pass(0).Description() << endl;
   cout << t.Pass(1).Description() << endl;
   cout << "Pass count: " << t.PassCount() << endl;
   cout << "" << endl;

   t.Str(FruitsXML);
   Pass2.Release();
   t.Transform();
   cout << "Pass1 only (Pass2 released)" << endl;
   cout << "---------------------------" << endl;
   cout << t.Text() << endl;

}
				
			
All passes
----------

<ListOfFruits>
  <Fruit>Apple *</Fruit>
  <Fruit>Banana **</Fruit>
  <Fruit>Orange *</Fruit>
  <Fruit>Grapes **</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango *</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon **</Fruit>
</ListOfFruits>

Pass A
Pass B
Pass count: 2

Pass1 only (Pass2 released)
---------------------------

<ListOfFruits>
  <Fruit>Apple</Fruit>
  <Fruit>Banana</Fruit>
  <Fruit>Orange</Fruit>
  <Fruit>Grapes</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon</Fruit>
</ListOfFruits>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim FruitsXML =
      "
<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' />
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <Fruit CommonName='Mango' ScientificName='Mangifera indica' />
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' />
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' />
</Fruits>
"
      
      Dim t = uc.NewTransformer()
      t.Text = FruitsXML
      
      Dim Pass1 = t.Pass()
      Dim Pass2 = t.Pass()
      
      Pass1.Description = "Pass A"
      Pass1.FromTo("Fruits", "ListOfFruits")
      Pass1.FromTo("<Fruit CommonName={@str:name} ScientificName={@str:sci_name} />", "<Fruit>{name}</Fruit>")
      
      Pass2.Description = "Pass B"
      Pass2.FromTo("{Fruit: Apple | Orange | Mango }", "{Fruit} *")
      Pass2.FromTo("{Fruit: Banana | Grapes | Watermelon }", "{Fruit} **")
      
      t.Transform()
      Console.WriteLine("All passes")
      Console.WriteLine("----------")
      Console.WriteLine(t.Text)
      
      Console.WriteLine(t.Pass(0).Description)
      Console.WriteLine(t.Pass(1).Description)
      Console.WriteLine($"Pass count: {t.PassCount()}")
      Console.WriteLine("")
      
      t.Str(FruitsXML)
      Pass2.Release()
      t.Transform()
      Console.WriteLine("Pass1 only (Pass2 released)")
      Console.WriteLine("---------------------------")
      Console.WriteLine(t.Text)
      
   End Sub
End Module
				
			
All passes
----------

<ListOfFruits>
  <Fruit>Apple *</Fruit>
  <Fruit>Banana **</Fruit>
  <Fruit>Orange *</Fruit>
  <Fruit>Grapes **</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango *</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon **</Fruit>
</ListOfFruits>

Pass A
Pass B
Pass count: 2

Pass1 only (Pass2 released)
---------------------------

<ListOfFruits>
  <Fruit>Apple</Fruit>
  <Fruit>Banana</Fruit>
  <Fruit>Orange</Fruit>
  <Fruit>Grapes</Fruit>
  <Fruit>Strawberry</Fruit>
  <Fruit>Pineapple</Fruit>
  <Fruit>Mango</Fruit>
  <Fruit>Blueberry</Fruit>
  <Fruit>Rambutan</Fruit>
  <Fruit>Salak (Snake Fruit)</Fruit>
  <Fruit>Jabuticaba</Fruit>
  <Fruit>Watermelon</Fruit>
</ListOfFruits>
Previous
Next