uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

GlobalMaximum = [int]

Property

Product: 

Transformer Library

Class: 

Rule

Gets or sets the maximum number of matches a rule can find before invalidating the entire transformation pass.

Remarks

The GlobalMaximum property defines a validation threshold for a Rule. If the number of matches found by this specific rule exceeds the GlobalMaximum value, the entire Transformer operation (e.g., Find, Transform) is immediately invalidated, and no matches are returned for any rule in that pass.

This provides a powerful mechanism for enforcing structural rules, such as ensuring a specific keyword or block appears at most 'N' times in a document.

GlobalMaximum vs. Maximum

Understanding the difference between GlobalMaximum and the standard Maximum property is crucial.

PropertyScope of InvalidationEffect when Exceeded
MaximumRule-LevelOnly the matches for this specific rule are discarded. Other rules are unaffected.
GlobalMaximumTransformer-LevelAll matches for all rules within the current transformer pass are discarded. The operation returns zero matches.

By default, GlobalMaximum is set to -1 (or the maximum value for an unsigned integer), which signifies no limit.

Scope and Limitations

The invalidation effect of GlobalMaximum is limited to the local Transformer instance or pass it is defined in. It does not propagate to parent transformers or subsequent passes.

💡 Why uCalc? (Comparative Analysis)

Most regex-based systems do not have a built-in mechanism to fail a search based on the count of matches. A developer would typically need to perform a search, get all matches, and then write separate application logic to check if the count exceeds a threshold.

// Manual, multi-step approach without uCalcvar matches = MyRegex.Matches(text);if (matches.Count > 2) {  // Handle the error, discard all results} else {  // Process the valid matches}

uCalc's GlobalMaximum property is declarative and more efficient. It integrates this validation directly into the parsing engine. The engine can often fail fast, stopping the search as soon as the limit is exceeded, rather than needing to find all possible matches first. This makes it a superior tool for building parsers with strict grammar and occurrence rules.

Examples

Demonstrates how `GlobalMaximum` invalidates a search if a rule matches too many times.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
var rule = t.FromTo("ERROR", "[ERR]");
rule.GlobalMaximum = 2;

// This input has 3 matches, which exceeds the maximum of 2.
string input1 = "ERROR 1, ERROR 2, ERROR 3";
t.Transform(input1);
Console.WriteLine($"Input 1 Match Count: {t.Matches.Count()}"); // Expect 0

// This input has 2 matches, which is within the limit.
string input2 = "ERROR 1, ERROR 2";
t.Transform(input2);
Console.WriteLine($"Input 2 Match Count: {t.Matches.Count()}"); // Expect 2
Console.WriteLine(t);
				
			
Input 1 Match Count: 0
Input 2 Match Count: 2
[ERR] 1, [ERR] 2
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   auto rule = t.FromTo("ERROR", "[ERR]");
   rule.GlobalMaximum(2);

   // This input has 3 matches, which exceeds the maximum of 2.
   string input1 = "ERROR 1, ERROR 2, ERROR 3";
   t.Transform(input1);
   cout << "Input 1 Match Count: " << t.Matches().Count() << endl; // Expect 0

   // This input has 2 matches, which is within the limit.
   string input2 = "ERROR 1, ERROR 2";
   t.Transform(input2);
   cout << "Input 2 Match Count: " << t.Matches().Count() << endl; // Expect 2
   cout << t << endl;
}
				
			
Input 1 Match Count: 0
Input 2 Match Count: 2
[ERR] 1, [ERR] 2
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      Dim rule = t.FromTo("ERROR", "[ERR]")
      rule.GlobalMaximum = 2
      
      '// This input has 3 matches, which exceeds the maximum of 2.
      Dim input1 As String = "ERROR 1, ERROR 2, ERROR 3"
      t.Transform(input1)
      Console.WriteLine($"Input 1 Match Count: {t.Matches.Count()}") '// Expect 0
      
      '// This input has 2 matches, which is within the limit.
      Dim input2 As String = "ERROR 1, ERROR 2"
      t.Transform(input2)
      Console.WriteLine($"Input 2 Match Count: {t.Matches.Count()}") '// Expect 2
      Console.WriteLine(t)
   End Sub
End Module
				
			
Input 1 Match Count: 0
Input 2 Match Count: 2
[ERR] 1, [ERR] 2
Internal Test: Compares the behavior of `Maximum` and `GlobalMaximum` at different thresholds to validate their distinct scopes of invalidation.
				
					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' />
</Fruits>

""";

var t = new uCalc.Transformer();
var fruitsTagRule = t.FromTo("<Fruits>", "List of fruits");
var fruitRule = t.FromTo("CommonName={@string:name}", "- {name}");

Console.WriteLine("--- Using Maximum (Rule-Level) ---");
fruitRule.Maximum = 3; // Rule fails if more than 3 fruits are found.
t.Filter(FruitsXML);
Console.WriteLine($"Match count when fruit rule fails: {t.Matches.Count()}"); // The 'fruitsTagRule' still matches.
Console.WriteLine(t.Matches.Text);

Console.WriteLine("");
Console.WriteLine("--- Using GlobalMaximum (Transformer-Level) ---");
fruitRule.Maximum = -1; // Reset local maximum
fruitRule.GlobalMaximum = 3; // Transformer fails if more than 3 fruits are found.
t.Filter(FruitsXML);
Console.WriteLine($"Match count when global rule fails: {t.Matches.Count()}"); // All matches are invalidated.
Console.WriteLine(t.Matches.Text);
				
			
--- Using Maximum (Rule-Level) ---
Match count when fruit rule fails: 1
List of fruits

--- Using GlobalMaximum (Transformer-Level) ---
Match count when global rule fails: 0

				
					#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' />
</Fruits>
)";

   uCalc::Transformer t;
   auto fruitsTagRule = t.FromTo("<Fruits>", "List of fruits");
   auto fruitRule = t.FromTo("CommonName={@string:name}", "- {name}");

   cout << "--- Using Maximum (Rule-Level) ---" << endl;
   fruitRule.Maximum(3); // Rule fails if more than 3 fruits are found.
   t.Filter(FruitsXML);
   cout << "Match count when fruit rule fails: " << t.Matches().Count() << endl; // The 'fruitsTagRule' still matches.
   cout << t.Matches().Text() << endl;

   cout << "" << endl;
   cout << "--- Using GlobalMaximum (Transformer-Level) ---" << endl;
   fruitRule.Maximum(-1); // Reset local maximum
   fruitRule.GlobalMaximum(3); // Transformer fails if more than 3 fruits are found.
   t.Filter(FruitsXML);
   cout << "Match count when global rule fails: " << t.Matches().Count() << endl; // All matches are invalidated.
   cout << t.Matches().Text() << endl;
}
				
			
--- Using Maximum (Rule-Level) ---
Match count when fruit rule fails: 1
List of fruits

--- Using GlobalMaximum (Transformer-Level) ---
Match count when global rule fails: 0

				
					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' />
</Fruits>
"
      
      Dim t As New uCalc.Transformer()
      Dim fruitsTagRule = t.FromTo("<Fruits>", "List of fruits")
      Dim fruitRule = t.FromTo("CommonName={@string:name}", "- {name}")
      
      Console.WriteLine("--- Using Maximum (Rule-Level) ---")
      fruitRule.Maximum = 3 '// Rule fails if more than 3 fruits are found.
      t.Filter(FruitsXML)
      Console.WriteLine($"Match count when fruit rule fails: {t.Matches.Count()}") '// The 'fruitsTagRule' still matches.
      Console.WriteLine(t.Matches.Text)
      
      Console.WriteLine("")
      Console.WriteLine("--- Using GlobalMaximum (Transformer-Level) ---")
      fruitRule.Maximum = -1 '// Reset local maximum
      fruitRule.GlobalMaximum = 3 '// Transformer fails if more than 3 fruits are found.
      t.Filter(FruitsXML)
      Console.WriteLine($"Match count when global rule fails: {t.Matches.Count()}") '// All matches are invalidated.
      Console.WriteLine(t.Matches.Text)
   End Sub
End Module
				
			
--- Using Maximum (Rule-Level) ---
Match count when fruit rule fails: 1
List of fruits

--- Using GlobalMaximum (Transformer-Level) ---
Match count when global rule fails: 0
Maximum, GlobalMaximum
				
					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");
var t = uc.NewTransformer();
var FruitsTag = t.FromTo("<Fruits>", "List of fruits");
var Fruit = t.FromTo("CommonName={@string:name}", "{@Eval: x++}. {name}");

uc.Eval("x = 1");
Fruit.Maximum = 10;
t.Filter(FruitsXML);
Console.WriteLine($"Maximum = {Fruit.Maximum}");
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.Maximum = 20;
t.Filter(FruitsXML);
Console.WriteLine($"Maximum = {Fruit.Maximum}");
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.GlobalMaximum = 10; // Notice "List of fruits" will not show
t.Filter(FruitsXML);
Console.WriteLine($"MaximumAND = {Fruit.GlobalMaximum}");
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.GlobalMaximum = 20;
t.Filter(FruitsXML);
Console.WriteLine($"MaximumAND = {Fruit.GlobalMaximum}");
Console.WriteLine($"Matches count: {t.Matches.Count()}");
Console.WriteLine("");
Console.WriteLine(t.Matches);

				
			
Maximum = 10
Matches count: 1

List of fruits

===============
Maximum = 20
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

===============
MaximumAND = 10
Matches count: 0


===============
MaximumAND = 20
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");
   auto t = uc.NewTransformer();
   auto FruitsTag = t.FromTo("<Fruits>", "List of fruits");
   auto Fruit = t.FromTo("CommonName={@string:name}", "{@Eval: x++}. {name}");

   uc.Eval("x = 1");
   Fruit.Maximum(10);
   t.Filter(FruitsXML);
   cout << "Maximum = " << Fruit.Maximum() << 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.Maximum(20);
   t.Filter(FruitsXML);
   cout << "Maximum = " << Fruit.Maximum() << 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.GlobalMaximum(10); // Notice "List of fruits" will not show
   t.Filter(FruitsXML);
   cout << "MaximumAND = " << Fruit.GlobalMaximum() << 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.GlobalMaximum(20);
   t.Filter(FruitsXML);
   cout << "MaximumAND = " << Fruit.GlobalMaximum() << endl;
   cout << "Matches count: " << t.Matches().Count() << endl;
   cout << "" << endl;
   cout << t.Matches() << endl;

}
				
			
Maximum = 10
Matches count: 1

List of fruits

===============
Maximum = 20
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

===============
MaximumAND = 10
Matches count: 0


===============
MaximumAND = 20
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")
      Dim t = uc.NewTransformer()
      Dim FruitsTag = t.FromTo("<Fruits>", "List of fruits")
      Dim Fruit = t.FromTo("CommonName={@string:name}", "{@Eval: x++}. {name}")
      
      uc.Eval("x = 1")
      Fruit.Maximum = 10
      t.Filter(FruitsXML)
      Console.WriteLine($"Maximum = {Fruit.Maximum}")
      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.Maximum = 20
      t.Filter(FruitsXML)
      Console.WriteLine($"Maximum = {Fruit.Maximum}")
      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.GlobalMaximum = 10 '// Notice "List of fruits" will not show
      t.Filter(FruitsXML)
      Console.WriteLine($"MaximumAND = {Fruit.GlobalMaximum}")
      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.GlobalMaximum = 20
      t.Filter(FruitsXML)
      Console.WriteLine($"MaximumAND = {Fruit.GlobalMaximum}")
      Console.WriteLine($"Matches count: {t.Matches.Count()}")
      Console.WriteLine("")
      Console.WriteLine(t.Matches)
      
   End Sub
End Module
				
			
Maximum = 10
Matches count: 1

List of fruits

===============
Maximum = 20
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

===============
MaximumAND = 10
Matches count: 0


===============
MaximumAND = 20
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