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.

Alternation

Product: 

Class: 

Learn to match one of several alternative patterns using the '|' operator and create dynamic outputs with conditional replacements.

Remarks

🔀 Matching Alternatives (OR Logic)

In many text processing tasks, you need to find a pattern that could be one of several possibilities. For example, a status could be "OK", "Error", or "Pending". uCalc's Transformer handles this with the alternation operator: the vertical bar |.

This tutorial will guide you through using the | operator to create flexible, conditional patterns.

1. The Basics of Alternation

The core syntax is simple: enclose your choices within curly braces {}, separated by the | operator. The engine will match the first choice that allows the entire pattern to succeed.

// This pattern will match 'Status: OK', 'Status: Error', or 'Status: Pending'"Status: { OK | Error | Pending }"

This is far more readable and maintainable than writing three separate rules.

2. Capturing the Choice

To make alternation useful, you often need to know which of the alternatives was matched. You can do this by assigning a variable name to the group.

// Captures 'OK', 'Error', or 'Pending' into the variable {status_val}"Status: {status_val: OK | Error | Pending }"

You can then use {status_val} in your replacement string to reference the specific text that was matched.

3. 💎 Conditional Replacements

This is where alternation becomes truly powerful. You can create different outputs based on which variable was captured within an alternation. This is done using special replacement syntax:

  • {var: ...}: The content after the colon is inserted only if {var} captured a value.
  • {!var: ...}: The content after the colon is inserted only if {var} is empty (did not capture a value).

This is perfect for normalizing data from different formats into a single, consistent output, as shown in the practical example below.

4. ⚠️ Ordering Matters: The Precedence Pitfall

The engine evaluates alternatives from left to right and stops at the first successful match that allows the rest of the pattern to succeed. This can create a common trap if your alternatives overlap.

Consider matching "Apple Pie" and "Apple".

  • Wrong Order: { Apple | Apple Pie }. When given the text "An Apple Pie", the engine will match "Apple" first and stop, because it's a valid match. It will never get a chance to test for "Apple Pie".
  • Correct Order: { Apple Pie | Apple }. You must always place the longest and most specific alternatives first. This ensures they are tested before any shorter, partial matches.

See the internal test example for a clear demonstration of this pitfall.

5. Why uCalc? (Comparative Analysis)

  • vs. Regex ((A|B|C)):
    • Readability: uCalc's syntax { Red | Blue } is cleaner and doesn't require the often-confusing parentheses-grouping of Regex (Red|Blue).
    • Token Awareness: A Regex alternation like (in|to) can match inside words like "bin" or "top" unless you explicitly add word boundaries (\b). uCalc defaults to whole-token matching, preventing these common false positives automatically.

Examples

A succinct example demonstrating how to match one of several possible status keywords.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.FromTo("Status: { OK | Error | Pending }", "Found Valid Status");

Console.WriteLine(t.Transform("Status: OK"));
Console.WriteLine(t.Transform("Status: Error"));
Console.WriteLine(t.Transform("Status: Fail"));
				
			
Found Valid Status
Found Valid Status
Status: Fail
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.FromTo("Status: { OK | Error | Pending }", "Found Valid Status");

   cout << t.Transform("Status: OK") << endl;
   cout << t.Transform("Status: Error") << endl;
   cout << t.Transform("Status: Fail") << endl;
}
				
			
Found Valid Status
Found Valid Status
Status: Fail
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      t.FromTo("Status: { OK | Error | Pending }", "Found Valid Status")
      
      Console.WriteLine(t.Transform("Status: OK"))
      Console.WriteLine(t.Transform("Status: Error"))
      Console.WriteLine(t.Transform("Status: Fail"))
   End Sub
End Module
				
			
Found Valid Status
Found Valid Status
Status: Fail
Previous
Next