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: 

Tokens

Gets or sets a user-defined text description for a token collection, useful for documenting and identifying different lexical configurations.

Remarks

🏷️ Attaching Metadata to Token Sets

The Description property allows you to attach arbitrary string metadata to a Tokens object. This is an invaluable feature for debugging complex transformations, creating self-documenting code, and identifying specific lexical configurations at runtime.

⚙️ Getter and Setter Behavior

This property functions as both a getter and a setter:

  • Getter: Retrieves the current description string. If no description has been set, it returns an empty string.

  • Setter: myTokens.Description = "new description" assigns the new metadata. As a method, SetDescription() supports a fluent interface, returning the Tokens object itself to allow for method chaining.

🎯 Core Use Cases

Attaching a description is a best practice for managing multiple or complex token sets.

  • Debugging: When an application uses multiple Transformer instances with different token configurations, you can print the Description of the active Tokens object to immediately understand which set of lexical rules is being applied.

  • Self-Documentation: Store a human-readable note directly on the token set to explain its purpose, such as "Strict JSON Tokenizer" vs. "Flexible Config File Tokenizer". This keeps the documentation tightly coupled with the object it describes.

  • Runtime Identification: Use descriptions to programmatically identify specific token configurations. For example, you could iterate through a collection of transformers and activate only those whose token sets have a description matching "Version 2.0 Syntax".

💡 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 Tokens description is dynamic data that can be queried, displayed, or used in application logic.

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

Examples

Demonstrates the basic getter and setter functionality of the Description property.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
var tokens = t.Tokens;

// Set a description
tokens.Description = "Default token set for general purpose parsing.";

// Get the description
Console.WriteLine(tokens.Description);
				
			
Default token set for general purpose parsing.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   auto tokens = t.Tokens();

   // Set a description
   tokens.Description("Default token set for general purpose parsing.");

   // Get the description
   cout << tokens.Description() << endl;
}
				
			
Default token set for general purpose parsing.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      Dim tokens = t.Tokens
      
      '// Set a description
      tokens.Description = "Default token set for general purpose parsing."
      
      '// Get the description
      Console.WriteLine(tokens.Description)
   End Sub
End Module
				
			
Default token set for general purpose parsing.
Uses descriptions to identify and differentiate between two separate token configurations at runtime.
				
					using uCalcSoftware;

var uc = new uCalc();
// Create two transformers with different token configurations
var strict_t = new uCalc.Transformer();
strict_t.Tokens.Description = "Strict Mode: only 'is' as a whole word.";

var flexible_t = new uCalc.Transformer();
flexible_t.Tokens.Description = "Flexible Mode: matches 'is' inside other words.";
flexible_t.Tokens.Clear();
flexible_t.Tokens.Add("."); // Match by character

string text = "This island is nice.";

strict_t.FromTo("is", "[MATCH]");
flexible_t.FromTo("is", "[MATCH]");

Console.WriteLine(strict_t.Tokens.Description);
Console.WriteLine($"Result: {strict_t.Transform(text)}");
Console.WriteLine("");
Console.WriteLine(flexible_t.Tokens.Description);
Console.WriteLine($"Result: {flexible_t.Transform(text)}");
				
			
Strict Mode: only 'is' as a whole word.
Result: This island [MATCH] nice.

Flexible Mode: matches 'is' inside other words.
Result: Th[MATCH] [MATCH]land [MATCH] nice.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Create two transformers with different token configurations
   uCalc::Transformer strict_t;
   strict_t.Tokens().Description("Strict Mode: only 'is' as a whole word.");

   uCalc::Transformer flexible_t;
   flexible_t.Tokens().Description("Flexible Mode: matches 'is' inside other words.");
   flexible_t.Tokens().Clear();
   flexible_t.Tokens().Add("."); // Match by character

   string text = "This island is nice.";

   strict_t.FromTo("is", "[MATCH]");
   flexible_t.FromTo("is", "[MATCH]");

   cout << strict_t.Tokens().Description() << endl;
   cout << "Result: " << strict_t.Transform(text) << endl;
   cout << "" << endl;
   cout << flexible_t.Tokens().Description() << endl;
   cout << "Result: " << flexible_t.Transform(text) << endl;
}
				
			
Strict Mode: only 'is' as a whole word.
Result: This island [MATCH] nice.

Flexible Mode: matches 'is' inside other words.
Result: Th[MATCH] [MATCH]land [MATCH] nice.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Create two transformers with different token configurations
      Dim strict_t As New uCalc.Transformer()
      strict_t.Tokens.Description = "Strict Mode: only 'is' as a whole word."
      
      Dim flexible_t As New uCalc.Transformer()
      flexible_t.Tokens.Description = "Flexible Mode: matches 'is' inside other words."
      flexible_t.Tokens.Clear()
      flexible_t.Tokens.Add(".") '// Match by character
      
      Dim text As String = "This island is nice."
      
      strict_t.FromTo("is", "[MATCH]")
      flexible_t.FromTo("is", "[MATCH]")
      
      Console.WriteLine(strict_t.Tokens.Description)
      Console.WriteLine($"Result: {strict_t.Transform(text)}")
      Console.WriteLine("")
      Console.WriteLine(flexible_t.Tokens.Description)
      Console.WriteLine($"Result: {flexible_t.Transform(text)}")
   End Sub
End Module
				
			
Strict Mode: only 'is' as a whole word.
Result: This island [MATCH] nice.

Flexible Mode: matches 'is' inside other words.
Result: Th[MATCH] [MATCH]land [MATCH] nice.
Internal Test: Verifies that descriptions are copied when token sets are imported, but remain independent afterward.
				
					using uCalcSoftware;

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

// Create a new transformer and import tokens from t1
var t2 = new uCalc.Transformer();
t2.Tokens.Add(t1.Tokens);

Console.WriteLine($"t2's initial description (copied from t1): {t2.Tokens.Description}");

// Modify t2's description
t2.Tokens.Description = "Modified Description";

Console.WriteLine($"t2's new description: {t2.Tokens.Description}");
Console.WriteLine($"t1's description remains unchanged: {t1.Tokens.Description}");
				
			
t2's initial description (copied from t1): Original Description
t2's new description: Modified Description
t1's description remains unchanged: Original Description
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   // Create a new transformer and import tokens from t1
   uCalc::Transformer t2;
   t2.Tokens().Add(t1.Tokens());

   cout << "t2's initial description (copied from t1): " << t2.Tokens().Description() << endl;

   // Modify t2's description
   t2.Tokens().Description("Modified Description");

   cout << "t2's new description: " << t2.Tokens().Description() << endl;
   cout << "t1's description remains unchanged: " << t1.Tokens().Description() << endl;
}
				
			
t2's initial description (copied from t1): Original Description
t2's new description: Modified Description
t1's description remains unchanged: Original Description
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t1 As New uCalc.Transformer()
      t1.Tokens.Description = "Original Description"
      
      '// Create a new transformer and import tokens from t1
      Dim t2 As New uCalc.Transformer()
      t2.Tokens.Add(t1.Tokens)
      
      Console.WriteLine($"t2's initial description (copied from t1): {t2.Tokens.Description}")
      
      '// Modify t2's description
      t2.Tokens.Description = "Modified Description"
      
      Console.WriteLine($"t2's new description: {t2.Tokens.Description}")
      Console.WriteLine($"t1's description remains unchanged: {t1.Tokens.Description}")
   End Sub
End Module
				
			
t2's initial description (copied from t1): Original Description
t2's new description: Modified Description
t1's description remains unchanged: Original Description
Transformer: Matching by tokens vs match by character; also whitespace sensitivity
				
					using uCalcSoftware;

var uc = new uCalc();
// This examples shows the default match by
// token mode, as well as how to reconfigure
// it in order to do match by character
// along with a whitespace variation

var t = uc.NewTransformer();
var txt = "This is an island test, I said.";
t.FromTo("is", "<is>");

Console.WriteLine(t.Transform(txt));
Console.WriteLine("");

t.Tokens.Description = "Match by character";
t.Tokens.Add("."); // This overrides existing tokens
t.FromTo("is", "<is>");
Console.WriteLine(t.Tokens.Description);
Console.WriteLine(t.Transform(txt));
Console.WriteLine("");

// Note: whitespace sensitivity is off by default
// Whitespace token is re-introduced
// (after being overridden in the previous Token Add())
t.Tokens.Description = "By char + whitespace ignored";
t.Tokens.Add("[\\t\\v ]+", TokenType.Whitespace);
t.FromTo("is", "<{@Self}>");
Console.WriteLine(t.Tokens.Description);
Console.WriteLine(t.Transform(txt));
				
			
This <is> an island test, I said.

Match by character
Th<is> <is> an <is>land test, I said.

By char + whitespace ignored
Th<is> <is> an <is>land test, <I s>aid.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // This examples shows the default match by
   // token mode, as well as how to reconfigure
   // it in order to do match by character
   // along with a whitespace variation

   auto t = uc.NewTransformer();
   auto txt = "This is an island test, I said.";
   t.FromTo("is", "<is>");

   cout << t.Transform(txt) << endl;
   cout << "" << endl;

   t.Tokens().Description("Match by character");
   t.Tokens().Add("."); // This overrides existing tokens
   t.FromTo("is", "<is>");
   cout << t.Tokens().Description() << endl;
   cout << t.Transform(txt) << endl;
   cout << "" << endl;

   // Note: whitespace sensitivity is off by default
   // Whitespace token is re-introduced
   // (after being overridden in the previous Token Add())
   t.Tokens().Description("By char + whitespace ignored");
   t.Tokens().Add("[\\t\\v ]+", TokenType::Whitespace);
   t.FromTo("is", "<{@Self}>");
   cout << t.Tokens().Description() << endl;
   cout << t.Transform(txt) << endl;
}
				
			
This <is> an island test, I said.

Match by character
Th<is> <is> an <is>land test, I said.

By char + whitespace ignored
Th<is> <is> an <is>land test, <I s>aid.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// This examples shows the default match by
      '// token mode, as well as how to reconfigure
      '// it in order to do match by character
      '// along with a whitespace variation
      
      Dim t = uc.NewTransformer()
      Dim txt = "This is an island test, I said."
      t.FromTo("is", "<is>")
      
      Console.WriteLine(t.Transform(txt))
      Console.WriteLine("")
      
      t.Tokens.Description = "Match by character"
      t.Tokens.Add(".") '// This overrides existing tokens
      t.FromTo("is", "<is>")
      Console.WriteLine(t.Tokens.Description)
      Console.WriteLine(t.Transform(txt))
      Console.WriteLine("")
      
      '// Note: whitespace sensitivity is off by default
      '// Whitespace token is re-introduced
      '// (after being overridden in the previous Token Add())
      t.Tokens.Description = "By char + whitespace ignored"
      t.Tokens.Add("[\\t\\v ]+", TokenType.Whitespace)
      t.FromTo("is", "<{@Self}>")
      Console.WriteLine(t.Tokens.Description)
      Console.WriteLine(t.Transform(txt))
   End Sub
End Module
				
			
This <is> an island test, I said.

Match by character
Th<is> <is> an <is>land test, I said.

By char + whitespace ignored
Th<is> <is> an <is>land test, <I s>aid.
Previous
Next