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.

ValueStr(bool)

Method

Product: 

Fast Math Parser

Class: 

Item

Retrieves the value of a uCalc item as a string, with optional custom formatting, converting from any data type.

Syntax

ValueStr(bool)

Parameters

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

Return

string

The string representation of the item's value.

Remarks

The ValueStr() method is the universal accessor for retrieving the value of any Item as a string. It serves two primary functions: converting any data type to its string representation and optionally applying a sophisticated, user-defined formatting pipeline.

Universal Type Conversion

This method acts as a robust, all-purpose converter. Unlike type-specific getters (e.g., ValueInt32, ValueDbl), ValueStr() works on an item of any data type, automatically handling the conversion to a human-readable string. This makes it the ideal choice for logging, debugging, and displaying values in a user interface.

The Formatting Pipeline

The formatOutput parameter is a powerful switch that controls whether the string result is processed by uCalc's formatting engine.

  • ValueStr(false) (Default): Returns the raw, default string representation of the value (e.g., a number like 99.5).
  • ValueStr(true): Passes the raw string through the formatting pipeline defined by uCalc.Format. This allows for centralized and declarative control over output appearance, such as formatting numbers as currency ($99.50) or dates into a specific layout.

Comparative Analysis

  • vs. C# .ToString() / C++ std::to_string: While similar in purpose, ValueStr is more versatile. Standard library functions typically require the developer to apply formatting imperatively at every call site (e.g., value.ToString("C2")). uCalc's model is declarative: you define the formatting rules once with uCalc.Format, and ValueStr(true) applies them automatically everywhere, separating the presentation logic from the data retrieval logic.

  • vs. other Value... methods: Methods like Value() or ValueInt32() return raw data types for computational use. ValueStr() is specifically for presentation and display. It is the only Value accessor that supports the custom formatting pipeline.

Examples

Using ValueStr()
				
					using uCalcSoftware;

var uc = new uCalc();
var MyStr = uc.DefineVariable("MyStr As String");
var MyDbl = uc.DefineVariable("MyDbl As Double");
var MyCplx = uc.DefineVariable("MyCplx As Complex");
var MyBool = uc.DefineVariable("MyBool As Boolean");

MyStr.ValueStr("Hello world!");
MyDbl.ValueStr("123.456");
MyCplx.ValueStr("3+4*#i");
MyBool.ValueStr("True");

Console.WriteLine(uc.EvalStr("$'MyStr = {MyStr}'"));
Console.WriteLine(uc.EvalStr("$'MyDbl = {MyDbl}'"));
Console.WriteLine(uc.EvalStr("$'MyCplx = {MyCplx}'"));
Console.WriteLine(uc.EvalStr("$'MyBool = {MyBool}'"));
Console.WriteLine("---");
Console.WriteLine(MyStr.ValueStr());
Console.WriteLine(MyDbl.ValueStr());
Console.WriteLine(MyCplx.ValueStr());
Console.WriteLine(MyBool.ValueStr());
				
			
MyStr = Hello world!
MyDbl = 123.456
MyCplx = 3+4i
MyBool = true
---
Hello world!
123.456
3+4i
true
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto MyStr = uc.DefineVariable("MyStr As String");
   auto MyDbl = uc.DefineVariable("MyDbl As Double");
   auto MyCplx = uc.DefineVariable("MyCplx As Complex");
   auto MyBool = uc.DefineVariable("MyBool As Boolean");

   MyStr.ValueStr("Hello world!");
   MyDbl.ValueStr("123.456");
   MyCplx.ValueStr("3+4*#i");
   MyBool.ValueStr("True");

   cout << uc.EvalStr("$'MyStr = {MyStr}'") << endl;
   cout << uc.EvalStr("$'MyDbl = {MyDbl}'") << endl;
   cout << uc.EvalStr("$'MyCplx = {MyCplx}'") << endl;
   cout << uc.EvalStr("$'MyBool = {MyBool}'") << endl;
   cout << "---" << endl;
   cout << MyStr.ValueStr() << endl;
   cout << MyDbl.ValueStr() << endl;
   cout << MyCplx.ValueStr() << endl;
   cout << MyBool.ValueStr() << endl;
}
				
			
MyStr = Hello world!
MyDbl = 123.456
MyCplx = 3+4i
MyBool = true
---
Hello world!
123.456
3+4i
true
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim MyStr = uc.DefineVariable("MyStr As String")
      Dim MyDbl = uc.DefineVariable("MyDbl As Double")
      Dim MyCplx = uc.DefineVariable("MyCplx As Complex")
      Dim MyBool = uc.DefineVariable("MyBool As Boolean")
      
      MyStr.ValueStr("Hello world!")
      MyDbl.ValueStr("123.456")
      MyCplx.ValueStr("3+4*#i")
      MyBool.ValueStr("True")
      
      Console.WriteLine(uc.EvalStr("$'MyStr = {MyStr}'"))
      Console.WriteLine(uc.EvalStr("$'MyDbl = {MyDbl}'"))
      Console.WriteLine(uc.EvalStr("$'MyCplx = {MyCplx}'"))
      Console.WriteLine(uc.EvalStr("$'MyBool = {MyBool}'"))
      Console.WriteLine("---")
      Console.WriteLine(MyStr.ValueStr())
      Console.WriteLine(MyDbl.ValueStr())
      Console.WriteLine(MyCplx.ValueStr())
      Console.WriteLine(MyBool.ValueStr())
   End Sub
End Module
				
			
MyStr = Hello world!
MyDbl = 123.456
MyCplx = 3+4i
MyBool = true
---
Hello world!
123.456
3+4i
true
EvaluateBool, also ValueStr which converts numeric value to string
				
					using uCalcSoftware;

var uc = new uCalc();

var VariableX = uc.DefineVariable("x");
var ParsedExpr = uc.Parse("x > 3"); // The > operation returns a Boolean instead of the default floating point

for (double x = 1; x <= 5; x++) {
   VariableX.Value(x);
   Console.WriteLine($"x = {VariableX.ValueStr()}  x > 3 is {ParsedExpr.EvaluateBool()}");
}

ParsedExpr.Release();
VariableX.Release();
				
			
x = 1  x > 3 is False
x = 2  x > 3 is False
x = 3  x > 3 is False
x = 4  x > 3 is True
x = 5  x > 3 is True
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

int main() {
   uCalc uc;

   auto VariableX = uc.DefineVariable("x");
   auto ParsedExpr = uc.Parse("x > 3"); // The > operation returns a Boolean instead of the default floating point

   for (double x = 1; x <= 5; x++) {
      VariableX.Value(x);
      cout << "x = " << VariableX.ValueStr() << "  x > 3 is " << tf(ParsedExpr.EvaluateBool()) << endl;
   }

   ParsedExpr.Release();
   VariableX.Release();
}
				
			
x = 1  x > 3 is False
x = 2  x > 3 is False
x = 3  x > 3 is False
x = 4  x > 3 is True
x = 5  x > 3 is True
				
					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 > 3") '// The > operation returns a Boolean instead of the default floating point
      
      For x  As Double = 1 To 5
         VariableX.Value(x)
         Console.WriteLine($"x = {VariableX.ValueStr()}  x > 3 is {ParsedExpr.EvaluateBool()}")
      Next
      
      ParsedExpr.Release()
      VariableX.Release()
   End Sub
End Module
				
			
x = 1  x > 3 is False
x = 2  x > 3 is False
x = 3  x > 3 is False
x = 4  x > 3 is True
x = 5  x > 3 is True
Displaying Integer (Int32) results with Evaluate32
				
					using uCalcSoftware;

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

var ParsedExpr = uc.Parse("x / 2", "Integer"); // Causes output of "x / 2" to convert to an integer

// NOTE: EvaluateInt32 should only be used when Parse() explicitly specifies Integer
// (Or Int, or Int32) as the second argument, or if the expression evaluates to an integer
// (such as evaluating a variable that was explicitly defined as integer;
// other arithmetic operators typically evaluate to Double floating point).

for (double x = 1; x <= 10; x++) {
   VariableX.Value(x);
   Console.WriteLine("x = " + VariableX.ValueStr() + "  Result = " + (ParsedExpr.EvaluateInt32()).ToString());
}

ParsedExpr.Release();
VariableX.Release();
				
			
x = 1  Result = 0
x = 2  Result = 1
x = 3  Result = 1
x = 4  Result = 2
x = 5  Result = 2
x = 6  Result = 3
x = 7  Result = 3
x = 8  Result = 4
x = 9  Result = 4
x = 10  Result = 5
				
					#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 / 2", "Integer"); // Causes output of "x / 2" to convert to an integer

   // NOTE: EvaluateInt32 should only be used when Parse() explicitly specifies Integer
   // (Or Int, or Int32) as the second argument, or if the expression evaluates to an integer
   // (such as evaluating a variable that was explicitly defined as integer;
   // other arithmetic operators typically evaluate to Double floating point).

   for (double x = 1; x <= 10; x++) {
      VariableX.Value(x);
      cout << "x = " + VariableX.ValueStr() + "  Result = " + to_string(ParsedExpr.EvaluateInt32()) << endl;
   }

   ParsedExpr.Release();
   VariableX.Release();
}
				
			
x = 1  Result = 0
x = 2  Result = 1
x = 3  Result = 1
x = 4  Result = 2
x = 5  Result = 2
x = 6  Result = 3
x = 7  Result = 3
x = 8  Result = 4
x = 9  Result = 4
x = 10  Result = 5
				
					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 / 2", "Integer") '// Causes output of "x / 2" to convert to an integer
      
      '// NOTE: EvaluateInt32 should only be used when Parse() explicitly specifies Integer
      '// (Or Int, or Int32) as the second argument, or if the expression evaluates to an integer
      '// (such as evaluating a variable that was explicitly defined as integer;
      '// other arithmetic operators typically evaluate to Double floating point).
      
      For x  As Double = 1 To 10
         VariableX.Value(x)
         Console.WriteLine("x = " + VariableX.ValueStr() + "  Result = " + (ParsedExpr.EvaluateInt32()).ToString())
      Next
      
      ParsedExpr.Release()
      VariableX.Release()
   End Sub
End Module
				
			
x = 1  Result = 0
x = 2  Result = 1
x = 3  Result = 1
x = 4  Result = 2
x = 5  Result = 2
x = 6  Result = 3
x = 7  Result = 3
x = 8  Result = 4
x = 9  Result = 4
x = 10  Result = 5
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