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: 

Rule

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

Remarks

The Description property provides a way to attach arbitrary string metadata to a Transformer Rule. This is invaluable for debugging, creating self-documenting configurations, and identifying which rule generated a specific Match at runtime.

⚙️ Getter and Setter Behavior

This property functions as both a getter and a setter:

  • Getter: When called with no arguments, myRule.Description returns the current description of the rule. If no description has been set, it returns an empty string.
  • Setter: When called with a string argument, myRule.Description = "your text" sets the rule's description. The setter supports a fluent interface, meaning it returns the Rule object itself, allowing you to chain method calls.

🎯 Core Use Cases

  • Debugging: When iterating through a list of matches, you can retrieve the rule for each match and print its description. This tells you exactly why a segment of text was matched, which is far more direct than trying to interpret a complex pattern string.
  • Self-Documentation: Store human-readable notes directly on the rule to explain its purpose or logic. This keeps the documentation tightly coupled with the code it describes.
  • Runtime Identification: Use descriptions to tag and identify specific rules for programmatic processing, such as enabling or disabling groups of rules based on their metadata.

💡 Comparative Analysis

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

  • External Dictionaries: Managing a Dictionary<Rule, string> is cumbersome. It requires manual synchronization, and if a Rule is released, the dictionary entry can become a memory leak.
  • Wrapper Classes: Creating a custom class just to add a description field adds significant boilerplate code.

uCalc's 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

A succinct example demonstrating how to set a description on a rule and then retrieve it.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var myRule = t.FromTo("Hello", "Hi");
myRule.Description = "Simple greeting replacement";

Console.WriteLine($"Rule Pattern: {myRule.Pattern}");
Console.Write("Rule Description: "); Console.Write(myRule.Description);
				
			
Rule Pattern: Hello
Rule Description: Simple greeting replacement
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto myRule = t.FromTo("Hello", "Hi");
   myRule.Description("Simple greeting replacement");

   cout << "Rule Pattern: " << myRule.Pattern() << endl;
   cout << "Rule Description: " << myRule.Description();
}
				
			
Rule Pattern: Hello
Rule Description: Simple greeting replacement
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim myRule = t.FromTo("Hello", "Hi")
      myRule.Description = "Simple greeting replacement"
      
      Console.WriteLine($"Rule Pattern: {myRule.Pattern}")
      Console.Write("Rule Description: ")
      Console.Write(myRule.Description)
   End Sub
End Module
				
			
Rule Pattern: Hello
Rule Description: Simple greeting replacement
How to assign and retrieve descriptions for specific transformation patterns using SetDescription().
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>");

var AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag");
var BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag");
var H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag");
t.Find();

foreach(var match in t.Matches) {
   Console.WriteLine(match.Text + "   Description: " + match.Rule.Description);
}
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>");

   auto AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag");
   auto BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag");
   auto H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag");
   t.Find();

   for(auto match : t.Matches()) {
      cout << match.Text() + "   Description: " + match.Rule().Description() << endl;
   }
}
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b><p>My paragraph</p>")
      
      Dim AnyOtherTag = t.Pattern("<{tag}>{text}</{tag}>").SetDescription("other kind of tag")
      Dim BoldTag = t.Pattern("<b>{text}</b>").SetDescription("bold tag")
      Dim H3Tag = t.Pattern("<h3>{text}</h3>").SetDescription("h3 tag")
      t.Find()
      
      For Each match In t.Matches
         Console.WriteLine(match.Text + "   Description: " + match.Rule.Description)
      Next
   End Sub
End Module
				
			
<h3>Title</h3>   Description: h3 tag
<b>Bold statement</b>   Description: bold tag
<h3>Title B</h3>   Description: h3 tag
<b>Other text</b>   Description: bold tag
<p>My paragraph</p>   Description: other kind of tag
Previous
Next