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.

{@Eval}

Product: 

Class: 

Remarks

Evaluator Directive

Description: A directive that evaluates expressions within a pattern or replacement. In replacements, it differentiates between pre-parsed static expressions (@) and dynamically parsed expressions (@@).

The {@Eval} directive allows the uCalc::Transformer to leverage the full power of the uCalc mathematical and logical engine. Its behavior depends on where it is used and which prefix is applied.

1. Within a Pattern (Definition)

In the From (pattern) part of a rule, only {@Eval} is available.

  • It is evaluated once when the rule is defined.
  • The result of the evaluation is inserted back into the pattern as a literal.
  • Example: {@Eval: 1 + 1} in a pattern becomes 2.

2. Within a Replacement (Transformation)

In the To (replacement) part of a rule, the prefix determines how the expression is handled:

{@Eval: expression} (Parse Once)

This is the high-performance mode.

  • The expression is parsed/compiled once when the rule is created.
  • With each match, the engine simply evaluates the pre-parsed formula using current variable values.
  • Conceptually similar to using uCalc.Parse() (Topic 69) and then calling EvaluateStr() (Topic 142) repeatedly.
  • Use this when the formula is constant but the variable values change.

{@@Eval: expression} (Parse Each Time)

This is the high-flexibility mode.

  • The expression is parsed and evaluated every time a match is found.
  • This allows the expression itself (the formula) to be different for each match.
  • Conceptually similar to calling uCalc.EvalStr() (Topic 47) for every match.
  • Use this when the text captured from the source document is the expression you want to solve.

Variable Handling & Content

Captured pattern variables (e.g., {@Number:var}) are accessible inside the evaluator context.

  • In {@Eval}: var refers to the captured text as a literal string. If var captured 1+1, {@Eval: var} returns the string 1+1.
  • In {@@Eval}: var is treated as a string to be evaluated. If var captured 1+1, {@@Eval: var} returns 2.

Variable Syntax

When using variables captured within a pattern (e.g., {@Number:x}), you refer to them by their name directly inside the evaluation string. Do not use additional curly braces.

  • Correct: {@@Eval: x * 2}
  • Incorrect: {@@Eval: {x} * 2}

Result Versatility

The evaluated result can be anything the uCalc engine supports, including numbers, and strings. The engine simply "pastes" the result of the evaluation into the location where the directive was placed.

Text passed to {@Eval} from a pattern variable is passed as a string. If the string contains a value that you want to treat as numeric, you can convert it by casting it, for instance, with double, as in double(MyStr). Variables defined in the parent uCalc object are also available to {@Eval}, in their native type. All results are converted back to a string when inserted into the replacement text (so you don't need to do an extra step for that).

Examples

1. Succinct (Quick Start: Evaluation Logic)

Showing how {@Eval} in a pattern is a one-time operation.

New(uCalc::Transformer, t)// The pattern literally looks for "2" because the Eval happens at definitiont.FromTo("val = {@Eval: 1 + 1}", "MATCH")wl(t.Transform("val = 2"))

[Expected Output]MATCH

2. Practical (Real World: Pre-Parsed Formula)

Using {@Eval} in a replacement for high-performance unit conversion where the formula is fixed.

New(uCalc::Transformer, t)// Formula is parsed once; 'c' value changes per matcht.FromTo("{@Number:c}C", "{@Eval: c * 9 / 5 + 32}F")wl(t.Transform("0C, 100C"))

[Expected Output]32F, 212F

2. Practical (Real World: Dynamic Discounting)

Calculating a 15% discount on a captured price value found in the source text.

New(uCalc::Transformer, t)// Capture 'p' and calculate the discount for every occurrencet.FromTo("Price: {@Number:p}", "Sale Price: {@@Eval: p * 0.85}")var(string, input) = "Price: 100, Price: 200"wl(t.Transform(input))

[Expected Output]Sale Price: 85, Sale Price: 170

3. Internal Test (Meta-Expression Evaluation)

Using {@@Eval} to solve a math problem that was captured as text from the source document.

New(uCalc::Transformer, t)// Capture the text '1+1' into 'v't.FromTo("solve: {v}", "Result: {@@Eval: v}")// {@@Eval} parses the string "1+1" and evaluates it to 2.// {@Eval: v} would have just returned the string "1+1".wl(t.Transform("solve: 1+1"))

[Expected Output]Result: 2

Strategy & Critique

  • Performance Choice: Developers should default to {@Eval} in replacements for speed, unless they explicitly need to evaluate strings captured from the source code as formulas.
  • Expression Persistence: Master the concept that {@Eval} keeps the formula constant while {@@Eval} allows the formula to be dynamic.
  • Lenient Typing: Both versions are lenient with input types, but {@@Eval} is specifically designed to handle "code-as-data" scenarios.

Current Time: Wednesday, January 14, 2026 at 3:11 PM EST.

Examples

				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

// Define the pattern first
t.FromTo("Temperature: {temp} C", "temperature: {@Eval: Double(temp) * 1.8 + 32} F");

// Perform the Transform() operation
Console.WriteLine(t.Transform("Here is the temperature: 22.5 C"));
				
			
Here is the temperature: 72.5 F
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   // Define the pattern first
   t.FromTo("Temperature: {temp} C", "temperature: {@Eval: Double(temp) * 1.8 + 32} F");

   // Perform the Transform() operation
   cout << t.Transform("Here is the temperature: 22.5 C") << endl;
}
				
			
Here is the temperature: 72.5 F
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      '// Define the pattern first
      t.FromTo("Temperature: {temp} C", "temperature: {@Eval: Double(temp) * 1.8 + 32} F")
      
      '// Perform the Transform() operation
      Console.WriteLine(t.Transform("Here is the temperature: 22.5 C"))
   End Sub
End Module
				
			
Here is the temperature: 72.5 F
{@Eval}, {@@Eval}, and escaping special characters in a pattern
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

t.FromTo("'['{word}']'", "{@Eval: UCase(word)}");
t.FromTo("'{'{expr}'}'", "{@@Eval: expr}");

Console.WriteLine(t.Transform("Words like [this] and [that]."));
Console.WriteLine(t.Transform("Is {5*3} bigger than {5^3}?"));
				
			
Words like THIS and THAT.
Is 15 bigger than 125?
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   t.FromTo("'['{word}']'", "{@Eval: UCase(word)}");
   t.FromTo("'{'{expr}'}'", "{@@Eval: expr}");

   cout << t.Transform("Words like [this] and [that].") << endl;
   cout << t.Transform("Is {5*3} bigger than {5^3}?") << endl;
}
				
			
Words like THIS and THAT.
Is 15 bigger than 125?
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("'['{word}']'", "{@Eval: UCase(word)}")
      t.FromTo("'{'{expr}'}'", "{@@Eval: expr}")
      
      Console.WriteLine(t.Transform("Words like [this] and [that]."))
      Console.WriteLine(t.Transform("Is {5*3} bigger than {5^3}?"))
   End Sub
End Module
				
			
Words like THIS and THAT.
Is 15 bigger than 125?
Previous
Next