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.

C++

Product: 

Class: 

Covers C++-specific features, syntax, and best practices for lifetime management when using the uCalc library.

Remarks

While uCalc is designed with a consistent cross-platform API, it offers several features that integrate seamlessly with C++ idioms, providing a more natural and productive development experience.

💎 Idiomatic C++ Features

1. Lifetime Management with RAII and Owned()

This is the most critical C++-specific pattern. Most uCalc objects hold unmanaged resources and must be released to prevent memory leaks. The idiomatic C++ approach is to leverage RAII (Resource Acquisition Is Initialization), where an object's lifetime is bound to the scope of a stack-allocated variable.

To bridge uCalc's memory model with RAII, you use the Owned() method. When called on a stack-allocated uCalc object, it ensures that Release() is automatically called in the object's destructor when it goes out of scope.

{    // Create a transformer on the stack.    uCalc::Transformer t;    // Mark it as 'owned' to enable automatic release.    t.Owned();    wl(t.Transform("input"));} // t's destructor is called here, which automatically calls Release().

This pattern is essential for managing objects returned by methods like Clone(), which are allocated on the heap.

2. Operator Overloading & Implicit Conversions

For convenience, several uCalc classes provide implicit conversions to and from std::string, allowing for more concise and natural code.

  • uCalc::Expression: An Expression object can be assigned from a string literal, which implicitly calls Parse(). It can also be converted to a string, which implicitly calls EvaluateStr().

    uCalc::Expression expr;expr = "5 + 4"; // Implicitly calls expr.Parse("5+4")wl(expr);     // Implicitly calls expr.EvaluateStr()

  • uCalc::String & uCalc::Transformer: Assignment to and from a string acts as a shortcut for the object's primary text property.

    uCalc::Transformer t;t = "some text"; // Equivalent to t.Text("some text")std::string result = t; // Equivalent to result = t.Text()

3. Method-Based Syntax

C++ does not have native property syntax like C#. Therefore, all interactions, including those documented as properties, are performed through method calls. This provides a consistent, predictable API.

  • C# Syntax: uc.Description = "text";
  • C++ Syntax: uc.Description("text");

4. Range-Based for Loop Integration

All uCalc collection objects (e.g., Matches, Tokens, Items) are compatible with C++11's range-based for loops. This provides a modern, safe, and readable way to iterate over collections.

// Assume 'myTransformer' has run and has matchesfor (const auto& match : myTransformer.Matches()){    wl(match.Text());}

5. Callback Calling Convention

When defining a callback function in C++ for Windows x86 (32-bit) builds, you must use the ucalc_call convention (__stdcall). This is not required for x64 builds or other platforms like Linux. For more details, see Callback mechanics.

🆚 Comparative Analysis: Why uCalc in C++?

While C++ offers powerful libraries, uCalc provides specialized parsing capabilities that are simpler and more dynamic than traditional alternatives.

  • vs. Parser Generators (Boost.Spirit, Flex/Bison): These tools are extremely powerful but require a separate grammar definition file, a code generation step, and a full recompile to make changes. uCalc is fully dynamic. You can define new tokens, functions, and operators at runtime through its C++ API, without any external tools or build steps. This makes it ideal for applications requiring user-configurable syntax or dynamic DSLs.

  • vs. std::regex and String Manipulation: C++'s standard regex is powerful for character-level patterns but struggles with nested structures and language context. uCalc's Transformer operates on tokens, making it inherently aware of code structure (parentheses, strings, comments). This is far more robust for code transformation and analysis than manual string splitting or fragile regex patterns.

  • vs. Embedded Scripting Engines (Lua, ChaiScript): Full scripting engines are often heavy and can be complex to integrate. uCalc is a lightweight, specialized component focused on expression evaluation and transformation. Its API is designed for tight, high-performance integration with C++ code, allowing you to expose native functions as callbacks with minimal overhead.

Examples

Demonstrates automatic resource management in C++ using RAII and the Owned() method.
				
					using uCalcSoftware;

var uc = new uCalc();


// This example is meant only for C++
Console.Write("Evaluating in scope: 20");

				
			
Evaluating in scope: 20
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;

   // Create a uCalc object on the stack.
   uCalc myCalc;
   // Flag it as 'owned' to enable automatic cleanup.
   myCalc.Owned();

   myCalc.DefineVariable("x=10");
   cout << "Evaluating in scope: " << myCalc.Eval("x*2");

   // When 'myCalc' goes out of scope at the end of the block,
   // its destructor is called, which automatically calls Release().


}
				
			
Evaluating in scope: 20
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      
      '// This example is meant only for C++
      Console.Write("Evaluating in scope: 20")
      
   End Sub
End Module
				
			
Evaluating in scope: 20
Previous
Next