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.

Filter()

Method

Product: 

Transformer Library

Class: 

Transformer

Performs a pattern-matching operation and returns a new string consisting only of the transformed matches.

Syntax

Filter()

Parameters

[None]

Return

Transformer

Current object

Remarks

[Revisit]The Filter() method performs a pattern-matching operation similar to Find() but produces a new string composed exclusively of the results. Unlike Transform(), which modifies the source text in-place, Filter() extracts the matches and concatenates their transformed output, with each result separated by a newline.

This makes it the ideal tool for data extraction, summarization, or creating a new document from selected parts of an original.

Find() vs. Filter() vs. Transform()

Choosing the correct method is key to efficient text processing. This table clarifies their distinct purposes:

MethodPurposeResultUse Case
Find()LocatePopulates the Matches collection with the locations of patterns. Does not produce an output string.When you only need to know if and where patterns exist.
Filter()Extract & TransformCreates a new string consisting only of the transformed results of each match, separated by newlines.Extracting all log errors, URLs, or specific data points from a document into a clean list.
Transform()Modify In-PlaceModifies the original text, replacing matches according to rules but preserving all other content.Performing a search-and-replace operation on a document.

How Replacements Work

The output of Filter() is built from the replacement part of each matching rule defined with FromTo(). If a rule was defined with Pattern(), which has no explicit replacement, the matched text itself ({@Self}) is used.

💡 Why uCalc? (Comparative Analysis)

In a standard Regex workflow, achieving the same result as Filter() is a multi-step, manual process:

  1. Run the regex search to get a collection of all matches.
  2. Create a StringBuilder or a List<string> in your host language (C#/C++).
  3. Loop through the match collection.
  4. For each match, perform any necessary transformation on its value.
  5. Append the transformed string to your builder/list.
  6. Finally, join the results with newlines to get the final string.

Filter() encapsulates this entire workflow into a single, highly optimized method call. You define your extraction and transformation logic declaratively, and the engine handles the iteration, transformation, and string concatenation internally, leading to code that is cleaner, faster, and less error-prone.

Examples

Rule Name
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "<b>(5+4)</b> this and that etc";
var a = t.Pattern("<{tg}>");
var b = t.Pattern("This {body} That");
var c = t.Pattern("etc");
var d = t.Pattern("({expr})");

t.Filter();
Console.WriteLine("--- Matches ---");
Console.WriteLine(t.Matches.Text);
Console.WriteLine("--- Pattern names ---");
Console.WriteLine(a.Name);
Console.WriteLine(b.Name);
Console.WriteLine(c.Name);
Console.WriteLine(d.Name);
Console.WriteLine("--- Pattern defs ---");
Console.WriteLine(a.Pattern);
Console.WriteLine(b.Pattern);
Console.WriteLine(c.Pattern);
Console.WriteLine(d.Pattern);
				
			
--- Matches ---
<b>
(5+4)
</b>
this and that
etc
--- Pattern names ---
<
this
etc
(
--- Pattern defs ---
<{tg}>
This {body} That
etc
({expr})
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("<b>(5+4)</b> this and that etc");
   auto a = t.Pattern("<{tg}>");
   auto b = t.Pattern("This {body} That");
   auto c = t.Pattern("etc");
   auto d = t.Pattern("({expr})");

   t.Filter();
   cout << "--- Matches ---" << endl;
   cout << t.Matches().Text() << endl;
   cout << "--- Pattern names ---" << endl;
   cout << a.Name() << endl;
   cout << b.Name() << endl;
   cout << c.Name() << endl;
   cout << d.Name() << endl;
   cout << "--- Pattern defs ---" << endl;
   cout << a.Pattern() << endl;
   cout << b.Pattern() << endl;
   cout << c.Pattern() << endl;
   cout << d.Pattern() << endl;
}
				
			
--- Matches ---
<b>
(5+4)
</b>
this and that
etc
--- Pattern names ---
<
this
etc
(
--- Pattern defs ---
<{tg}>
This {body} That
etc
({expr})
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "<b>(5+4)</b> this and that etc"
      Dim a = t.Pattern("<{tg}>")
      Dim b = t.Pattern("This {body} That")
      Dim c = t.Pattern("etc")
      Dim d = t.Pattern("({expr})")
      
      t.Filter()
      Console.WriteLine("--- Matches ---")
      Console.WriteLine(t.Matches.Text)
      Console.WriteLine("--- Pattern names ---")
      Console.WriteLine(a.Name)
      Console.WriteLine(b.Name)
      Console.WriteLine(c.Name)
      Console.WriteLine(d.Name)
      Console.WriteLine("--- Pattern defs ---")
      Console.WriteLine(a.Pattern)
      Console.WriteLine(b.Pattern)
      Console.WriteLine(c.Pattern)
      Console.WriteLine(d.Pattern)
   End Sub
End Module
				
			
--- Matches ---
<b>
(5+4)
</b>
this and that
etc
--- Pattern names ---
<
this
etc
(
--- Pattern defs ---
<{tg}>
This {body} That
etc
({expr})
Previous
Next