📝 Setting 64-bit Integer Values Programmatically

The ValueInt64 method provides a direct and type-safe way to set the value of a uCalc variable that holds a 64-bit integer. It is the primary setter for variables defined as Int64 or Long.

⚙️ Core Usage

This method is used after a variable has been created with a method like DefineVariable. It allows the host application to update the variable's state before an expression is evaluated, which is crucial for performance.

using uCalcSoftware;

var uc = new uCalc();

// 1. Define a 64-bit integer variable for a database record ID
var recordId = uc.DefineVariable("recordId As Int64");

// 2. Set its value using ValueInt64
recordId.ValueInt64(8192837123981273);

// 3. Use it in an expression
Console.WriteLine(uc.EvalStr("recordId")); // Outputs: 8192837123981273

This method handles both signed (Int64) and unsigned (Int64u) variables correctly. When setting an unsigned variable, the bit pattern is preserved. For example, setting an Int64u variable to -1 will result in its maximum possible value, 18446744073709551615.

🆚 Comparative Analysis: Performance and Approach

There are three primary ways to manage variable values in uCalc, each with different performance characteristics.

1. ValueInt64 (Type-Safe Setter - Recommended)

   • Pros: Fast, type-safe, and avoids string parsing overhead.
   • Cons: Requires a specific method call for each data type.
   • Best for: Updating variables in performance-critical loops where values are already available as native 64-bit integers.

2. Value(string) (Expression-Based Setter)

   • Pros: Flexible; can set a variable of any type from a string expression.
   • Cons: Slower, as it involves parsing and evaluating the input string.
   • Best for: Setting values from user input or configuration files where performance is not the primary concern.

3. Direct Memory Binding (Highest Performance)

   • When defining the variable with DefineVariable, you can pass a pointer to a host application variable. The uCalc variable becomes a direct proxy to your native variable, eliminating the need for any setter calls.
   • Pros: The fastest possible method, zero overhead per update.
   • Cons: Requires more complex setup, especially in managed languages like C#.
   • Best for: High-frequency updates in scientific simulations, financial modeling, or real-time systems.

In summary, ValueInt64 offers the best balance of performance, safety, and ease of use for programmatically updating 64-bit integer variables.