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.

EvalStr

Method

Product: 

Fast Math Parser

Class: 

uCalcBase

Parses and evaluates an expression in a single step, returning the result of any data type as a string.

Syntax

EvalStr(string, bool)

Parameters

expression
string
Expression to be evaluated
returnFormatted
bool
(Default = true)
If true, the output string is processed by any defined formatters. If false, the raw, unformatted string representation is returned.

Return

string

A string containing the formatted or raw result of the evaluation, or an error message if the expression is invalid.

Remarks

The EvalStr method is a versatile, one-step function that parses and evaluates an expression, returning the result as a string. It is the most convenient way to get a display-ready result from user input, as it handles any data type and can automatically apply custom formatting.

This method is a high-level convenience wrapper around the two-step process of using uCalc.Parse followed by Expression.EvaluateStr.

💡 Key Features

  • Universal Type Support: Unlike its counterpart uCalc.Eval, which is optimized for and returns a double, EvalStr works with any data type defined in uCalc, including String, Complex, Boolean, and user-defined types.
  • Safe Error Handling: If a syntax or evaluation error occurs (like a typo or division by zero), EvalStr does not throw an exception. Instead, it safely returns the error message as a string, making it ideal for processing raw user input without needing complex try-catch blocks.
  • Automatic Formatting: The result can be automatically passed through any defined output formatters, controlled by the returnFormatted parameter.

Eval vs. EvalStr

FeatureEval(string)EvalStr(string)
Return Typedoublestring
Supported TypesNumeric types (or types convertible to double)All data types
Use CaseNumeric calculationsGeneral-purpose evaluation, user-facing output, non-numeric results
Error HandlingReturns NaN or Infinity; inspect with Error.CodeReturns the error message as a string

🎨 Output Formatting

The returnFormatted parameter determines whether custom format rules are applied.

  • When true (default), the result is processed by formatters defined with uCalc.Format. This is useful for consistently formatting values, such as adding currency symbols or scientific notation.
  • When false, the method returns the raw, default string representation of the result.

Comparative Analysis

vs. eval() in Scripting Languages (JavaScript, Python)While functionally similar, uCalc's EvalStr is vastly more secure. Scripting language eval() functions can often execute arbitrary code, creating significant security vulnerabilities (code injection). EvalStr operates within a sandboxed environment defined by your uCalc instance; it can only execute the functions, operators, and variables you have explicitly defined and cannot interact with the host system's file system, network, or other resources without being given explicit access.

vs. Manual Parsing in C++/C#Implementing a robust expression evaluator from scratch is a complex task involving tokenization, abstract syntax tree (AST) construction, type checking, and evaluation logic. EvalStr abstracts all this complexity into a single, powerful function call, dramatically reducing development time and potential for bugs.

Examples

Demonstrates basic, one-line evaluations for numeric, string, and boolean expressions.
				
					using uCalcSoftware;

var uc = new uCalc();
// Basic arithmetic
Console.WriteLine(uc.EvalStr("15 * (4 + 3)"));
// String manipulation
Console.WriteLine(uc.EvalStr("UCase('hello') + ', world!'"));
// Boolean logic
Console.WriteLine(uc.EvalStr("10 > 5 AndAlso 'a' < 'b'"));
				
			
105
HELLO, world!
true
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Basic arithmetic
   cout << uc.EvalStr("15 * (4 + 3)") << endl;
   // String manipulation
   cout << uc.EvalStr("UCase('hello') + ', world!'") << endl;
   // Boolean logic
   cout << uc.EvalStr("10 > 5 AndAlso 'a' < 'b'") << endl;
}
				
			
105
HELLO, world!
true
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Basic arithmetic
      Console.WriteLine(uc.EvalStr("15 * (4 + 3)"))
      '// String manipulation
      Console.WriteLine(uc.EvalStr("UCase('hello') + ', world!'"))
      '// Boolean logic
      Console.WriteLine(uc.EvalStr("10 > 5 AndAlso 'a' < 'b'"))
   End Sub
End Module
				
			
105
HELLO, world!
true
Calculates a total price using predefined variables and demonstrates the effect of output formatting.
				
					using uCalcSoftware;

var uc = new uCalc();
// Define some context for the expression
uc.DefineVariable("price = 49.99");
uc.DefineVariable("quantity = 3");
uc.DefineConstant("TAX_RATE = 0.0825");

// Define a format for currency output
uc.Format("DataType: Double, Def: result = '$' + result");

// Expression to calculate total price, using variables
var expression = "price * quantity * (1 + TAX_RATE)";

// Evaluate with formatting enabled
Console.WriteLine($"Formatted Total: {uc.EvalStr(expression, true)}");

// Evaluate with formatting disabled
Console.WriteLine($"Raw Total: {uc.EvalStr(expression, false)}");
				
			
Formatted Total: $162.342525
Raw Total: 162.342525
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Define some context for the expression
   uc.DefineVariable("price = 49.99");
   uc.DefineVariable("quantity = 3");
   uc.DefineConstant("TAX_RATE = 0.0825");

   // Define a format for currency output
   uc.Format("DataType: Double, Def: result = '$' + result");

   // Expression to calculate total price, using variables
   auto expression = "price * quantity * (1 + TAX_RATE)";

   // Evaluate with formatting enabled
   cout << "Formatted Total: " << uc.EvalStr(expression, true) << endl;

   // Evaluate with formatting disabled
   cout << "Raw Total: " << uc.EvalStr(expression, false) << endl;
}
				
			
Formatted Total: $162.342525
Raw Total: 162.342525
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Define some context for the expression
      uc.DefineVariable("price = 49.99")
      uc.DefineVariable("quantity = 3")
      uc.DefineConstant("TAX_RATE = 0.0825")
      
      '// Define a format for currency output
      uc.Format("DataType: Double, Def: result = '$' + result")
      
      '// Expression to calculate total price, using variables
      Dim expression = "price * quantity * (1 + TAX_RATE)"
      
      '// Evaluate with formatting enabled
      Console.WriteLine($"Formatted Total: {uc.EvalStr(expression, true)}")
      
      '// Evaluate with formatting disabled
      Console.WriteLine($"Raw Total: {uc.EvalStr(expression, false)}")
   End Sub
End Module
				
			
Formatted Total: $162.342525
Raw Total: 162.342525
Evaluating expressions returned as string
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineVariable("x = 123");
uc.DefineVariable("y");

Console.WriteLine(uc.EvalStr("1 + 1"));
Console.WriteLine(uc.EvalStr("UCase('Hello ' + 'world!')"));
Console.WriteLine(uc.EvalStr("$'Interpolation: {2+3}'"));
Console.WriteLine(uc.EvalStr("#b101 + #hAE"));
Console.WriteLine(uc.EvalStr("Hex(1234)"));
Console.WriteLine(uc.EvalStr("(3+5*#i)^2"));
Console.WriteLine(uc.EvalStr("3 > 4"));
Console.WriteLine(uc.EvalStr("Max(5, 10, 3, -5)"));
Console.WriteLine(uc.EvalStr("x * 10"));
uc.EvalStr("x = 456");
Console.WriteLine(uc.EvalStr("x"));
Console.WriteLine(uc.EvalStr("2+4, 5+4, 10+20"));
Console.WriteLine(uc.EvalStr("y=100; ForLoop(x, 1, 10, 1, y = y + x); y"));
Console.WriteLine(uc.EvalStr("10 / "));
				
			
2
HELLO WORLD!
Interpolation: 5
179
4d2
-16+30i
false
10
1230
456
30
155
Syntax error
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineVariable("x = 123");
   uc.DefineVariable("y");

   cout << uc.EvalStr("1 + 1") << endl;
   cout << uc.EvalStr("UCase('Hello ' + 'world!')") << endl;
   cout << uc.EvalStr("$'Interpolation: {2+3}'") << endl;
   cout << uc.EvalStr("#b101 + #hAE") << endl;
   cout << uc.EvalStr("Hex(1234)") << endl;
   cout << uc.EvalStr("(3+5*#i)^2") << endl;
   cout << uc.EvalStr("3 > 4") << endl;
   cout << uc.EvalStr("Max(5, 10, 3, -5)") << endl;
   cout << uc.EvalStr("x * 10") << endl;
   uc.EvalStr("x = 456");
   cout << uc.EvalStr("x") << endl;
   cout << uc.EvalStr("2+4, 5+4, 10+20") << endl;
   cout << uc.EvalStr("y=100; ForLoop(x, 1, 10, 1, y = y + x); y") << endl;
   cout << uc.EvalStr("10 / ") << endl;
}
				
			
2
HELLO WORLD!
Interpolation: 5
179
4d2
-16+30i
false
10
1230
456
30
155
Syntax error
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("x = 123")
      uc.DefineVariable("y")
      
      Console.WriteLine(uc.EvalStr("1 + 1"))
      Console.WriteLine(uc.EvalStr("UCase('Hello ' + 'world!')"))
      Console.WriteLine(uc.EvalStr("$'Interpolation: {2+3}'"))
      Console.WriteLine(uc.EvalStr("#b101 + #hAE"))
      Console.WriteLine(uc.EvalStr("Hex(1234)"))
      Console.WriteLine(uc.EvalStr("(3+5*#i)^2"))
      Console.WriteLine(uc.EvalStr("3 > 4"))
      Console.WriteLine(uc.EvalStr("Max(5, 10, 3, -5)"))
      Console.WriteLine(uc.EvalStr("x * 10"))
      uc.EvalStr("x = 456")
      Console.WriteLine(uc.EvalStr("x"))
      Console.WriteLine(uc.EvalStr("2+4, 5+4, 10+20"))
      Console.WriteLine(uc.EvalStr("y=100; ForLoop(x, 1, 10, 1, y = y + x); y"))
      Console.WriteLine(uc.EvalStr("10 / "))
   End Sub
End Module
				
			
2
HELLO WORLD!
Interpolation: 5
179
4d2
-16+30i
false
10
1230
456
30
155
Syntax error
How to perform a summation in a loop efficiently using Execute() instead of Evaluate().
				
					using uCalcSoftware;

var uc = new uCalc();
var VariableX = uc.DefineVariable("x = 0");
var Total = uc.DefineVariable("Total");
string Expression = "x++; Total = Total + x^2 + 5";

var ParsedExpr = uc.Parse(Expression);

for (double x = 1; x <= 10; x++) {
   // Execute() runs the parsed expression without the overhead of returning a value.
   // This provides near-native performance for loops across C#, VB, and C++.
   ParsedExpr.Execute();

   // Evaluate string interpolation to output the final calculated total
   Console.WriteLine(uc.EvalStr("$'{x}   Sub total = {Total}'"));
}

Console.WriteLine(uc.EvalStr("$'Total = {Total}'"));

ParsedExpr.Release();
VariableX.Release();
				
			
1   Sub total = 6
2   Sub total = 15
3   Sub total = 29
4   Sub total = 50
5   Sub total = 80
6   Sub total = 121
7   Sub total = 175
8   Sub total = 244
9   Sub total = 330
10   Sub total = 435
Total = 435
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto VariableX = uc.DefineVariable("x = 0");
   auto Total = uc.DefineVariable("Total");
   string Expression = "x++; Total = Total + x^2 + 5";

   auto ParsedExpr = uc.Parse(Expression);

   for (double x = 1; x <= 10; x++) {
      // Execute() runs the parsed expression without the overhead of returning a value.
      // This provides near-native performance for loops across C#, VB, and C++.
      ParsedExpr.Execute();

      // Evaluate string interpolation to output the final calculated total
      cout << uc.EvalStr("$'{x}   Sub total = {Total}'") << endl;
   }

   cout << uc.EvalStr("$'Total = {Total}'") << endl;

   ParsedExpr.Release();
   VariableX.Release();
}
				
			
1   Sub total = 6
2   Sub total = 15
3   Sub total = 29
4   Sub total = 50
5   Sub total = 80
6   Sub total = 121
7   Sub total = 175
8   Sub total = 244
9   Sub total = 330
10   Sub total = 435
Total = 435
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim VariableX = uc.DefineVariable("x = 0")
      Dim Total = uc.DefineVariable("Total")
      Dim Expression As String = "x++; Total = Total + x^2 + 5"
      
      Dim ParsedExpr = uc.Parse(Expression)
      
      For x  As Double = 1 To 10
         '// Execute() runs the parsed expression without the overhead of returning a value.
         '// This provides near-native performance for loops across C#, VB, and C++.
         ParsedExpr.Execute()
         
         '// Evaluate string interpolation to output the final calculated total
         Console.WriteLine(uc.EvalStr("$'{x}   Sub total = {Total}'"))
      Next
      
      Console.WriteLine(uc.EvalStr("$'Total = {Total}'"))
      
      ParsedExpr.Release()
      VariableX.Release()
   End Sub
End Module
				
			
1   Sub total = 6
2   Sub total = 15
3   Sub total = 29
4   Sub total = 50
5   Sub total = 80
6   Sub total = 121
7   Sub total = 175
8   Sub total = 244
9   Sub total = 330
10   Sub total = 435
Total = 435
Previous
Next