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.

DataType = [DataType]

Property

Product: 

Fast Math Parser

Class: 

Item

Gets/sets the DataType object that defines the type characteristics of the Item.

Remarks

The DataType() method is a core introspection tool that returns the DataType object associated with any given Item. This allows you to programmatically inspect the type of a variable, function, or operator at runtime.

🎯 Purpose and Usage

Every symbol defined in uCalc (e.g., via DefineVariable() or DefineFunction()) is represented by an Item object. This method allows you to query that Item to understand its underlying data type. The returned DataType object provides access to key metadata, including:

  • Name(): The string name of the type (e.g., "double", "string").
  • ByteSize(): The size of the type in bytes.
  • IsCompound(): Whether the type is a simple value (like an int) or a complex structure (like a string or complex number).

This is essential for building dynamic systems, such as a custom script editor or a data validation layer, where you need to check the type of a variable before performing an operation.

💡 Comparative Analysis: uCalc Introspection vs. Native Reflection

In statically-typed languages, reflection is used to inspect types at runtime.

  • In C#: You would use an object's .GetType() method.
  • In C++: You might use typeid or template metaprogramming.

While powerful, these native mechanisms operate on host-language types. uCalc's Item.DataType() is different because it operates on the symbolic types defined within the uCalc engine itself. This provides a consistent and unified way to inspect the type of a uCalc variable, a uCalc function's return value, or a parameter, all through the same simple API. It abstracts away the underlying host language, allowing you to reason about your defined symbols in a platform-agnostic way.

Setter

The DataType method assigns a specific data type to an existing Item, giving it semantic meaning within the uCalc engine. While it can be used on any item, its most critical role is to elevate a custom token from a simple text match into a usable literal value for the expression parser.

🎯 Primary Use Case: Defining Custom Literals

When you define a new token with uCalc.Tokens.Add, you are essentially just defining a regular expression. To make the text captured by that regex usable in an expression (e.g., in a math calculation), you must complete two steps:

  1. Categorize the token as a Literal using TokenType::Literal.
  2. Use this DataType() method on the returned token Item to tell the parser how to interpret that literal's value (e.g., as a String, Double, Int32, etc.).

Without this step, the parser would treat the matched text as an unrecognized symbol. By assigning a data type, you integrate your custom syntax directly into the evaluation engine.

💡 Other Use Cases

While less common, you can also use this method to change the data type of an existing variable. This is a powerful but potentially unsafe operation, as it can affect expressions that were previously parsed and may rely on the variable's original type.

🆚 Why uCalc? (Comparative Analysis)

In traditional compiler development, defining literals is part of a static grammar file processed by a tool like ANTLR or Lex/Flex. The logic to convert the matched text (e.g., "0xFF") into a numeric value is written in a separate, compiled source file.

uCalc's approach is entirely programmatic and dynamic. You can add new literal formats at runtime. Item.DataType() is the bridge that connects your dynamically defined regex pattern to the engine's type system, all without external tools or recompilation. This provides superior flexibility for creating adaptable, user-extendable languages.

Examples

A simple demonstration of retrieving the data type name from a defined variable.
				
					using uCalcSoftware;

var uc = new uCalc();
var myInt = uc.DefineVariable("myInt As Int");
var myIntType = myInt.DataType;
Console.WriteLine($"Variable 'myInt' has type: {myIntType.Name}");
				
			
Variable 'myInt' has type: int
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto myInt = uc.DefineVariable("myInt As Int");
   auto myIntType = myInt.DataType();
   cout << "Variable 'myInt' has type: " << myIntType.Name() << endl;
}
				
			
Variable 'myInt' has type: int
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim myInt = uc.DefineVariable("myInt As Int")
      Dim myIntType = myInt.DataType
      Console.WriteLine($"Variable 'myInt' has type: {myIntType.Name}")
   End Sub
End Module
				
			
Variable 'myInt' has type: int
A practical example showing how to inspect multiple items and display their type properties, distinguishing between simple and compound types.
				
					using uCalcSoftware;

var uc = new uCalc();
var x = uc.DefineVariable("x = 10.5"); // double
var y = uc.DefineVariable("y = 'hello'"); // string
var z = uc.DefineVariable("z As Complex = 1+2*#i"); // complex

Console.WriteLine($"Item: {x.Name}, Type: {x.DataType.Name}, Compound: {x.DataType.IsCompound}");
Console.WriteLine($"Item: {y.Name}, Type: {y.DataType.Name}, Compound: {y.DataType.IsCompound}");
Console.WriteLine($"Item: {z.Name}, Type: {z.DataType.Name}, Compound: {z.DataType.IsCompound}");
				
			
Item: x, Type: double, Compound: False
Item: y, Type: string, Compound: True
Item: z, Type: complex, Compound: True

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

using namespace std;
using namespace uCalcSoftware;

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

int main() {
   uCalc uc;
   auto x = uc.DefineVariable("x = 10.5"); // double
   auto y = uc.DefineVariable("y = 'hello'"); // string
   auto z = uc.DefineVariable("z As Complex = 1+2*#i"); // complex

   cout << "Item: " << x.Name() << ", Type: " << x.DataType().Name() << ", Compound: " << tf(x.DataType().IsCompound()) << endl;
   cout << "Item: " << y.Name() << ", Type: " << y.DataType().Name() << ", Compound: " << tf(y.DataType().IsCompound()) << endl;
   cout << "Item: " << z.Name() << ", Type: " << z.DataType().Name() << ", Compound: " << tf(z.DataType().IsCompound()) << endl;
}
				
			
Item: x, Type: double, Compound: False
Item: y, Type: string, Compound: True
Item: z, Type: complex, Compound: True

				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim x = uc.DefineVariable("x = 10.5") '// double
      Dim y = uc.DefineVariable("y = 'hello'") '// string
      Dim z = uc.DefineVariable("z As Complex = 1+2*#i") '// complex
      
      Console.WriteLine($"Item: {x.Name}, Type: {x.DataType.Name}, Compound: {x.DataType.IsCompound}")
      Console.WriteLine($"Item: {y.Name}, Type: {y.DataType.Name}, Compound: {y.DataType.IsCompound}")
      Console.WriteLine($"Item: {z.Name}, Type: {z.DataType.Name}, Compound: {z.DataType.IsCompound}")
   End Sub
End Module
				
			
Item: x, Type: double, Compound: False
Item: y, Type: string, Compound: True
Item: z, Type: complex, Compound: True
Passing arg ByHandle to retrieve meta data such as arg data type; and AnyType
				
					using uCalcSoftware;

var uc = new uCalc();

static void DisplayArgs(uCalc.Callback cb) {
   for (int x = 1; x <= cb.ArgCount(); x++) {
      Console.WriteLine(cb.ArgItem(x).ValueStr() + "  Type: " + cb.ArgItem(x).DataType.Name);
   }
}

uc.DefineFunction("DisplayArgs(ByHandle Arg As AnyType ...)", DisplayArgs);
uc.Eval("DisplayArgs(5, 3+2*#i, 'Hello', True, False, Int16(5+4.1))");
				
			
5  Type: double
3+2i  Type: complex
Hello  Type: string
true  Type: bool
false  Type: bool
9  Type: int16
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

void ucalc_call DisplayArgs(uCalcBase::Callback cb) {
   for (int x = 1; x <= cb.ArgCount(); x++) {
      cout << cb.ArgItem(x).ValueStr() + "  Type: " + cb.ArgItem(x).DataType().Name() << endl;
   }
}
int main() {
   uCalc uc;
   uc.DefineFunction("DisplayArgs(ByHandle Arg As AnyType ...)", DisplayArgs);
   uc.Eval("DisplayArgs(5, 3+2*#i, 'Hello', True, False, Int16(5+4.1))");
}
				
			
5  Type: double
3+2i  Type: complex
Hello  Type: string
true  Type: bool
false  Type: bool
9  Type: int16
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub DisplayArgs(ByVal cb As uCalc.Callback)
      For x  As Integer = 1 To cb.ArgCount()
         Console.WriteLine(cb.ArgItem(x).ValueStr() + "  Type: " + cb.ArgItem(x).DataType.Name)
      Next
   End Sub
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineFunction("DisplayArgs(ByHandle Arg As AnyType ...)", AddressOf DisplayArgs)
      uc.Eval("DisplayArgs(5, 3+2*#i, 'Hello', True, False, Int16(5+4.1))")
   End Sub
End Module
				
			
5  Type: double
3+2i  Type: complex
Hello  Type: string
true  Type: bool
false  Type: bool
9  Type: int16
Determining properties of an expression part
				
					using uCalcSoftware;

var uc = new uCalc();

static void ItemCallback(uCalc.Callback cb) {
   Console.WriteLine($"Name: {cb.Item.Name}");
   Console.WriteLine($"Data type: {cb.Item.DataType.Name}");
   Console.WriteLine($"Param count: {cb.Item.Count}");
   Console.Write("Procedure type: ");
   if (cb.Item.IsProperty(ItemIs.Operator)) {
      Console.WriteLine("Operator");
   } else if (cb.Item.IsProperty(ItemIs.Function)) {
      Console.WriteLine("Function");
   }
   Console.WriteLine(cb.Item.Text);
   Console.WriteLine(cb.Item.Description);
   Console.WriteLine("---");
}


uc.DefineFunction("AAA() As Double", ItemCallback).Description = "Does this and that";
uc.DefineFunction("BBB(x, y, z) As String", ItemCallback).Description = "Does something else";
uc.DefineOperator("{x} CCC {y} As Int32", 0, Associativity.LeftToRight, ItemCallback);

uc.EvalStr("AAA()");
uc.EvalStr("BBB(9, 8, 7)");
uc.EvalStr("5 CCC 4");

				
			
Name: aaa
Data type: double
Param count: 0
Procedure type: Function
Function: AAA() As Double
Does this and that
---
Name: bbb
Data type: string
Param count: 3
Procedure type: Function
Function: BBB(x, y, z) As String
Does something else
---
Name: ccc
Data type: int
Param count: 2
Procedure type: Operator
Operator: {x} CCC {y} As Int32

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

using namespace std;
using namespace uCalcSoftware;

void ucalc_call ItemCallback(uCalcBase::Callback cb) {
   cout << "Name: " << cb.Item().Name() << endl;
   cout << "Data type: " << cb.Item().DataType().Name() << endl;
   cout << "Param count: " << cb.Item().Count() << endl;
   cout << "Procedure type: ";
   if (cb.Item().IsProperty(ItemIs::Operator)) {
      cout << "Operator" << endl;
   } else if (cb.Item().IsProperty(ItemIs::Function)) {
      cout << "Function" << endl;
   }
   cout << cb.Item().Text() << endl;
   cout << cb.Item().Description() << endl;
   cout << "---" << endl;
}
int main() {
   uCalc uc;

   uc.DefineFunction("AAA() As Double", ItemCallback).Description("Does this and that");
   uc.DefineFunction("BBB(x, y, z) As String", ItemCallback).Description("Does something else");
   uc.DefineOperator("{x} CCC {y} As Int32", 0, Associativity::LeftToRight, ItemCallback);

   uc.EvalStr("AAA()");
   uc.EvalStr("BBB(9, 8, 7)");
   uc.EvalStr("5 CCC 4");

}
				
			
Name: aaa
Data type: double
Param count: 0
Procedure type: Function
Function: AAA() As Double
Does this and that
---
Name: bbb
Data type: string
Param count: 3
Procedure type: Function
Function: BBB(x, y, z) As String
Does something else
---
Name: ccc
Data type: int
Param count: 2
Procedure type: Operator
Operator: {x} CCC {y} As Int32

---
				
					Imports System
Imports uCalcSoftware
Public Module Program
   
   Public Sub ItemCallback(ByVal cb As uCalc.Callback)
      Console.WriteLine($"Name: {cb.Item.Name}")
      Console.WriteLine($"Data type: {cb.Item.DataType.Name}")
      Console.WriteLine($"Param count: {cb.Item.Count}")
      Console.Write("Procedure type: ")
      If cb.Item.IsProperty(ItemIs.Operator) Then
         Console.WriteLine("Operator")
         ElseIf cb.Item.IsProperty(ItemIs.Function ) Then
            Console.WriteLine("Function")
         End If
         Console.WriteLine(cb.Item.Text)
         Console.WriteLine(cb.Item.Description)
         Console.WriteLine("---")
      End Sub
      Public Sub Main()
         Dim uc As New uCalc()
         
         uc.DefineFunction("AAA() As Double", AddressOf ItemCallback).Description = "Does this and that"
         uc.DefineFunction("BBB(x, y, z) As String", AddressOf ItemCallback).Description = "Does something else"
         uc.DefineOperator("{x} CCC {y} As Int32", 0, Associativity.LeftToRight, AddressOf ItemCallback)
         
         uc.EvalStr("AAA()")
         uc.EvalStr("BBB(9, 8, 7)")
         uc.EvalStr("5 CCC 4")
         
      End Sub
   End Module
				
			
Name: aaa
Data type: double
Param count: 0
Procedure type: Function
Function: AAA() As Double
Does this and that
---
Name: bbb
Data type: string
Param count: 3
Procedure type: Function
Function: BBB(x, y, z) As String
Does something else
---
Name: ccc
Data type: int
Param count: 2
Procedure type: Operator
Operator: {x} CCC {y} As Int32

---
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
Setting a token data type
				
					using uCalcSoftware;

var uc = new uCalc();

// This example makes the # character behave the same way as quotes
uc.ExpressionTokens.Add("#([^#]*)#", TokenType.Literal, "", 1).DataType = uc.DataTypeOf("String");
Console.WriteLine(uc.EvalStr("#Hello # + #World#"));
				
			
Hello World
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;

   // This example makes the # character behave the same way as quotes
   uc.ExpressionTokens().Add("#([^#]*)#", TokenType::Literal, "", 1).DataType(uc.DataTypeOf("String"));
   cout << uc.EvalStr("#Hello # + #World#") << endl;
}
				
			
Hello World
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      '// This example makes the # character behave the same way as quotes
      uc.ExpressionTokens.Add("#([^#]*)#", TokenType.Literal, "", 1).DataType = uc.DataTypeOf("String")
      Console.WriteLine(uc.EvalStr("#Hello # + #World#"))
   End Sub
End Module
				
			
Hello World
Previous
Next