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.

Pass

Method

Product: 

Transformer Library

Class: 

Transformer

Creates or retrieves a sequential transformation stage (a pass), enabling multi-step text processing pipelines.

Syntax

Pass(int, bool)

Parameters

index
int
(Default = -1)
The zero-based index of the pass to select or create. If the default value of -1 is used, a new pass is created at the end of the sequence.
share
bool
(Default = false)
If true, the pass inherits a copy of the rules from the main transformer. If false (default), the pass starts with a clean, empty rule set.

Return

Transformer

A Transformer object representing the specified pass, which can be configured with its own independent set of rules.

Remarks

The Pass method is the entry point for creating multi-stage transformation pipelines. It allows you to break down a complex transformation into a sequence of simpler, independent steps. Each pass is its own Transformer object with its own set of rules.

How It Works: A Sequential Pipeline

When Transform() is called on the main Transformer, the input text is processed sequentially through each defined pass:

  1. The text is processed by Pass 0.
  2. The output of Pass 0 becomes the input for Pass 1.
  3. This continues until the final pass is complete.

This architecture is ideal for separating distinct logical stages, such as an initial data cleanup pass, followed by a data extraction pass, and finally a formatting pass.

Creating and Accessing Passes

Passes are identified by a zero-based index.

  • Create a new pass: Call Pass() with no arguments or -1. This appends a new pass to the end of the sequence.
  • Access an existing pass: Call Pass(n) to retrieve the Transformer object for the nth pass.

The share Parameter: Rule Inheritance

The share parameter controls whether a new pass inherits rules from the main (root) transformer.

  • share = false (Default): The pass is created with a clean slate. It has its own isolated set of rules and does not inherit any from the parent.
  • share = true: The pass is created with a copy of all rules currently defined on the main transformer. You can then add more rules to the pass. Changes to the pass's rules will not affect the main transformer.

💡 Why uCalc? (Comparative Analysis)

Without the Pass system, you would need to manually create and manage a pipeline of separate Transformer objects, which is verbose and error-prone:

Manual Approach:

var t1 = new uCalc.Transformer();var t2 = new uCalc.Transformer();// ... define rules for t1 and t2 ...string result1 = t1.Transform("input");string finalResult = t2.Transform(result1);

uCalc Pass Approach:

var t = new uCalc.Transformer();var pass1 = t.Pass();var pass2 = t.Pass();// ... define rules for pass1 and pass2 ...string finalResult = t.Transform("input");

uCalc's Pass method encapsulates the entire pipeline into a single object, simplifying the logic and making the transformation sequence easier to manage and understand.

Examples

Succinct: A simple two-pass transformation where the output of the first pass becomes the input for the second.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.Text = "A";

// Pass 0 will change 'A' to 'B'
var pass0 = t.Pass(0);
pass0.FromTo("A", "B");

// Pass 1 will receive 'B' and change it to 'C'
var pass1 = t.Pass(1);
pass1.FromTo("B", "C");

t.Transform();
Console.WriteLine(t); // The final output is 'C'
				
			
C
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.Text("A");

   // Pass 0 will change 'A' to 'B'
   auto pass0 = t.Pass(0);
   pass0.FromTo("A", "B");

   // Pass 1 will receive 'B' and change it to 'C'
   auto pass1 = t.Pass(1);
   pass1.FromTo("B", "C");

   t.Transform();
   cout << t << endl; // The final output is 'C'
}
				
			
C
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.Text = "A"
      
      '// Pass 0 will change 'A' to 'B'
      Dim pass0 = t.Pass(0)
      pass0.FromTo("A", "B")
      
      '// Pass 1 will receive 'B' and change it to 'C'
      Dim pass1 = t.Pass(1)
      pass1.FromTo("B", "C")
      
      t.Transform()
      Console.WriteLine(t) '// The final output is 'C'
   End Sub
End Module
				
			
C
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