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.

Clone

Method

Product: 

Fast Math Parser

Class: 

uCalcBase

Creates an identical, but independent, copy of the current uCalc instance, including all its defined variables, functions, and settings.

Syntax

Clone(bool)

Parameters

makeDefault
bool
(Default = false)
If true, the newly created clone becomes the new default uCalc instance for the current thread.

Return

uCalcBase

A new, independent uCalc instance that is a complete replica of the original.

Remarks

This method creates an identical, yet completely independent, copy of a uCalc object. The new instance inherits the entire state of the original, including all defined variables, functions, operators, and configuration settings. Once cloned, the two instances are decoupled; changes made to one will not affect the other.

This is functionally equivalent to, but more expressive than, creating a new uCalc instance with the original as a constructor argument. So var clone = uc.Clone(); is the same as var clone = new uCalc(uc);.

State Replication

A clone is a deep copy. The following state is replicated:

  • Variables: All user-defined variables.
  • Functions: All user-defined functions, including those with callbacks.
  • Operators: All custom operators.
  • Error Handlers: The entire error handler chain.
  • Settings: All configuration settings, such as Format, DecimalSeparator, etc.

⚙️ Primary Use Cases

Cloning is essential for creating isolated environments for computation.

  • "What-If" Scenario Analysis: Create a base configuration and then clone it multiple times to model different scenarios without affecting the original or other scenarios. This is useful in financial modeling or scientific simulations.
  • Sandboxing: Evaluate untrusted or experimental expressions in a cloned instance. If the clone's state is corrupted, the original instance remains intact.
  • Multithreading: Provide each thread with its own identical uCalc instance to perform calculations in parallel without state conflicts.

💡 Comparative Analysis

In a standard programming language, replicating a complex object's state often requires implementing a deep copy constructor or a serialization-deserialization mechanism, which can be error-prone.

  • Without uCalc: You would need to instantiate a new uCalc object and then manually re-apply all definitions and settings from the original. This is inefficient and verbose.

    // Manual, inefficient wayvar uc2 = new uCalc();// ... manually copy dozens of variables, functions, settings ...uc2.DefineVariable("rate = 0.05");uc2.DefineFunction("MyFunc(x) = x*2");// etc.
*   **With uCalc's `Clone`**: The entire state replication is handled by a single, optimized method call.    ```csharp    // Clean, efficient uCalc way    var uc2 = uc.Clone();

This simplifies code, reduces bugs, and improves performance for scenarios requiring state duplication.

Examples

Creating a clone of a uCalc object
				
					using uCalcSoftware;

var uc = new uCalc();

uc.DefineVariable("MyVar = 100");
uc.DefineFunction("MyFunc(x) = x + 1");

var Cloned_uc = uc.Clone();

Console.WriteLine(uc.EvalStr("MyVar"));
Console.WriteLine(uc.EvalStr("MyFunc(10)"));

Console.WriteLine(Cloned_uc.EvalStr("MyVar"));
Console.WriteLine(Cloned_uc.EvalStr("MyFunc(10)"));

Cloned_uc.Eval("MyVar = 200");
Cloned_uc.DefineFunction("OtherFunc(x) = x * 10");

Console.WriteLine(uc.EvalStr("MyVar"));
Console.WriteLine(uc.EvalStr("OtherFunc(5)"));

Console.WriteLine(Cloned_uc.EvalStr("MyVar"));
Console.WriteLine(Cloned_uc.EvalStr("OtherFunc(5)"));
				
			
100
11
100
11
100
Undefined identifier
200
50
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;

   uc.DefineVariable("MyVar = 100");
   uc.DefineFunction("MyFunc(x) = x + 1");

   auto Cloned_uc = uc.Clone();

   cout << uc.EvalStr("MyVar") << endl;
   cout << uc.EvalStr("MyFunc(10)") << endl;

   cout << Cloned_uc.EvalStr("MyVar") << endl;
   cout << Cloned_uc.EvalStr("MyFunc(10)") << endl;

   Cloned_uc.Eval("MyVar = 200");
   Cloned_uc.DefineFunction("OtherFunc(x) = x * 10");

   cout << uc.EvalStr("MyVar") << endl;
   cout << uc.EvalStr("OtherFunc(5)") << endl;

   cout << Cloned_uc.EvalStr("MyVar") << endl;
   cout << Cloned_uc.EvalStr("OtherFunc(5)") << endl;
}
				
			
100
11
100
11
100
Undefined identifier
200
50
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      uc.DefineVariable("MyVar = 100")
      uc.DefineFunction("MyFunc(x) = x + 1")
      
      Dim Cloned_uc = uc.Clone()
      
      Console.WriteLine(uc.EvalStr("MyVar"))
      Console.WriteLine(uc.EvalStr("MyFunc(10)"))
      
      Console.WriteLine(Cloned_uc.EvalStr("MyVar"))
      Console.WriteLine(Cloned_uc.EvalStr("MyFunc(10)"))
      
      Cloned_uc.Eval("MyVar = 200")
      Cloned_uc.DefineFunction("OtherFunc(x) = x * 10")
      
      Console.WriteLine(uc.EvalStr("MyVar"))
      Console.WriteLine(uc.EvalStr("OtherFunc(5)"))
      
      Console.WriteLine(Cloned_uc.EvalStr("MyVar"))
      Console.WriteLine(Cloned_uc.EvalStr("OtherFunc(5)"))
   End Sub
End Module
				
			
100
11
100
11
100
Undefined identifier
200
50
Creating uCalc instances
				
					using uCalcSoftware;

var uc = new uCalc();
uc.DefineVariable("x = 123");

var uc1 = new uCalc(); // Creates a new instance
Console.WriteLine(uc1.EvalStr("x")); // uc1 does not have a variable named x
uc1.Release(); // Releases uc1 if it is no longer needed

var uc2 = uc.Clone(); // Creates new instance that is a clone of uc
Console.WriteLine(uc2.EvalStr("x")); // starts with the value of x obtained from uc
uc2.Eval("x = 456"); // Changes the value of x in uc1 but not uc
Console.WriteLine(uc2.EvalStr("x"));
Console.WriteLine(uc.EvalStr("x")); // The original x in uc remains unchanged
uc2.Release();

// Language specific - auto-releasing uCalc object

{ // Instances pointed to by neither uCalc1 nor uCalc2 will be released when they go out of scope
   var uCalc1 = new uCalc();
   var uCalc2 = uc.Clone();
   // Call uCalc1.Release() and uCalc2.Release() explicitly if want to release them
}

{ // The instances that both uCalc1 and uCalc2 point to will be released when uCalc1 and uCalc2 go out of scope
   using var uCalc1 = new uCalc();
   using var uCalc2 = uc.Clone();

   // No need for uCalc1.Release() or uCalc2.Release(), they will automatically be released
}

				
			
Undefined identifier
123
456
123
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uc.DefineVariable("x = 123");

   uCalc uc1; // Creates a new instance
   cout << uc1.EvalStr("x") << endl; // uc1 does not have a variable named x
   uc1.Release(); // Releases uc1 if it is no longer needed

   auto uc2 = uc.Clone(); // Creates new instance that is a clone of uc
   cout << uc2.EvalStr("x") << endl; // starts with the value of x obtained from uc
   uc2.Eval("x = 456"); // Changes the value of x in uc1 but not uc
   cout << uc2.EvalStr("x") << endl;
   cout << uc.EvalStr("x") << endl; // The original x in uc remains unchanged
   uc2.Release();

   // Language specific - auto-releasing uCalc object

   { // Instances pointed to by neither uCalc1 nor uCalc2 will be released when they go out of scope
      auto uCalc1 = new uCalc();
      auto uCalc2 = uc.Clone();
      // Call uCalc1.Release() and uCalc2.Release() explicitly if want to release them
   }

   { // The instances that both uCalc1 and uCalc2 point to will be released when uCalc1 and uCalc2 go out of scope
      
      uCalc uCalc1;
      uCalc uCalc2(uc.Clone());
      // No need for uCalc1.Release() or uCalc2.Release(), they will automatically be released
   }

}
				
			
Undefined identifier
123
456
123
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      uc.DefineVariable("x = 123")
      
      Dim uc1 As New uCalc() '// Creates a new instance
      Console.WriteLine(uc1.EvalStr("x")) '// uc1 does not have a variable named x
      uc1.Release() '// Releases uc1 if it is no longer needed
      
      Dim uc2 = uc.Clone() '// Creates new instance that is a clone of uc
      Console.WriteLine(uc2.EvalStr("x")) '// starts with the value of x obtained from uc
      uc2.Eval("x = 456") '// Changes the value of x in uc1 but not uc
      Console.WriteLine(uc2.EvalStr("x"))
      Console.WriteLine(uc.EvalStr("x")) '// The original x in uc remains unchanged
      uc2.Release()
      
      '// Language specific - auto-releasing uCalc object
      #If False
         { '// Instances pointed to by neither uCalc1 nor uCalc2 will be released when they go out of scope
         Dim uCalc1 = new uCalc()
         Dim uCalc2 = uc.Clone()
         '// Call uCalc1.Release() and uCalc2.Release() explicitly if want to release them
         }
         
         { '// The instances that both uCalc1 and uCalc2 point to will be released when uCalc1 and uCalc2 go out of scope
         
         
         '// No need for uCalc1.Release() or uCalc2.Release(), they will automatically be released
         }
         #End If
      End Sub
   End Module
				
			
Undefined identifier
123
456
123
Previous
Next