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.

Capturing Text with Variables

Product: 

Class: 

Explains how to use named placeholders (variables) in patterns to capture, reuse, and validate dynamic text.

Remarks

🎣 Capturing Text with Variables

At the heart of any parsing task is the need to find known text in order to extract unknown text. In uCalc's Transformer, this is done using two simple concepts: Anchors and Variables.

  • Anchors are the literal, static text in your pattern that must exist in the source string. They act as guideposts for the parser. In the pattern User: {name}, the text User: is the anchor.
  • Variables are named placeholders enclosed in curly braces {...} that capture the dynamic, unknown text. In User: {name}, the variable {name} captures whatever text follows the anchor.

How a Capture Works

By default, a variable like {data} is "smart lazy." It captures all text until it encounters one of three things:

  1. The next anchor defined in your pattern.
  2. A statement separator token (like a newline or semicolon).
  3. The end of the string.

This behavior is incredibly powerful because it automatically respects the natural structure of your text without requiring complex lookaheads or non-greedy specifiers common in Regex.

Using Captured Variables

Once a variable captures text, you can re-insert it in the replacement string using the same {variableName} syntax. This allows you to reformat, wrap, or reorder the extracted data.

## Backreferences: Enforcing EqualityOne of the most powerful features is **backreferencing**. If you use the same variable name multiple times within the *pattern string*, uCalc enforces that the captured text for each instance must be identical. This is the key to matching balanced structures.For example, the pattern `<{tag}>{content}</{tag}>` will correctly match `<b>text</b>` because the `{tag}` variable captures `b` in both places. It will **not** match `<b>text</i>`, preventing a common parsing error.## 💡 Why uCalc? (Comparative Analysis)### vs. Regular ExpressionsRegex uses capture groups `(...)` and backreferences like `$1` or `\1`. uCalc's approach is superior for several reasons:*   **Readability**: Named variables like `{user}` are far more readable and maintainable than numeric indices like `$1`.*   **Token Awareness**: A uCalc variable like `{word}` automatically respects word boundaries. In Regex, you must manually add boundaries (`\bword\b`) to prevent partial matches inside other words.*   **Safe Backreferences**: As shown above, matching balanced tags is simple and intuitive in uCalc, while it is often complex and fragile in Regex.### vs. Native String SplittingUsing native functions like `string.Split()` is common but brittle.*   **Positional Fragility**: `Split()` gives you an array of results that you must access by a numeric index (e.g., `parts[1]`). If the input format changes slightly, your indices may be wrong, leading to runtime errors.*   **Named Access**: uCalc variables allow you to access captured data by a meaningful name, making your code more robust and self-documenting.

Examples

Extracts a value from a simple key-value pair.

ID: 1198

See: Capturing Text with Variables 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
t.FromTo("ID: {value}", "Found value: {value}");
Console.WriteLine(t.Transform("Product ID: 12345"));
				
			
Product Found value: 12345
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   t.FromTo("ID: {value}", "Found value: {value}");
   cout << t.Transform("Product ID: 12345") << endl;
}
				
			
Product Found value: 12345
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("ID: {value}", "Found value: {value}")
      Console.WriteLine(t.Transform("Product ID: 12345"))
   End Sub
End Module
				
			
Product Found value: 12345
Explore 600+ other examples
Parses a structured log entry and reformats it for display using multiple variables.

ID: 1199

See: Capturing Text with Variables 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
// Note the use of {@String} to capture the quoted text
t.FromTo("'['{level}']' Code: {code}, Msg: {@String:message}",
"[{level}] - {message} (Code {code})");

var log = "[ERROR] Code: 404, Msg: 'Not Found'";
Console.WriteLine(t.Transform(log));
				
			
[ERROR] - Not Found (Code 404)
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   // Note the use of {@String} to capture the quoted text
   t.FromTo("'['{level}']' Code: {code}, Msg: {@String:message}",
   "[{level}] - {message} (Code {code})");

   auto log = "[ERROR] Code: 404, Msg: 'Not Found'";
   cout << t.Transform(log) << endl;
}
				
			
[ERROR] - Not Found (Code 404)
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()
      '// Note the use of {@String} to capture the quoted text
      t.FromTo("'['{level}']' Code: {code}, Msg: {@String:message}",
      "[{level}] - {message} (Code {code})")
      
      Dim log = "[ERROR] Code: 404, Msg: 'Not Found'"
      Console.WriteLine(t.Transform(log))
   End Sub
End Module
				
			
[ERROR] - Not Found (Code 404)
Explore 600+ other examples