⚙️ Data Types and Evaluation in uCalc

The uCalc engine combines the flexibility of a dynamically typed language with the robustness of a strongly typed system. This topic provides an overview of how data types are handled and how expressions are evaluated, two fundamental concepts for using the library effectively.

1. The uCalc Type System

Unlike statically-compiled languages like C# or C++, where types are fixed at compile time, uCalc's type system is dynamic at runtime. However, every value still has a specific, well-defined type.

💡 Type Inference (The Default)

For convenience, uCalc automatically infers the data type from the value provided in a definition. This allows for concise, script-like code.

using uCalcSoftware;

var uc = new uCalc();

// uCalc infers the types automatically

uc.DefineVariable("myDouble = 10.5");         // Becomes a Double type
uc.DefineVariable("myString = 'hello'");      // Becomes a String type
uc.DefineVariable("myFlag = 10 > 5");     // Becomes a Boolean type

✍️ Explicit Typing (As Keyword)

You can enforce a specific data type using the As keyword in a definition string. This is useful for ensuring type safety, optimizing memory, or when a variable is created without an initial value.

using uCalcSoftware;

var uc = new uCalc();

// Explicitly define a 16-bit integer
uc.DefineVariable("counter As Int16");

// Define a function that must return a String
uc.DefineFunction("GetMessage() As String = 'OK'");

🎲 The Default Data Type: Double

If a type cannot be inferred (e.g., when defining a variable with no initial value), uCalc assigns the default data type. By default, this is Double (a 64-bit floating-point number), which is suitable for a wide range of mathematical calculations.

You can inspect or change this default for any uCalc instance using the DefaultDataType property. This is useful if your application deals primarily with integers or another specific type.

For a list of all available types, see the BuiltInType enumeration.

2. The Evaluation Model

uCalc offers two primary models for evaluating expressions, designed to balance convenience with performance.

🚀 The High-Performance Model: Parse-Once, Evaluate-Many

The single most important concept for performance is the separation of parsing and evaluation.

1. Parsing: The computationally expensive step of analyzing a string and building an executable plan. This is done once with the Parse method, which returns an Expression object.
2. Evaluation: The extremely fast step of executing that pre-compiled plan. This is done repeatedly by calling methods like Evaluate or EvaluateStr on the Expression object.

This two-step pattern is critical for any code that runs in a loop and is explained in detail in the Optimizing Performance tutorial.

✅ The Convenience Model: One-Step Evaluation

For one-off calculations where performance is not critical, uCalc provides the Eval and EvalStr methods. These convenient functions perform the parsing and evaluation steps internally in a single call.

• Eval(): Optimized for numeric results, returns a double.
• EvalStr(): The universal evaluator. It can return a value of any data type formatted as a string and safely returns error messages as strings, making it ideal for handling user input.