uCalc API Version: 5.7.0-preview.1 Released: 7/30/2026

Warning

uCalc API Preview Release Notice:This preview documentation describes the intended behavior of the API. It is not fully accurate or complete.The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.Use of the preview version in your production code is not recommended.

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.

csharp
// 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.

You can then use `{status_val}` in your replacement string to reference the specific text that was matched.## 3. 💎 Conditional ReplacementsThis 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 PitfallThe 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 "b**in**" or "**to**p" unless you explicitly add word boundaries (`\b`). uCalc defaults to whole-token matching, preventing these common false positives automatically.

Examples

How to match one of several possible status keywords.

ID: 1207

See: Alternation 
				
					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
Explore 600+ other examples
				
					#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
Explore 600+ other examples
				
					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
Explore 600+ other examples