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.

EvaluateStr

Method

Product: 

Fast Math Parser

Class: 

Expression

Evaluates a pre-parsed expression and returns the result of any data type as a string.

Syntax

EvaluateStr(bool)

Parameters

returnFormatted
bool
(Default = true)
If true, the output string is processed by any custom formatters defined with uCalc.Format(). If false, the raw, unformatted string representation of the result is returned.

Return

string

A string containing the formatted or raw result of the evaluation. If an error occurs, the string contains the error message.

Remarks

The EvaluateStr method executes a pre-compiled Expression object and returns the result as a string. It is the second step in the recommended two-step process for high-performance evaluation: Parse once, EvaluateStr many times.

This method is the most versatile way to get a display-ready result, as it correctly handles all data types and can apply custom formatting rules.

💡 EvaluateStr vs. Evaluate

While both methods execute a parsed expression, they serve different purposes. Use this table to decide which is appropriate for your use case:

FeatureEvaluateStr()Evaluate()
Return Typestringdouble
Supported Data TypesAll (Numeric, String, Complex, Bool, etc.)Numeric types (or those convertible to double)
Error HandlingSafely returns the error message as a string.Returns NaN or Infinity; requires checking Error.Code.
Primary Use CaseDisplaying results to a user, handling any return type.High-speed, numeric-only calculations in loops.

🎨 Output Formatting

The returnFormatted parameter provides powerful control over the output string:

  • true (Default): The result is processed through the formatting pipeline. Any rules defined with uCalc.Format() that match the result's data type will be applied. This is ideal for consistently styling output, such as adding currency symbols or normalizing date formats.
  • false: The formatting pipeline is bypassed, and the raw, default string representation of the result is returned.

This allows you to separate calculation logic from presentation logic cleanly.

Comparative Analysis

  • vs. Native .ToString(): In languages like C#, every object has a .ToString() method. However, EvaluateStr is superior because it is context-aware. It leverages the formatting rules defined within its parent uCalc instance, allowing for dynamic and centralized control over application-wide output styles that a simple .ToString() call cannot achieve.

  • vs. eval() in Scripting Languages: Unlike the eval() function in languages like JavaScript or Python, which can execute arbitrary code and pose a security risk, EvaluateStr operates within a secure sandbox. It can only execute functions and access variables that have been explicitly defined in its uCalc instance, preventing code injection vulnerabilities.

  • vs. uCalc.EvalStr(): It's important to distinguish between the two EvalStr methods. uCalc.EvalStr() is a one-step convenience function that takes a raw string, parses it, and evaluates it. Expression.EvaluateStr() is the high-performance version that operates on an already-parsed object, avoiding the cost of re-parsing in loops.

Examples

Displaying strings with EvaluateStr()
				
					using uCalcSoftware;

var uc = new uCalc();
var VariableX = uc.DefineVariable("x As Int32");
var MyStringVar = uc.DefineVariable("MyString = 'Hello world'");
var ParsedExpr = uc.Parse("SubStr(MyString, x, 1)");
var StrLength = uc.Eval("Length(MyString)");

for (int x = 0; x <= uc.Eval("Length(MyString) - 1"); x++) {
   VariableX.ValueInt32(x);
   Console.Write(ParsedExpr.EvaluateStr() + ".");
}
				
			
H.e.l.l.o. .w.o.r.l.d.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto VariableX = uc.DefineVariable("x As Int32");
   auto MyStringVar = uc.DefineVariable("MyString = 'Hello world'");
   auto ParsedExpr = uc.Parse("SubStr(MyString, x, 1)");
   auto StrLength = uc.Eval("Length(MyString)");

   for (int x = 0; x <= uc.Eval("Length(MyString) - 1"); x++) {
      VariableX.ValueInt32(x);
      cout << ParsedExpr.EvaluateStr() + ".";
   }
}
				
			
H.e.l.l.o. .w.o.r.l.d.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim VariableX = uc.DefineVariable("x As Int32")
      Dim MyStringVar = uc.DefineVariable("MyString = 'Hello world'")
      Dim ParsedExpr = uc.Parse("SubStr(MyString, x, 1)")
      Dim StrLength = uc.Eval("Length(MyString)")
      
      For x  As Integer = 0 To uc.Eval("Length(MyString) - 1")
         VariableX.ValueInt32(x)
         Console.Write(ParsedExpr.EvaluateStr() + ".")
      Next
   End Sub
End Module
				
			
H.e.l.l.o. .w.o.r.l.d.
Displaying complex number outputs with EvaluateStr()
				
					using uCalcSoftware;

var uc = new uCalc();
var VariableX = uc.DefineVariable("x");
var ParsedExpr = uc.Parse("x * #i + 5", "Complex");

for (double x = 1; x <= 10; x++) {
   VariableX.Value(x);
   // Note: EvaluateStr works with any data type;
   Console.WriteLine(uc.EvalStr("$'x = {x}  Result = '") + ParsedExpr.EvaluateStr());
}

ParsedExpr.Release();
VariableX.Release();
				
			
x = 1  Result = 5+1i
x = 2  Result = 5+2i
x = 3  Result = 5+3i
x = 4  Result = 5+4i
x = 5  Result = 5+5i
x = 6  Result = 5+6i
x = 7  Result = 5+7i
x = 8  Result = 5+8i
x = 9  Result = 5+9i
x = 10  Result = 5+10i
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto VariableX = uc.DefineVariable("x");
   auto ParsedExpr = uc.Parse("x * #i + 5", "Complex");

   for (double x = 1; x <= 10; x++) {
      VariableX.Value(x);
      // Note: EvaluateStr works with any data type;
      cout << uc.EvalStr("$'x = {x}  Result = '") + ParsedExpr.EvaluateStr() << endl;
   }

   ParsedExpr.Release();
   VariableX.Release();
}
				
			
x = 1  Result = 5+1i
x = 2  Result = 5+2i
x = 3  Result = 5+3i
x = 4  Result = 5+4i
x = 5  Result = 5+5i
x = 6  Result = 5+6i
x = 7  Result = 5+7i
x = 8  Result = 5+8i
x = 9  Result = 5+9i
x = 10  Result = 5+10i
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim VariableX = uc.DefineVariable("x")
      Dim ParsedExpr = uc.Parse("x * #i + 5", "Complex")
      
      For x  As Double = 1 To 10
         VariableX.Value(x)
         '// Note: EvaluateStr works with any data type;
         Console.WriteLine(uc.EvalStr("$'x = {x}  Result = '") + ParsedExpr.EvaluateStr())
      Next
      
      ParsedExpr.Release()
      VariableX.Release()
   End Sub
End Module
				
			
x = 1  Result = 5+1i
x = 2  Result = 5+2i
x = 3  Result = 5+3i
x = 4  Result = 5+4i
x = 5  Result = 5+5i
x = 6  Result = 5+6i
x = 7  Result = 5+7i
x = 8  Result = 5+8i
x = 9  Result = 5+9i
x = 10  Result = 5+10i
DefineVariable examples
				
					using uCalcSoftware;

var uc = new uCalc();
var MyVar = uc.DefineVariable("MyVar");
var MyInt = uc.DefineVariable("MyInt As Int");
var MyStr = uc.DefineVariable("MyStr As String");
uc.DefineVariable("OtherStr = 'string type inferred'");
uc.DefineVariable("MyInt16 = Int16(100/3)"); // type inferred
uc.DefineVariable("MyBool = True"); // type inferred
uc.DefineVariable("MyComplex = 3 + 4*#i"); // type inferred

MyVar.Value(123);
MyInt.ValueInt32(456);
MyStr.ValueStr("This is a test");

Console.WriteLine("MyVar = " + uc.EvalStr("MyVar"));
Console.WriteLine("MyInt = " + uc.EvalStr("MyInt"));
Console.WriteLine("MyStr = " + uc.EvalStr("MyStr"));
Console.WriteLine("OtherStr = " + uc.EvalStr("OtherStr"));
Console.WriteLine("MyInt16 = " + uc.EvalStr("MyInt16"));
Console.WriteLine("MyBool = " + uc.EvalStr("MyBool"));
Console.WriteLine("MyComplex = " + uc.EvalStr("MyComplex"));
Console.WriteLine("---");
Console.WriteLine(MyVar.Value());
Console.WriteLine(MyInt.ValueInt32());
Console.WriteLine(MyStr.ValueStr());
Console.WriteLine("---");
Console.WriteLine(uc.ItemOf("MyVar").DataType.Name);
Console.WriteLine(uc.ItemOf("MyInt").DataType.Name);
Console.WriteLine(uc.ItemOf("MyStr").DataType.Name);
Console.WriteLine(uc.ItemOf("OtherStr").DataType.Name);
Console.WriteLine(uc.ItemOf("MyInt16").DataType.Name);
Console.WriteLine(uc.ItemOf("MyBool").DataType.Name);
Console.WriteLine("---");

var Expression = "x^2 * 10";
var VarX = uc.DefineVariable("x");
var ParsedExpr = uc.Parse(Expression);

Console.Write("Expression = ");
Console.WriteLine(Expression);
for (int x = 1; x <= 10; x++) {
   VarX.Value(x); // In C++ you can skip this by passing &x to DefineVariable
   Console.WriteLine("x = " + VarX.ValueStr() + "  Result = " + ParsedExpr.EvaluateStr());
}

ParsedExpr.Release();
VarX.Release();
				
			
MyVar = 123
MyInt = 456
MyStr = This is a test
OtherStr = string type inferred
MyInt16 = 33
MyBool = true
MyComplex = 3+4i
---
123
456
This is a test
---
double
int
string
string
int16
bool
---
Expression = x^2 * 10
x = 1  Result = 10
x = 2  Result = 40
x = 3  Result = 90
x = 4  Result = 160
x = 5  Result = 250
x = 6  Result = 360
x = 7  Result = 490
x = 8  Result = 640
x = 9  Result = 810
x = 10  Result = 1000
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto MyVar = uc.DefineVariable("MyVar");
   auto MyInt = uc.DefineVariable("MyInt As Int");
   auto MyStr = uc.DefineVariable("MyStr As String");
   uc.DefineVariable("OtherStr = 'string type inferred'");
   uc.DefineVariable("MyInt16 = Int16(100/3)"); // type inferred
   uc.DefineVariable("MyBool = True"); // type inferred
   uc.DefineVariable("MyComplex = 3 + 4*#i"); // type inferred

   MyVar.Value(123);
   MyInt.ValueInt32(456);
   MyStr.ValueStr("This is a test");

   cout << "MyVar = " + uc.EvalStr("MyVar") << endl;
   cout << "MyInt = " + uc.EvalStr("MyInt") << endl;
   cout << "MyStr = " + uc.EvalStr("MyStr") << endl;
   cout << "OtherStr = " + uc.EvalStr("OtherStr") << endl;
   cout << "MyInt16 = " + uc.EvalStr("MyInt16") << endl;
   cout << "MyBool = " + uc.EvalStr("MyBool") << endl;
   cout << "MyComplex = " + uc.EvalStr("MyComplex") << endl;
   cout << "---" << endl;
   cout << MyVar.Value() << endl;
   cout << MyInt.ValueInt32() << endl;
   cout << MyStr.ValueStr() << endl;
   cout << "---" << endl;
   cout << uc.ItemOf("MyVar").DataType().Name() << endl;
   cout << uc.ItemOf("MyInt").DataType().Name() << endl;
   cout << uc.ItemOf("MyStr").DataType().Name() << endl;
   cout << uc.ItemOf("OtherStr").DataType().Name() << endl;
   cout << uc.ItemOf("MyInt16").DataType().Name() << endl;
   cout << uc.ItemOf("MyBool").DataType().Name() << endl;
   cout << "---" << endl;

   auto Expression = "x^2 * 10";
   auto VarX = uc.DefineVariable("x");
   auto ParsedExpr = uc.Parse(Expression);

   cout << "Expression = ";
   cout << Expression << endl;
   for (int x = 1; x <= 10; x++) {
      VarX.Value(x); // In C++ you can skip this by passing &x to DefineVariable
      cout << "x = " + VarX.ValueStr() + "  Result = " + ParsedExpr.EvaluateStr() << endl;
   }

   ParsedExpr.Release();
   VarX.Release();
}
				
			
MyVar = 123
MyInt = 456
MyStr = This is a test
OtherStr = string type inferred
MyInt16 = 33
MyBool = true
MyComplex = 3+4i
---
123
456
This is a test
---
double
int
string
string
int16
bool
---
Expression = x^2 * 10
x = 1  Result = 10
x = 2  Result = 40
x = 3  Result = 90
x = 4  Result = 160
x = 5  Result = 250
x = 6  Result = 360
x = 7  Result = 490
x = 8  Result = 640
x = 9  Result = 810
x = 10  Result = 1000
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim MyVar = uc.DefineVariable("MyVar")
      Dim MyInt = uc.DefineVariable("MyInt As Int")
      Dim MyStr = uc.DefineVariable("MyStr As String")
      uc.DefineVariable("OtherStr = 'string type inferred'")
      uc.DefineVariable("MyInt16 = Int16(100/3)") '// type inferred
      uc.DefineVariable("MyBool = True") '// type inferred
      uc.DefineVariable("MyComplex = 3 + 4*#i") '// type inferred
      
      MyVar.Value(123)
      MyInt.ValueInt32(456)
      MyStr.ValueStr("This is a test")
      
      Console.WriteLine("MyVar = " + uc.EvalStr("MyVar"))
      Console.WriteLine("MyInt = " + uc.EvalStr("MyInt"))
      Console.WriteLine("MyStr = " + uc.EvalStr("MyStr"))
      Console.WriteLine("OtherStr = " + uc.EvalStr("OtherStr"))
      Console.WriteLine("MyInt16 = " + uc.EvalStr("MyInt16"))
      Console.WriteLine("MyBool = " + uc.EvalStr("MyBool"))
      Console.WriteLine("MyComplex = " + uc.EvalStr("MyComplex"))
      Console.WriteLine("---")
      Console.WriteLine(MyVar.Value())
      Console.WriteLine(MyInt.ValueInt32())
      Console.WriteLine(MyStr.ValueStr())
      Console.WriteLine("---")
      Console.WriteLine(uc.ItemOf("MyVar").DataType.Name)
      Console.WriteLine(uc.ItemOf("MyInt").DataType.Name)
      Console.WriteLine(uc.ItemOf("MyStr").DataType.Name)
      Console.WriteLine(uc.ItemOf("OtherStr").DataType.Name)
      Console.WriteLine(uc.ItemOf("MyInt16").DataType.Name)
      Console.WriteLine(uc.ItemOf("MyBool").DataType.Name)
      Console.WriteLine("---")
      
      Dim Expression = "x^2 * 10"
      Dim VarX = uc.DefineVariable("x")
      Dim ParsedExpr = uc.Parse(Expression)
      
      Console.Write("Expression = ")
      Console.WriteLine(Expression)
      For x  As Integer = 1 To 10
         VarX.Value(x) '// In C++ you can skip this by passing &x to DefineVariable
         Console.WriteLine("x = " + VarX.ValueStr() + "  Result = " + ParsedExpr.EvaluateStr())
      Next
      
      ParsedExpr.Release()
      VarX.Release()
   End Sub
End Module
				
			
MyVar = 123
MyInt = 456
MyStr = This is a test
OtherStr = string type inferred
MyInt16 = 33
MyBool = true
MyComplex = 3+4i
---
123
456
This is a test
---
double
int
string
string
int16
bool
---
Expression = x^2 * 10
x = 1  Result = 10
x = 2  Result = 40
x = 3  Result = 90
x = 4  Result = 160
x = 5  Result = 250
x = 6  Result = 360
x = 7  Result = 490
x = 8  Result = 640
x = 9  Result = 810
x = 10  Result = 1000
Previous
Next