uCalc API Version: 2.1.3-preview.2 Released: 6/17/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.

DefaultInstance = [uCalc]

Property

Product: 

Fast Math Parser

Class: 

uCalcBase

Gets/sets the globally accessible default uCalc instance.

Remarks

This static method provides access to the default uCalc instance, which serves as a convenient global singleton and a template for newly created instances.

🎯 Core Concept

Every uCalc environment has a default instance. You can access it anytime using uCalc.GetDefaultInstance() without needing to create or track an object manually. This is useful for simple, one-off calculations or for establishing a shared configuration across different parts of an application.

⚙️ How It Works

  1. Inheritance: When a new uCalc instance is created (e.g., var uc = new uCalc();), it inherits a complete copy of the settings, functions, variables, and operators from the current default instance. This allows you to pre-configure the default instance with a standard library of features that all subsequent instances will automatically receive.

  2. Stack-Based Defaults: The default instance is not a single, fixed object. Instead, uCalc manages a stack of default instances. You can promote any instance to be the new default using myInstance.IsDefault(true);. This pushes myInstance onto the top of the stack. When that instance is unset (myInstance.IsDefault(false);) or goes out of scope (if created with using), it is popped from the stack, and the previous instance becomes the default again. This provides a predictable, scoped approach to managing global settings.

💡 Why Use a Default Instance?

  • Convenience: For quick calculations, you don't need to instantiate a new uCalc object. You can directly use uCalc.GetDefaultInstance().Eval(...).
  • Global Configuration: Define custom functions, units, or variables once in a dedicated instance, set it as the default, and they become available everywhere. This avoids the need for dependency injection or passing uCalc objects throughout your application's call stack.
  • Implicit Context: Other components, like [topic:uCalc.Expression] or [topic:uCalc.String], use the default instance implicitly when no specific instance is provided in their constructors.

⚠️ Best Practices

While you can modify the original default instance directly, the recommended approach is to:

  1. Create and configure a new uCalc instance.
  2. Set this new, configured instance as the default using .IsDefault(true).

This practice leads to cleaner, more maintainable code by clearly separating your application's custom configuration from the initial built-in state.

Thread Safety

The default instance stack is managed on a per-thread basis (using thread-local storage). This means that changes to the default instance in one thread will not affect the default instance in another, ensuring thread safety in multi-threaded applications.

Examples

Using the default uCalc.GetDefaultInstance() instance
				
					using uCalcSoftware;

var uc = new uCalc();
uCalc.DefaultInstance.DefineVariable("instance = 'original default'");

var ucB = new uCalc();
var ucC = new uCalc();
var ucD = new uCalc();

ucB.Eval("instance = 'B derived from -> ' + instance");
ucC.Eval("instance = 'C derived from -> ' + instance");
ucD.Eval("instance = 'D derived from -> ' + instance");

ucC.IsDefault = true;

var ucE = new uCalc();
ucE.Eval("instance = 'E derived from -> ' + instance");

Console.WriteLine(uCalc.DefaultInstance.EvalStr("'Default: ' + instance"));

Console.WriteLine(uc.EvalStr("instance")); // Note: this is not, nor was the default
Console.WriteLine(ucB.EvalStr("instance"));
Console.WriteLine(ucC.EvalStr("instance"));
Console.WriteLine(ucD.EvalStr("instance"));
Console.WriteLine(ucE.EvalStr("instance"));

// Note: Unlike this example, it is generally best to always
// create a new instance first and then set it as default
				
			
Default: C derived from -> original default
Undefined identifier
B derived from -> original default
C derived from -> original default
D derived from -> original default
E derived from -> C derived from -> original default
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::DefaultInstance().DefineVariable("instance = 'original default'");

   uCalc ucB;
   uCalc ucC;
   uCalc ucD;

   ucB.Eval("instance = 'B derived from -> ' + instance");
   ucC.Eval("instance = 'C derived from -> ' + instance");
   ucD.Eval("instance = 'D derived from -> ' + instance");

   ucC.IsDefault(true);

   uCalc ucE;
   ucE.Eval("instance = 'E derived from -> ' + instance");

   cout << uCalc::DefaultInstance().EvalStr("'Default: ' + instance") << endl;

   cout << uc.EvalStr("instance") << endl; // Note: this is not, nor was the default
   cout << ucB.EvalStr("instance") << endl;
   cout << ucC.EvalStr("instance") << endl;
   cout << ucD.EvalStr("instance") << endl;
   cout << ucE.EvalStr("instance") << endl;

   // Note: Unlike this example, it is generally best to always
   // create a new instance first and then set it as default
}
				
			
Default: C derived from -> original default
Undefined identifier
B derived from -> original default
C derived from -> original default
D derived from -> original default
E derived from -> C derived from -> original default
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uCalc.DefaultInstance.DefineVariable("instance = 'original default'")
      
      Dim ucB As New uCalc()
      Dim ucC As New uCalc()
      Dim ucD As New uCalc()
      
      ucB.Eval("instance = 'B derived from -> ' + instance")
      ucC.Eval("instance = 'C derived from -> ' + instance")
      ucD.Eval("instance = 'D derived from -> ' + instance")
      
      ucC.IsDefault = true
      
      Dim ucE As New uCalc()
      ucE.Eval("instance = 'E derived from -> ' + instance")
      
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("'Default: ' + instance"))
      
      Console.WriteLine(uc.EvalStr("instance")) '// Note: this is not, nor was the default
      Console.WriteLine(ucB.EvalStr("instance"))
      Console.WriteLine(ucC.EvalStr("instance"))
      Console.WriteLine(ucD.EvalStr("instance"))
      Console.WriteLine(ucE.EvalStr("instance"))
      
      '// Note: Unlike this example, it is generally best to always
      '// create a new instance first and then set it as default
   End Sub
End Module
				
			
Default: C derived from -> original default
Undefined identifier
B derived from -> original default
C derived from -> original default
D derived from -> original default
E derived from -> C derived from -> original default
Setting default uCalc instance with uCalc.IsDefault(); also clearing all uCalc instances from default list
				
					using uCalcSoftware;

var uc = new uCalc();
uCalc.DefaultInstance.DefineVariable("val = 'original default'");
Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"));

uc.DefineVariable("val = 'uc'");
uc.IsDefault = true;
Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"));

var ucB = new uCalc();
ucB.DefineVariable("val = 'ucB'");
ucB.IsDefault = true;
Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"));

var ucC = new uCalc();
ucC.DefineVariable("val = 'ucC'");
ucC.IsDefault = true;
Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"));

uCalc.DefaultClear();

// The original unnamed default instance is reset so user variable val no longer exists
Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"));

// The other instances are removed from Default list but remain active
Console.WriteLine(uc.EvalStr("val"));
Console.WriteLine(ucB.EvalStr("val"));
Console.WriteLine(ucC.EvalStr("val"));
				
			
original default
uc
ucB
ucC
Undefined identifier
uc
ucB
ucC
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::DefaultInstance().DefineVariable("val = 'original default'");
   cout << uCalc::DefaultInstance().EvalStr("val") << endl;

   uc.DefineVariable("val = 'uc'");
   uc.IsDefault(true);
   cout << uCalc::DefaultInstance().EvalStr("val") << endl;

   uCalc ucB;
   ucB.DefineVariable("val = 'ucB'");
   ucB.IsDefault(true);
   cout << uCalc::DefaultInstance().EvalStr("val") << endl;

   uCalc ucC;
   ucC.DefineVariable("val = 'ucC'");
   ucC.IsDefault(true);
   cout << uCalc::DefaultInstance().EvalStr("val") << endl;

   uCalc::DefaultClear();

   // The original unnamed default instance is reset so user variable val no longer exists
   cout << uCalc::DefaultInstance().EvalStr("val") << endl;

   // The other instances are removed from Default list but remain active
   cout << uc.EvalStr("val") << endl;
   cout << ucB.EvalStr("val") << endl;
   cout << ucC.EvalStr("val") << endl;
}
				
			
original default
uc
ucB
ucC
Undefined identifier
uc
ucB
ucC
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uCalc.DefaultInstance.DefineVariable("val = 'original default'")
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"))
      
      uc.DefineVariable("val = 'uc'")
      uc.IsDefault = true
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"))
      
      Dim ucB As New uCalc()
      ucB.DefineVariable("val = 'ucB'")
      ucB.IsDefault = true
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"))
      
      Dim ucC As New uCalc()
      ucC.DefineVariable("val = 'ucC'")
      ucC.IsDefault = true
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"))
      
      uCalc.DefaultClear()
      
      '// The original unnamed default instance is reset so user variable val no longer exists
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("val"))
      
      '// The other instances are removed from Default list but remain active
      Console.WriteLine(uc.EvalStr("val"))
      Console.WriteLine(ucB.EvalStr("val"))
      Console.WriteLine(ucC.EvalStr("val"))
   End Sub
End Module
				
			
original default
uc
ucB
ucC
Undefined identifier
uc
ucB
ucC
"using" (C#) and Owned (C++) for auto-releasing uCalc object
				
					using uCalcSoftware;

var uc = new uCalc();

// In C# and VB you should use "using".
// In C++ you can flag a uCalc object for
// auto-release with Owned(), or by setting
// the last parameter of the constructor to true.

uc.IsDefault = true; // Set uc as the default uCalc object
uCalc.DefaultInstance.DefineVariable("Value = 'Original uc object'");
Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")); // Outputs: Original uc object

// Use "using" so that the object is auto-released when it it goes out of scope
using (var uCalcTemp = new uCalc()) {
   uCalcTemp.IsDefault = true; // Set uCalcTemp as the default uCalc object
   uCalc.DefaultInstance.DefineVariable("Value = 'uCalcTemp object'");
   Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")); // uCalcTemp object
}
// uCalcTemp goes out of scope here, and the default uCalc object reverts back to uc

Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")); // Original uc object

{
   /*using*/ var uCalcSticky = new uCalc(); // remains the default even after going out of scope
   uCalcSticky.IsDefault = true; // Set uCalcSticky as the default uCalc object
   uCalc.DefaultInstance.DefineVariable("Value = 'uCalcSticky object'");
   Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")); // Outputs: uCalcSticky object
}    // The uCalcSticky object itself goes out of scope here, but internally it remains the default uCalc object

Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value"));
				
			
Original uc object
uCalcTemp object
Original uc object
uCalcSticky object
uCalcSticky object
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;

   // In C# and VB you should use "using".
   // In C++ you can flag a uCalc object for
   // auto-release with Owned(), or by setting
   // the last parameter of the constructor to true.

   uc.IsDefault(true); // Set uc as the default uCalc object
   uCalc::DefaultInstance().DefineVariable("Value = 'Original uc object'");
   cout << uCalc::DefaultInstance().EvalStr("Value") << endl; // Outputs: Original uc object


   {
      uCalc uCalcTemp;
      uCalcTemp.Owned(); // Causes uCalcTemp to be released when it goes out of scope // Make uCalcTemp owned so it reverts back to uc when uCalcTemp goes out of scope
      uCalcTemp.IsDefault(true); // Set uCalcTemp as the default uCalc object
      uCalc::DefaultInstance().DefineVariable("Value = 'uCalcTemp object'");
      cout << uCalc::DefaultInstance().EvalStr("Value") << endl; // uCalcTemp object
   }
   // uCalcTemp goes out of scope here, and the default uCalc object reverts back to uc

   cout << uCalc::DefaultInstance().EvalStr("Value") << endl; // Original uc object

   {
      uCalc uCalcSticky; // remains the default even after going out of scope
      uCalcSticky.IsDefault(true); // Set uCalcSticky as the default uCalc object
      uCalc::DefaultInstance().DefineVariable("Value = 'uCalcSticky object'");
      cout << uCalc::DefaultInstance().EvalStr("Value") << endl; // Outputs: uCalcSticky object
   }    // The uCalcSticky object itself goes out of scope here, but internally it remains the default uCalc object

   cout << uCalc::DefaultInstance().EvalStr("Value") << endl;
}
				
			
Original uc object
uCalcTemp object
Original uc object
uCalcSticky object
uCalcSticky object
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      '// In C# and VB you should use "using".
      '// In C++ you can flag a uCalc object for
      '// auto-release with Owned(), or by setting
      '// the last parameter of the constructor to true.
      
      uc.IsDefault = true '// Set uc as the default uCalc object
      uCalc.DefaultInstance.DefineVariable("Value = 'Original uc object'")
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")) '// Outputs: Original uc object
      
      '// Use "using" so that the object is auto-released when it it goes out of scope
      Using uCalcTemp As New uCalc()
         uCalcTemp.IsDefault = true '// Set uCalcTemp as the default uCalc object
         uCalc.DefaultInstance.DefineVariable("Value = 'uCalcTemp object'")
         Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")) '// uCalcTemp object
      End Using
      '// uCalcTemp goes out of scope here, and the default uCalc object reverts back to uc
      
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")) '// Original uc object
      
      If True Then
         Dim uCalcSticky As New uCalc() '// remains the default even after going out of scope
         uCalcSticky.IsDefault = true '// Set uCalcSticky as the default uCalc object
         uCalc.DefaultInstance.DefineVariable("Value = 'uCalcSticky object'")
         Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value")) '// Outputs: uCalcSticky object
      End If    '// The uCalcSticky object itself goes out of scope here, but internally it remains the default uCalc object
      
      Console.WriteLine(uCalc.DefaultInstance.EvalStr("Value"))
   End Sub
End Module
				
			
Original uc object
uCalcTemp object
Original uc object
uCalcSticky object
uCalcSticky object
Internal Test: Verifies the stack-like (LIFO) behavior of default instances using a scoped object.
				
					using uCalcSoftware;

var uc = new uCalc();
// Original default instance
uCalc.DefaultInstance.DefineVariable("id = 'Original'");
Console.WriteLine($"Current Default ID: {uCalc.DefaultInstance.EvalStr("id")}");

// Push a new default instance onto the stack
var ucA = new uCalc();
ucA.DefineVariable("id = 'Instance A'");
ucA.IsDefault = true;
Console.WriteLine($"Current Default ID: {uCalc.DefaultInstance.EvalStr("id")}");

// The 'NewUsing' block creates a temporary, scoped default instance

// The following instance will be auto-released at the end of the block
using (var ucB = new uCalc()) {
   ucB.DefineVariable("id = 'Instance B (temp)'");
   ucB.IsDefault = true; // Pushes 'ucB' onto the stack
   Console.WriteLine($"Current Default ID: {uCalc.DefaultInstance.EvalStr("id")}");
}

// 'ucB' has gone out of scope, so the default reverts to the previous one ('ucA')
Console.WriteLine($"Current Default ID (after scope exit): {uCalc.DefaultInstance.EvalStr("id")}");

// Manually unset 'ucA'
ucA.IsDefault = false;
Console.WriteLine($"Current Default ID (after unset): {uCalc.DefaultInstance.EvalStr("id")}");
				
			
Current Default ID: Original
Current Default ID: Instance A
Current Default ID: Instance B (temp)
Current Default ID (after scope exit): Instance A
Current Default ID (after unset): Original
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Original default instance
   uCalc::DefaultInstance().DefineVariable("id = 'Original'");
   cout << "Current Default ID: " << uCalc::DefaultInstance().EvalStr("id") << endl;

   // Push a new default instance onto the stack
   uCalc ucA;
   ucA.DefineVariable("id = 'Instance A'");
   ucA.IsDefault(true);
   cout << "Current Default ID: " << uCalc::DefaultInstance().EvalStr("id") << endl;

   // The 'NewUsing' block creates a temporary, scoped default instance

   // The following instance will be auto-released at the end of the block
   {
      uCalc ucB;
      ucB.Owned(); // Causes ucB to be released when it goes out of scope
      ucB.DefineVariable("id = 'Instance B (temp)'");
      ucB.IsDefault(true); // Pushes 'ucB' onto the stack
      cout << "Current Default ID: " << uCalc::DefaultInstance().EvalStr("id") << endl;
   }

   // 'ucB' has gone out of scope, so the default reverts to the previous one ('ucA')
   cout << "Current Default ID (after scope exit): " << uCalc::DefaultInstance().EvalStr("id") << endl;

   // Manually unset 'ucA'
   ucA.IsDefault(false);
   cout << "Current Default ID (after unset): " << uCalc::DefaultInstance().EvalStr("id") << endl;
}
				
			
Current Default ID: Original
Current Default ID: Instance A
Current Default ID: Instance B (temp)
Current Default ID (after scope exit): Instance A
Current Default ID (after unset): Original
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Original default instance
      uCalc.DefaultInstance.DefineVariable("id = 'Original'")
      Console.WriteLine($"Current Default ID: {uCalc.DefaultInstance.EvalStr("id")}")
      
      '// Push a new default instance onto the stack
      Dim ucA As New uCalc()
      ucA.DefineVariable("id = 'Instance A'")
      ucA.IsDefault = true
      Console.WriteLine($"Current Default ID: {uCalc.DefaultInstance.EvalStr("id")}")
      
      '// The 'NewUsing' block creates a temporary, scoped default instance
      
      '// The following instance will be auto-released at the end of the block
      Using ucB As New uCalc()
         ucB.DefineVariable("id = 'Instance B (temp)'")
         ucB.IsDefault = true '// Pushes 'ucB' onto the stack
         Console.WriteLine($"Current Default ID: {uCalc.DefaultInstance.EvalStr("id")}")
      End Using
      
      '// 'ucB' has gone out of scope, so the default reverts to the previous one ('ucA')
      Console.WriteLine($"Current Default ID (after scope exit): {uCalc.DefaultInstance.EvalStr("id")}")
      
      '// Manually unset 'ucA'
      ucA.IsDefault = false
      Console.WriteLine($"Current Default ID (after unset): {uCalc.DefaultInstance.EvalStr("id")}")
   End Sub
End Module
				
			
Current Default ID: Original
Current Default ID: Instance A
Current Default ID: Instance B (temp)
Current Default ID (after scope exit): Instance A
Current Default ID (after unset): Original
Previous
Next