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.

GlobalMinimum = [int]

Property

Product: 

Transformer Library

Class: 

Rule

Gets or sets the minimum number of matches this rule must find for the entire transform operation to be considered valid.

Remarks

🛡️ Global Match Threshold: GlobalMinimum

The GlobalMinimum property sets a "pass/fail" condition for an entire Transformer operation. If this rule does not find at least the specified minimum number of matches, the entire transform is invalidated, and no matches from any rule will be returned.

This is a powerful feature for validating document structure, ensuring that a file contains a required number of key elements before it is processed further.

GlobalMinimum vs. Minimum

It is crucial to understand the difference in scope between these two properties.

PropertyScope of FailureBehaviorUse Case
rule.@Minimum(n)Rule-specificIf this rule finds fewer than n matches, only the matches for this rule are discarded. Other rules are unaffected.When a specific pattern is optional but, if present, must appear a certain number of times.
rule.@GlobalMinimum(n)Transformer-wideIf this rule finds fewer than n matches, the entire Find, Filter, or Transform operation fails, returning zero matches for all rules.When the presence of a certain number of n matches from this rule is a mandatory validation check for the entire document.

⚠️ Performance Considerations

To enable this "all or nothing" behavior, the Transformer must store a backup of the original string. If the GlobalMinimum is not met, the engine discards the results and reverts to this backup. This consumes more memory than a standard transformation.

💡 Why uCalc? (Comparative Analysis)

In a standard Regex-based workflow, achieving this would require multiple steps:

  1. Run the regex search to get all matches.
  2. Count the number of matches found.
  3. Write an if statement in your host language (C#, C++, etc.) to check if the count meets your minimum.
  4. If it doesn't, manually discard all results.

uCalc's GlobalMinimum is declarative. You state your requirement directly on the rule, and the engine handles the validation logic internally. This leads to cleaner, more expressive, and less error-prone code by keeping the validation logic tightly coupled with the pattern it applies to.

Examples

Succinct: Demonstrates the pass/fail behavior of GlobalMinimum. If the rule doesn't find at least 3 'a's, the entire transform fails.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var ruleA = t.FromTo("a", "A");
var ruleB = t.FromTo("b", "B");
ruleA.GlobalMinimum = 3;

// Case 1: Fails (only 2 'a's)
Console.WriteLine("--- Case 1: Fails ---");
t.Text = "a b a b";
t.Transform();
Console.WriteLine($"Matches Found: {t.Matches.Count()}"); // Should be 0
Console.WriteLine($"Result: {t}");

// Case 2: Succeeds (3 'a's)
Console.WriteLine("");
Console.WriteLine("--- Case 2: Succeeds ---");
t.Text = "a b a b a";
t.Transform();
Console.WriteLine($"Matches Found: {t.Matches.Count()}"); // Should be 5 (3 'A's and 2 'B's)
Console.WriteLine($"Result: {t}");
				
			
--- Case 1: Fails ---
Matches Found: 0
Result: a b a b

--- Case 2: Succeeds ---
Matches Found: 5
Result: A B A B A
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto ruleA = t.FromTo("a", "A");
   auto ruleB = t.FromTo("b", "B");
   ruleA.GlobalMinimum(3);

   // Case 1: Fails (only 2 'a's)
   cout << "--- Case 1: Fails ---" << endl;
   t.Text("a b a b");
   t.Transform();
   cout << "Matches Found: " << t.Matches().Count() << endl; // Should be 0
   cout << "Result: " << t << endl;

   // Case 2: Succeeds (3 'a's)
   cout << "" << endl;
   cout << "--- Case 2: Succeeds ---" << endl;
   t.Text("a b a b a");
   t.Transform();
   cout << "Matches Found: " << t.Matches().Count() << endl; // Should be 5 (3 'A's and 2 'B's)
   cout << "Result: " << t << endl;
}
				
			
--- Case 1: Fails ---
Matches Found: 0
Result: a b a b

--- Case 2: Succeeds ---
Matches Found: 5
Result: A B A B A
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim ruleA = t.FromTo("a", "A")
      Dim ruleB = t.FromTo("b", "B")
      ruleA.GlobalMinimum = 3
      
      '// Case 1: Fails (only 2 'a's)
      Console.WriteLine("--- Case 1: Fails ---")
      t.Text = "a b a b"
      t.Transform()
      Console.WriteLine($"Matches Found: {t.Matches.Count()}") '// Should be 0
      Console.WriteLine($"Result: {t}")
      
      '// Case 2: Succeeds (3 'a's)
      Console.WriteLine("")
      Console.WriteLine("--- Case 2: Succeeds ---")
      t.Text = "a b a b a"
      t.Transform()
      Console.WriteLine($"Matches Found: {t.Matches.Count()}") '// Should be 5 (3 'A's and 2 'B's)
      Console.WriteLine($"Result: {t}")
   End Sub
End Module
				
			
--- Case 1: Fails ---
Matches Found: 0
Result: a b a b

--- Case 2: Succeeds ---
Matches Found: 5
Result: A B A B A
Minimum, GlobalMinimum
				
					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>

""";

uc.DefineVariable("x = 1");
var t = uc.NewTransformer();
var FruitsTag = t.FromTo("<Fruits>", "List of fruits");
var Fruit = t.FromTo("CommonName={@string:name}", "{@Eval: x++}. {name}");

Fruit.Minimum = 20;
t.Filter(FruitsXML);
Console.WriteLine($"Minimum = {Fruit.Minimum}");
Console.WriteLine($"Matches count: {t.Matches.Count()}"); // 1 for FruitsTag occurrence
Console.WriteLine("");
Console.WriteLine(t.Matches);
Console.WriteLine("");
Console.WriteLine("===============");

uc.Eval("x = 1");
Fruit.Minimum = 10;
t.Filter(FruitsXML);
Console.WriteLine($"Minimum = {Fruit.Minimum}");
Console.WriteLine($"Matches count: {t.Matches.Count()}"); // 1 for FruitsTag plus 12 fruits
Console.WriteLine("");
Console.WriteLine(t.Matches);
Console.WriteLine("");
Console.WriteLine("===============");

uc.Eval("x = 1");
Fruit.GlobalMinimum = 20; // Notice "List of fruits" will not show
t.Filter(FruitsXML);
Console.WriteLine($"MinimumAND = {Fruit.GlobalMinimum}");
Console.WriteLine($"Matches count: {t.Matches.Count()}"); // Even FruitsTage won't be counted
Console.WriteLine("");
Console.WriteLine(t.Matches);
Console.WriteLine("===============");

uc.Eval("x = 1");
Fruit.GlobalMinimum = 10;
t.Filter(FruitsXML);
Console.WriteLine($"MinimumAND = {Fruit.GlobalMinimum}");
Console.WriteLine($"Matches count: {t.Matches.Count()}");
Console.WriteLine("");
Console.WriteLine(t.Matches);

				
			
Minimum = 20
Matches count: 1

List of fruits

===============
Minimum = 10
Matches count: 13

List of fruits
1. Apple
2. Banana
3. Orange
4. Grapes
5. Strawberry
6. Pineapple
7. Mango
8. Blueberry
9. Rambutan
10. Salak (Snake Fruit)
11. Jabuticaba
12. Watermelon

===============
MinimumAND = 20
Matches count: 0


===============
MinimumAND = 10
Matches count: 13

List of fruits
1. Apple
2. Banana
3. Orange
4. Grapes
5. Strawberry
6. Pineapple
7. Mango
8. Blueberry
9. Rambutan
10. Salak (Snake Fruit)
11. Jabuticaba
12. Watermelon
				
					#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>
)";

   uc.DefineVariable("x = 1");
   auto t = uc.NewTransformer();
   auto FruitsTag = t.FromTo("<Fruits>", "List of fruits");
   auto Fruit = t.FromTo("CommonName={@string:name}", "{@Eval: x++}. {name}");

   Fruit.Minimum(20);
   t.Filter(FruitsXML);
   cout << "Minimum = " << Fruit.Minimum() << endl;
   cout << "Matches count: " << t.Matches().Count() << endl; // 1 for FruitsTag occurrence
   cout << "" << endl;
   cout << t.Matches() << endl;
   cout << "" << endl;
   cout << "===============" << endl;

   uc.Eval("x = 1");
   Fruit.Minimum(10);
   t.Filter(FruitsXML);
   cout << "Minimum = " << Fruit.Minimum() << endl;
   cout << "Matches count: " << t.Matches().Count() << endl; // 1 for FruitsTag plus 12 fruits
   cout << "" << endl;
   cout << t.Matches() << endl;
   cout << "" << endl;
   cout << "===============" << endl;

   uc.Eval("x = 1");
   Fruit.GlobalMinimum(20); // Notice "List of fruits" will not show
   t.Filter(FruitsXML);
   cout << "MinimumAND = " << Fruit.GlobalMinimum() << endl;
   cout << "Matches count: " << t.Matches().Count() << endl; // Even FruitsTage won't be counted
   cout << "" << endl;
   cout << t.Matches() << endl;
   cout << "===============" << endl;

   uc.Eval("x = 1");
   Fruit.GlobalMinimum(10);
   t.Filter(FruitsXML);
   cout << "MinimumAND = " << Fruit.GlobalMinimum() << endl;
   cout << "Matches count: " << t.Matches().Count() << endl;
   cout << "" << endl;
   cout << t.Matches() << endl;

}
				
			
Minimum = 20
Matches count: 1

List of fruits

===============
Minimum = 10
Matches count: 13

List of fruits
1. Apple
2. Banana
3. Orange
4. Grapes
5. Strawberry
6. Pineapple
7. Mango
8. Blueberry
9. Rambutan
10. Salak (Snake Fruit)
11. Jabuticaba
12. Watermelon

===============
MinimumAND = 20
Matches count: 0


===============
MinimumAND = 10
Matches count: 13

List of fruits
1. Apple
2. Banana
3. Orange
4. Grapes
5. Strawberry
6. Pineapple
7. Mango
8. Blueberry
9. Rambutan
10. Salak (Snake Fruit)
11. Jabuticaba
12. Watermelon
				
					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>
"
      
      uc.DefineVariable("x = 1")
      Dim t = uc.NewTransformer()
      Dim FruitsTag = t.FromTo("<Fruits>", "List of fruits")
      Dim Fruit = t.FromTo("CommonName={@string:name}", "{@Eval: x++}. {name}")
      
      Fruit.Minimum = 20
      t.Filter(FruitsXML)
      Console.WriteLine($"Minimum = {Fruit.Minimum}")
      Console.WriteLine($"Matches count: {t.Matches.Count()}") '// 1 for FruitsTag occurrence 
      Console.WriteLine("")
      Console.WriteLine(t.Matches)
      Console.WriteLine("")
      Console.WriteLine("===============")
      
      uc.Eval("x = 1")
      Fruit.Minimum = 10
      t.Filter(FruitsXML)
      Console.WriteLine($"Minimum = {Fruit.Minimum}")
      Console.WriteLine($"Matches count: {t.Matches.Count()}") '// 1 for FruitsTag plus 12 fruits
      Console.WriteLine("")
      Console.WriteLine(t.Matches)
      Console.WriteLine("")
      Console.WriteLine("===============")
      
      uc.Eval("x = 1")
      Fruit.GlobalMinimum = 20 '// Notice "List of fruits" will not show
      t.Filter(FruitsXML)
      Console.WriteLine($"MinimumAND = {Fruit.GlobalMinimum}")
      Console.WriteLine($"Matches count: {t.Matches.Count()}") '// Even FruitsTage won't be counted
      Console.WriteLine("")
      Console.WriteLine(t.Matches)
      Console.WriteLine("===============")
      
      uc.Eval("x = 1")
      Fruit.GlobalMinimum = 10
      t.Filter(FruitsXML)
      Console.WriteLine($"MinimumAND = {Fruit.GlobalMinimum}")
      Console.WriteLine($"Matches count: {t.Matches.Count()}")
      Console.WriteLine("")
      Console.WriteLine(t.Matches)
      
   End Sub
End Module
				
			
Minimum = 20
Matches count: 1

List of fruits

===============
Minimum = 10
Matches count: 13

List of fruits
1. Apple
2. Banana
3. Orange
4. Grapes
5. Strawberry
6. Pineapple
7. Mango
8. Blueberry
9. Rambutan
10. Salak (Snake Fruit)
11. Jabuticaba
12. Watermelon

===============
MinimumAND = 20
Matches count: 0


===============
MinimumAND = 10
Matches count: 13

List of fruits
1. Apple
2. Banana
3. Orange
4. Grapes
5. Strawberry
6. Pineapple
7. Mango
8. Blueberry
9. Rambutan
10. Salak (Snake Fruit)
11. Jabuticaba
12. Watermelon
Previous
Next