uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

Immediate Transform %

Product: 

Class: 

Remarks

Immediate Transform

Shortcut: %Associated Method: uCalc.Rule.ImmediateTransform(bool)

Description: A postfix modifier that instructs the engine to immediately transform any nested matches found within the captured text before moving on to the next part of the transformation.

By default, uCalc is structurally aware during a variable capture. If a variable {v} is moving through text and encounters a sequence that matches another active pattern, it respects that pattern's boundaries (treating it as an atomic unit), but it does not perform any transformative actions on that inner match. The inner text remains in its original form within the captured variable.

The Immediate Transform (%) postfix is used to force uCalc to apply all relevant rules to that inner content right away.

Default vs. Transform Behavior

  • Default: The engine identifies nested patterns so it doesn't "cross" them, but it passes over them without changing their text. The variable receives the original source content.
  • Immediate Transform (%): The engine identifies the nested patterns and executes their replacements immediately. The variable receives the "transformed" version of the text.

Purpose: Pre-Processing for Evaluation

This modifier is essential when the captured text is intended to be used as input for an evaluator directive like {@Eval}. If the captured text contains keywords or shorthand that need to be expanded into numbers or valid formulas before the math engine sees them, the % modifier ensures those expansions happen first.

Examples

1. Succinct (Immediate vs. Deferred Transformation)

Comparing how a nested rule to change "old" to "new" affects a variable.

New(uCalc::Transformer, t)t.FromTo("old", "new") // Nested rule// Standard: 'val' contains the original text "old"t.FromTo("standard: {val}", "RESULT:{val}")// Immediate: 'val' contains the updated text "new"t.FromTo("immediate: {val%}", "RESULT:{val}")wl(t.Transform("standard: old"))  // Output: RESULT:oldwl(t.Transform("immediate: old")) // Output: RESULT:new

2. Practical (Nested Expression Cleanup)

Using % to ensure internal variables are resolved within a captured block before the block is wrapped in a tag.

New(uCalc::Transformer, t)t.FromTo("x", "10")t.FromTo("y", "20")// Capture the content inside brackets and update x and y immediatelyt.FromTo("calc({expr%})", "COMPUTE:[{expr}]")wl(t.Transform("calc(x + y)"))

[Expected Output]COMPUTE:[10 + 20]

3. Internal Test (Evaluation Integrity)

Demonstrating that % is necessary when a captured string is passed to {@Eval} and contains tokens that need to be transformed into numeric literals first.

New(uCalc::Transformer, t)t.FromTo("PI_CONST", "3.14159")// Without %, {v} would contain the string "PI_CONST" which Eval might not recognize.// With %, {v} contains "3.14159".t.FromTo("solve: {v%}", "Result: {@@Eval: v}")wl(t.Transform("solve: PI_CONST"))

[Expected Output]Result: 3.14159

Strategy & Critique

  • The "Now vs. Later" Choice: Most transformations in uCalc are designed to be safe and structural (Default). % is the tool you use when you need "active" content that must be fully baked before the current rule finishes.
  • Counterpart to Verbatim: While Verbatim Capture (~) (Topic 784) tells the engine to ignore boundaries entirely, Immediate Transform (%) tells the engine to respect the boundaries and act on them immediately.
  • Naming: The method ImmediateTransform() is a suggested name that clearly contrasts with the default deferred-transformation behavior of the engine.
  • See Also: Refer to Topic 784 (Verbatim Capture) for the "Black Box" approach to nested content.

Examples

TransformArg directive
				
					using uCalcSoftware;

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

t.FromTo("abc", "changed to xyz");
t.FromTo("Quote1({arg})", "'{arg}'");
t.FromTo("Quote2({arg%})", "'{arg}'");

Console.WriteLine(t.Transform("Quote1(abc), Quote2(abc)"));

				
			
'abc', 'changed to xyz'
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

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

   t.FromTo("abc", "changed to xyz");
   t.FromTo("Quote1({arg})", "'{arg}'");
   t.FromTo("Quote2({arg%})", "'{arg}'");

   cout << t.Transform("Quote1(abc), Quote2(abc)") << endl;

}
				
			
'abc', 'changed to xyz'
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("abc", "changed to xyz")
      t.FromTo("Quote1({arg})", "'{arg}'")
      t.FromTo("Quote2({arg%})", "'{arg}'")
      
      Console.WriteLine(t.Transform("Quote1(abc), Quote2(abc)"))
      
   End Sub
End Module
				
			
'abc', 'changed to xyz'
Previous
Next