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.

DefineConstant

Method

Product: 

Fast Math Parser

Class: 

uCalcBase

Defines a named, read-only constant for use in expressions.

Syntax

DefineConstant(string, ADDR, DataType)

Parameters

constantDefinition
string
A string defining the constant's name and value, typically in the format 'NAME = VALUE'. For example, 'PI = 3.14159'.
hostVariableAddress
ADDR
(Default = 0)
Optional memory address of a variable in the host application. If provided, the constant's value will be linked to this variable, allowing the host application to update it dynamically while still preventing end-user modification.
targetType
DataType
(Default = Empty)
Optional data type for the constant. If omitted, the type is inferred from the value, defaulting to `Double` if ambiguous.

Return

Item

Returns an Item object representing the newly defined constant, which can be used for further programmatic manipulation (e.g., renaming or deleting).

Remarks

The DefineConstant method provides a straightforward way to create a named, read-only value within the uCalc engine. Constants are ideal for representing fixed values like mathematical constants, physical constants, or application configuration settings that should not be modified by end-user scripts.

✍️ Syntax & Usage

The most common usage involves passing a single string that defines both the name and the value of the constant.

// Defines a constant named PI with the value 3.14159uc.DefineConstant("PI = 3.14159");// Defines a string constant for an application versionuc.DefineConstant("APP_VERSION = 'v1.2.0'");

🛡️ Key Behaviors

  • Read-Only for End-Users: Once a constant is defined, any attempt by an end-user script to assign a new value to it will result in an error. This ensures the integrity of important values.

  • Host Application Control: While end-users cannot modify constants, the host application retains full control. You can programmatically delete the constant using the returned Item object's Release() method and redefine it, or you can link it to a host variable by providing the hostVariableAddress.

  • Syntactic Sugar: Using DefineConstant is a more readable and convenient shorthand for the generic [topic: Define] method with the Lock modifier. The following two lines are functionally identical:

    uc.DefineConstant("PI = 3.14");uc.Define("Lock ~~ Variable: PI = 3.14");

🆚 Comparison with Native Languages

Unlike compile-time constants in languages like C# (const) or C++ (const, constexpr), uCalc constants are defined at runtime. This provides a significant advantage for dynamic applications.

  • C# (const): Must be known at compile time.
  • uCalc (DefineConstant): Can be defined at runtime, for example, by loading values from a configuration file, a database, or user input when the application starts.

This runtime flexibility allows you to expose application settings to the scripting engine in a safe, read-only manner.

💡 Best Practices

  • Use constants for any value that is set by the application and should not be changed by a user's formula or script.
  • Prefix constants with a consistent pattern (e.g., CFG_, SYS_) to easily distinguish them from user variables in complex expressions.
  • For more advanced scenarios involving variables, see the [topic: DefineVariable] topic.

Examples

Quickly defines the mathematical constant PI and uses it in a simple calculation.
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineConstant("PI = 3.14159");
Console.WriteLine(uc.Eval("2 * PI"));
				
			
6.28318
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineConstant("PI = 3.14159");
   cout << uc.Eval("2 * PI") << endl;
}
				
			
6.28318
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineConstant("PI = 3.14159")
      Console.WriteLine(uc.Eval("2 * PI"))
   End Sub
End Module
				
			
6.28318
Defines several application-level configuration constants for use in expressions.
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineConstant("MAX_USERS = 100");
uc.DefineConstant("API_VERSION = 'v2.1'");
uc.DefineConstant("ENABLE_LOGGING = true");

Console.WriteLine("Configuration Settings:");
Console.WriteLine($"Max Users: {uc.Eval("MAX_USERS")}");
Console.WriteLine($"API Version: {uc.EvalStr("API_VERSION")}");
Console.WriteLine($"Logging Enabled: {uc.EvalStr("ENABLE_LOGGING")}");

// Use in a conditional expression
int currentUserCount = 99;
if (uc.EvalStr((currentUserCount).ToString() + " < MAX_USERS") == "true") {
   Console.WriteLine("System capacity is OK.");
}
				
			
Configuration Settings:
Max Users: 100
API Version: v2.1
Logging Enabled: true
System capacity is OK.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineConstant("MAX_USERS = 100");
   uc.DefineConstant("API_VERSION = 'v2.1'");
   uc.DefineConstant("ENABLE_LOGGING = true");

   cout << "Configuration Settings:" << endl;
   cout << "Max Users: " << uc.Eval("MAX_USERS") << endl;
   cout << "API Version: " << uc.EvalStr("API_VERSION") << endl;
   cout << "Logging Enabled: " << uc.EvalStr("ENABLE_LOGGING") << endl;

   // Use in a conditional expression
   int currentUserCount = 99;
   if (uc.EvalStr(to_string(currentUserCount) + " < MAX_USERS") == "true") {
      cout << "System capacity is OK." << endl;
   }
}
				
			
Configuration Settings:
Max Users: 100
API Version: v2.1
Logging Enabled: true
System capacity is OK.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineConstant("MAX_USERS = 100")
      uc.DefineConstant("API_VERSION = 'v2.1'")
      uc.DefineConstant("ENABLE_LOGGING = true")
      
      Console.WriteLine("Configuration Settings:")
      Console.WriteLine($"Max Users: {uc.Eval("MAX_USERS")}")
      Console.WriteLine($"API Version: {uc.EvalStr("API_VERSION")}")
      Console.WriteLine($"Logging Enabled: {uc.EvalStr("ENABLE_LOGGING")}")
      
      '// Use in a conditional expression
      Dim currentUserCount As Integer = 99
      If uc.EvalStr((currentUserCount).ToString() + " < MAX_USERS") = "true" Then
         Console.WriteLine("System capacity is OK.")
      End If
   End Sub
End Module
				
			
Configuration Settings:
Max Users: 100
API Version: v2.1
Logging Enabled: true
System capacity is OK.
Internal Test: Validates that end-users cannot modify a locked constant.
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineConstant("LOCKED_VAL = 1000");
Console.WriteLine($"Initial value: {uc.Eval("LOCKED_VAL")}");

// 1. End-user attempts to assign a value. This should fail.
uc.Eval("LOCKED_VAL = 2000");
Console.WriteLine($"Error after assignment attempt: {uc.Error.Message}");
Console.WriteLine($"Value remains unchanged: {uc.Eval("LOCKED_VAL")}");

				
			
Initial value: 1000
Error after assignment attempt: Value cannot be assigned here
Value remains unchanged: 1000
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineConstant("LOCKED_VAL = 1000");
   cout << "Initial value: " << uc.Eval("LOCKED_VAL") << endl;

   // 1. End-user attempts to assign a value. This should fail.
   uc.Eval("LOCKED_VAL = 2000");
   cout << "Error after assignment attempt: " << uc.Error().Message() << endl;
   cout << "Value remains unchanged: " << uc.Eval("LOCKED_VAL") << endl;

}
				
			
Initial value: 1000
Error after assignment attempt: Value cannot be assigned here
Value remains unchanged: 1000
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineConstant("LOCKED_VAL = 1000")
      Console.WriteLine($"Initial value: {uc.Eval("LOCKED_VAL")}")
      
      '// 1. End-user attempts to assign a value. This should fail.
      uc.Eval("LOCKED_VAL = 2000")
      Console.WriteLine($"Error after assignment attempt: {uc.Error.Message}")
      Console.WriteLine($"Value remains unchanged: {uc.Eval("LOCKED_VAL")}")
      
   End Sub
End Module
				
			
Initial value: 1000
Error after assignment attempt: Value cannot be assigned here
Value remains unchanged: 1000
Defining a constant
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineVariable("MyVar = 10");
uc.DefineConstant("MyPi = 3.14");

Console.WriteLine(uc.Eval("MyVar"));
Console.WriteLine(uc.Eval("MyPi"));

uc.EvalStr("MyVar = 20"); // Attempt to change MyVar
Console.WriteLine(uc.Error.Message);

uc.EvalStr("MyPi = 25"); // Attempt to change MyPi
Console.WriteLine(uc.Error.Message);

Console.WriteLine(uc.EvalStr("MyVar"));
Console.WriteLine(uc.EvalStr("MyPi"));
				
			
10
3.14
No error
Value cannot be assigned here
20
3.14
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineVariable("MyVar = 10");
   uc.DefineConstant("MyPi = 3.14");

   cout << uc.Eval("MyVar") << endl;
   cout << uc.Eval("MyPi") << endl;

   uc.EvalStr("MyVar = 20"); // Attempt to change MyVar
   cout << uc.Error().Message() << endl;

   uc.EvalStr("MyPi = 25"); // Attempt to change MyPi
   cout << uc.Error().Message() << endl;

   cout << uc.EvalStr("MyVar") << endl;
   cout << uc.EvalStr("MyPi") << endl;
}
				
			
10
3.14
No error
Value cannot be assigned here
20
3.14
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("MyVar = 10")
      uc.DefineConstant("MyPi = 3.14")
      
      Console.WriteLine(uc.Eval("MyVar"))
      Console.WriteLine(uc.Eval("MyPi"))
      
      uc.EvalStr("MyVar = 20") '// Attempt to change MyVar
      Console.WriteLine(uc.Error.Message)
      
      uc.EvalStr("MyPi = 25") '// Attempt to change MyPi
      Console.WriteLine(uc.Error.Message)
      
      Console.WriteLine(uc.EvalStr("MyVar"))
      Console.WriteLine(uc.EvalStr("MyPi"))
   End Sub
End Module
				
			
10
3.14
No error
Value cannot be assigned here
20
3.14
Previous
Next