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.

Maximum = [int]

Property

Product: 

Transformer Library

Class: 

Rule

Gets or sets the maximum number of matches a rule is allowed to find; if exceeded, this rule's own matches are invalidated.

Remarks

🎯 Rule-Level Match Limit: Maximum

The Maximum property sets a validation threshold for an individual Rule. If the number of matches found by this specific rule exceeds the Maximum value, the operation continues, but all matches found by this rule are invalidated and discarded from the final results. This provides a powerful way to enforce structural constraints on a per-pattern basis.

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

Maximum vs. GlobalMaximum vs. StopAfter

Choosing the correct property to limit matches is crucial. This table clarifies their distinct behaviors:

PropertyEffect when Limit is ExceededUse Case
@Maximum(n) (This Property)Only matches from this rule are invalidated. Other rules are unaffected.When a pattern should be ignored entirely if it appears too many times.
@GlobalMaximum(n)All matches from all rules are invalidated. The operation fails.When a pattern's count is a critical validation check for the entire document.
@StopAfter(n)Matching for this rule stops after n matches. The first n matches are kept.When you only care about the first few occurrences of a pattern and want to stop early.

⚠️ Performance Note

To enable this "all or nothing" behavior for a rule, the Transformer must store a backup of the original string. If the Maximum count is exceeded, the engine discards the results, deactivates the rule, and re-scans the text from the backup. This consumes more memory and time than a standard transformation. For simple match limiting without invalidation, @StopAfter is more performant.

💡 Why uCalc? (Comparative Analysis)

In a standard regex workflow, you would have to perform these steps manually:

  1. Run the regex search to get all matches for a pattern.
  2. Get the count of the matches.
  3. Write an if statement in your application code to check if the count exceeds a threshold.
  4. If it does, manually filter those matches out of your final result set.

uCalc's @Maximum property is declarative. You state the constraint directly on the rule, and the engine handles the validation and invalidation logic internally. This leads to cleaner, more expressive code by keeping the validation logic tightly coupled with the pattern it applies to.

Examples

Succinct: A basic demonstration of how the Maximum threshold invalidates a rule's matches.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var ruleA = t.FromTo("a", "A");

// Case 1: Limit is 2, but 3 'a's are present. The rule is invalidated.
t.Transform("a b a c a");
ruleA.Maximum = 2;
Console.WriteLine("--- Maximum = 2 (Rule Fails) ---");
Console.Write("Result: ");
Console.WriteLine(t.Transform("a b a c a"));

// Case 2: Limit is 3. The rule passes and matches are kept.
ruleA.Maximum = 3;
Console.WriteLine("");
Console.WriteLine("--- Maximum = 3 (Rule Succeeds) ---");
Console.Write("Result: ");
Console.WriteLine(t.Transform("a b a c a"));
				
			
--- Maximum = 2 (Rule Fails) ---
Result: a b a c a

--- Maximum = 3 (Rule Succeeds) ---
Result: A b A c 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");

   // Case 1: Limit is 2, but 3 'a's are present. The rule is invalidated.
   t.Transform("a b a c a");
   ruleA.Maximum(2);
   cout << "--- Maximum = 2 (Rule Fails) ---" << endl;
   cout << "Result: ";
   cout << t.Transform("a b a c a") << endl;

   // Case 2: Limit is 3. The rule passes and matches are kept.
   ruleA.Maximum(3);
   cout << "" << endl;
   cout << "--- Maximum = 3 (Rule Succeeds) ---" << endl;
   cout << "Result: ";
   cout << t.Transform("a b a c a") << endl;
}
				
			
--- Maximum = 2 (Rule Fails) ---
Result: a b a c a

--- Maximum = 3 (Rule Succeeds) ---
Result: A b A c 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")
      
      '// Case 1: Limit is 2, but 3 'a's are present. The rule is invalidated.
      t.Transform("a b a c a")
      ruleA.Maximum = 2
      Console.WriteLine("--- Maximum = 2 (Rule Fails) ---")
      Console.Write("Result: ")
      Console.WriteLine(t.Transform("a b a c a"))
      
      '// Case 2: Limit is 3. The rule passes and matches are kept.
      ruleA.Maximum = 3
      Console.WriteLine("")
      Console.WriteLine("--- Maximum = 3 (Rule Succeeds) ---")
      Console.Write("Result: ")
      Console.WriteLine(t.Transform("a b a c a"))
   End Sub
End Module
				
			
--- Maximum = 2 (Rule Fails) ---
Result: a b a c a

--- Maximum = 3 (Rule Succeeds) ---
Result: A b A c A
Practical: Validating log file entries. If more than 2 'WARNING' entries exist, they are ignored, but 'ERROR' entries are still processed.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var log = "WARNING: low disk. ERROR: service down. WARNING: high CPU. WARNING: queue full.";

var warningRule = t.FromTo("WARNING: {msg}.", "[WARN] {msg}.");
var errorRule = t.FromTo("ERROR: {msg}.", "[ERR] {msg}.");

// Set a rule-specific limit for warnings.
warningRule.Maximum = 2;

t.Filter(log);
Console.WriteLine(t.Matches.Text);
				
			
[ERR] service down.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto log = "WARNING: low disk. ERROR: service down. WARNING: high CPU. WARNING: queue full.";

   auto warningRule = t.FromTo("WARNING: {msg}.", "[WARN] {msg}.");
   auto errorRule = t.FromTo("ERROR: {msg}.", "[ERR] {msg}.");

   // Set a rule-specific limit for warnings.
   warningRule.Maximum(2);

   t.Filter(log);
   cout << t.Matches().Text() << endl;
}
				
			
[ERR] service down.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim log = "WARNING: low disk. ERROR: service down. WARNING: high CPU. WARNING: queue full."
      
      Dim warningRule = t.FromTo("WARNING: {msg}.", "[WARN] {msg}.")
      Dim errorRule = t.FromTo("ERROR: {msg}.", "[ERR] {msg}.")
      
      '// Set a rule-specific limit for warnings.
      warningRule.Maximum = 2
      
      t.Filter(log)
      Console.WriteLine(t.Matches.Text)
   End Sub
End Module
				
			
[ERR] service down.
Internal Test: Compares the behavior of Maximum (rule-level) and GlobalMaximum (transformer-level) invalidation.
				
					using uCalcSoftware;

var uc = new uCalc();
var FruitsXML =
"""

<Fruits>
  <Fruit CommonName='Apple' />
  <Fruit CommonName='Banana' />
  <Fruit CommonName='Orange' />
  <Fruit CommonName='Grapes' />
</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 Invalidation) ---");
// The fruitRule will fail because there are 4 fruits, exceeding the max of 3.
fruitRule.Maximum = 3;
t.Filter(FruitsXML);
Console.WriteLine($"Match count: {t.Matches.Count()}"); // The 'fruitsTagRule' still matches and is counted.
Console.WriteLine(t.Matches.Text);

Console.WriteLine("");
Console.WriteLine("--- Using GlobalMaximum (Transformer-Level Invalidation) ---");
fruitRule.Maximum = -1; // Reset local maximum to default (unlimited).
fruitRule.GlobalMaximum = 3; // The entire transformer will fail if more than 3 fruits are found.
t.Filter(FruitsXML);
Console.WriteLine($"Match count: {t.Matches.Count()}"); // All matches (including fruitsTagRule) are invalidated.
Console.WriteLine(t.Matches.Text);
				
			
--- Using Maximum (Rule-Level Invalidation) ---
Match count: 1
List of fruits

--- Using GlobalMaximum (Transformer-Level Invalidation) ---
Match count: 0

				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto FruitsXML =
   R"(
<Fruits>
  <Fruit CommonName='Apple' />
  <Fruit CommonName='Banana' />
  <Fruit CommonName='Orange' />
  <Fruit CommonName='Grapes' />
</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 Invalidation) ---" << endl;
   // The fruitRule will fail because there are 4 fruits, exceeding the max of 3.
   fruitRule.Maximum(3);
   t.Filter(FruitsXML);
   cout << "Match count: " << t.Matches().Count() << endl; // The 'fruitsTagRule' still matches and is counted.
   cout << t.Matches().Text() << endl;

   cout << "" << endl;
   cout << "--- Using GlobalMaximum (Transformer-Level Invalidation) ---" << endl;
   fruitRule.Maximum(-1); // Reset local maximum to default (unlimited).
   fruitRule.GlobalMaximum(3); // The entire transformer will fail if more than 3 fruits are found.
   t.Filter(FruitsXML);
   cout << "Match count: " << t.Matches().Count() << endl; // All matches (including fruitsTagRule) are invalidated.
   cout << t.Matches().Text() << endl;
}
				
			
--- Using Maximum (Rule-Level Invalidation) ---
Match count: 1
List of fruits

--- Using GlobalMaximum (Transformer-Level Invalidation) ---
Match count: 0

				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim FruitsXML =
      "
<Fruits>
  <Fruit CommonName='Apple' />
  <Fruit CommonName='Banana' />
  <Fruit CommonName='Orange' />
  <Fruit CommonName='Grapes' />
</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 Invalidation) ---")
      '// The fruitRule will fail because there are 4 fruits, exceeding the max of 3.
      fruitRule.Maximum = 3
      t.Filter(FruitsXML)
      Console.WriteLine($"Match count: {t.Matches.Count()}") '// The 'fruitsTagRule' still matches and is counted.
      Console.WriteLine(t.Matches.Text)
      
      Console.WriteLine("")
      Console.WriteLine("--- Using GlobalMaximum (Transformer-Level Invalidation) ---")
      fruitRule.Maximum = -1 '// Reset local maximum to default (unlimited).
      fruitRule.GlobalMaximum = 3 '// The entire transformer will fail if more than 3 fruits are found.
      t.Filter(FruitsXML)
      Console.WriteLine($"Match count: {t.Matches.Count()}") '// All matches (including fruitsTagRule) are invalidated.
      Console.WriteLine(t.Matches.Text)
   End Sub
End Module
				
			
--- Using Maximum (Rule-Level Invalidation) ---
Match count: 1
List of fruits

--- Using GlobalMaximum (Transformer-Level Invalidation) ---
Match count: 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