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.

Rules

Product: 

Class: 

Remarks

In uCalc, a Rule is the compiled object that binds a specific Pattern to an action (such as a replacement string or a callback function).

When you call definition methods like FromTo() or Pattern(), the Transformer creates a Rule object internally. Capturing this object allows you to manipulate the rule's behavior dynamically at runtime.

Note: The properties and methods listed below are a sample of the most common functionality. For a complete list, browse the subtopics under uCalc -> Rules.

Core Properties:

  • Active(bool): Enables or disables the rule. Setting this to False effectively removes the rule from consideration without deleting it.
  • Name(): (Read-Only) Returns the identifier of the rule.
  • Description(text): Gets or sets a descriptive string. This is useful for storing metadata or comments associated with the rule.

Configuration Methods:These methods allow you to override global transformer settings for this specific rule.

  • CaseSensitive(bool): Determines if text matching is case-sensitive (e.g., Apple vs apple).
  • WhitespaceSensitive(bool): Determines if spaces are treated as tokens or ignored.
  • BracketSensitive(bool): Determines if brackets () [] {} enforce nesting logic.
  • QuoteSensitive(bool): Determines if quotes are respected as string delimiters.
  • RewindOnChange(bool): Determines whether the parser should "rewind" and re-scan the text after a replacement occurs. This is useful for recursive patterns or cascading replacements.

Advanced Methods:

  • LocalTransformer(): Returns a Transformer object restricted to the scope of the match found by this rule. This allows you to "zoom in" and perform secondary searches only within the text matched by this rule.
  • Release(): Manually destroys the rule object and frees resources.

Comparative Analysis: Why uCalc?

  • vs. Regex (Stateless):
    • Dynamics: A Regex is typically a static string. To make it case-insensitive, you often have to recompile it. In uCalc, Rule.CaseSensitive(false) is a runtime property toggle.
  • vs. Standard Iteration:
    • Rewind Logic: Implementing "Find, Replace, then Re-scan from the start" in standard string manipulation often requires while loops and index management. RewindOnChange(true) handles this complexity declaratively.

Examples

Searching for two different words in parallel.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

// Define concurrent patterns
t.FromTo("Mango", "[Fruit]");
t.FromTo("Car", "[Vehicle]");

Console.WriteLine(t.Transform("I have a Mango and a Car."));

				
			
I have a [Fruit] and a [Vehicle].
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   // Define concurrent patterns
   t.FromTo("Mango", "[Fruit]");
   t.FromTo("Car", "[Vehicle]");

   cout << t.Transform("I have a Mango and a Car.") << endl;

}
				
			
I have a [Fruit] and a [Vehicle].
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// Define concurrent patterns
      t.FromTo("Mango", "[Fruit]")
      t.FromTo("Car", "[Vehicle]")
      
      Console.WriteLine(t.Transform("I have a Mango and a Car."))
      
   End Sub
End Module
				
			
I have a [Fruit] and a [Vehicle].
RewindOnChange
				
					using uCalcSoftware;

var uc = new uCalc();
var ExprT = uc.ExpressionTransformer;  // Transformer used for Eval() and Evaluate()

ExprT.DefaultRuleSet.RewindOnChange = true;

ExprT.FromTo("AddUp({x})", "{x}");
ExprT.FromTo("AddUp({x}, {y})", "({x} + AddUp({y}))");

ExprT.FromTo("ArgCount({x})", "1");
ExprT.FromTo("ArgCount({x}, {y})", "(1 + ArgCount({y}))");

ExprT.FromTo("Average({x}, {y})", "AddUp({x}, {y}) / ArgCount({x}, {y})");

var Expression = "Average(1, 2, 3, 4)";
Console.WriteLine($"Input: {Expression}");
Console.WriteLine($"Transform: {ExprT.Transform(Expression)}");
Console.WriteLine($"Eval: {uc.Eval(Expression)}");
				
			
Input: Average(1, 2, 3, 4)
Transform: (1 + (2 + (3 + 4))) / (1 + (1 + (1 + 1)))
Eval: 2.5
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto ExprT = uc.ExpressionTransformer();  // Transformer used for Eval() and Evaluate()

   ExprT.DefaultRuleSet().RewindOnChange(true);

   ExprT.FromTo("AddUp({x})", "{x}");
   ExprT.FromTo("AddUp({x}, {y})", "({x} + AddUp({y}))");

   ExprT.FromTo("ArgCount({x})", "1");
   ExprT.FromTo("ArgCount({x}, {y})", "(1 + ArgCount({y}))");

   ExprT.FromTo("Average({x}, {y})", "AddUp({x}, {y}) / ArgCount({x}, {y})");

   auto Expression = "Average(1, 2, 3, 4)";
   cout << "Input: " << Expression << endl;
   cout << "Transform: " << ExprT.Transform(Expression) << endl;
   cout << "Eval: " << uc.Eval(Expression) << endl;
}
				
			
Input: Average(1, 2, 3, 4)
Transform: (1 + (2 + (3 + 4))) / (1 + (1 + (1 + 1)))
Eval: 2.5
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim ExprT = uc.ExpressionTransformer  '// Transformer used for Eval() and Evaluate()
      
      ExprT.DefaultRuleSet.RewindOnChange = true
      
      ExprT.FromTo("AddUp({x})", "{x}")
      ExprT.FromTo("AddUp({x}, {y})", "({x} + AddUp({y}))")
      
      ExprT.FromTo("ArgCount({x})", "1")
      ExprT.FromTo("ArgCount({x}, {y})", "(1 + ArgCount({y}))")
      
      ExprT.FromTo("Average({x}, {y})", "AddUp({x}, {y}) / ArgCount({x}, {y})")
      
      Dim Expression = "Average(1, 2, 3, 4)"
      Console.WriteLine($"Input: {Expression}")
      Console.WriteLine($"Transform: {ExprT.Transform(Expression)}")
      Console.WriteLine($"Eval: {uc.Eval(Expression)}")
   End Sub
End Module
				
			
Input: Average(1, 2, 3, 4)
Transform: (1 + (2 + (3 + 4))) / (1 + (1 + (1 + 1)))
Eval: 2.5
Toggling a rule on and off.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var r = t.FromTo("Hello", "Hi");

// Disable
r.Active = false;
Console.WriteLine(t.Transform("Hello").Text); // Output: Hello (No change)

// Enable
r.Active = true;
Console.WriteLine(t.Transform("Hello").Text); // Output: Hi
				
			
Hello
Hi
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto r = t.FromTo("Hello", "Hi");

   // Disable
   r.Active(false);
   cout << t.Transform("Hello").Text() << endl; // Output: Hello (No change)

   // Enable
   r.Active(true);
   cout << t.Transform("Hello").Text() << endl; // Output: Hi
}
				
			
Hello
Hi
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim r = t.FromTo("Hello", "Hi")
      
      '// Disable
      r.Active = false
      Console.WriteLine(t.Transform("Hello").Text) '// Output: Hello (No change)
      
      '// Enable
      r.Active = true
      Console.WriteLine(t.Transform("Hello").Text) '// Output: Hi
   End Sub
End Module
				
			
Hello
Hi
Previous
Next