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.

C#

Product: 

Class: 

Covers C#-specific features, syntax, and lifetime management patterns 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. Properties vs. Methods

Many uCalc members documented as properties (getters/setters) can be accessed using C# property syntax (=) instead of method calls (()). This provides cleaner, more readable code.

FeatureC# SyntaxC++ Syntax
Setteruc.Description = "text";uc.Description("text");
Getterd = uc.Description;var d = uc.Description();

For a detailed overview, see the Properties / Getters / Setters topic.

2. Indexers ([])

Collections like Tokens and Matches support C# indexers ([]) for direct access to elements. This is a convenient shortcut for methods like ByName() or At().

// Instead of this:var token = uc.ExpressionTokens.ByName("_token_alphanumeric");// You can write this:var token = uc.ExpressionTokens["_token_alphanumeric"];

3. foreach Loop Integration

All uCalc collection objects (e.g., Matches, Tokens, Items) implement IEnumerable. This means you can iterate over them directly using a standard C# foreach loop, which is simpler and safer than a manual for loop with an index.

foreach(var rule in myTransformer.Rules) {{    Console.WriteLine(rule.Name);}

4. Lifetime Management with using

This is the most critical C#-specific pattern. Most uCalc objects hold unmanaged resources and must be released to prevent memory leaks. While you can call Release() manually, the idiomatic C# approach is to wrap object creation in a using statement. All major uCalc objects implement IDisposable, which guarantees that Release() will be called automatically when the object goes out of scope.

// The transformer 't' will be released automatically at the end of the block.using (var t = uc.NewTransformer()){    Console.WriteLine(t.Transform("input"));} // t.Release() is called here.

This is the C# equivalent of the C++ RAII pattern using Owned().

5. Implicit Conversions & Constructors

For convenience, several uCalc classes provide implicit conversions from string, allowing for more concise initialization.

  • uCalc.String: uCalc.String s = "initial text";
  • uCalc.Expression: uCalc.Expression expr = "1 + 1";
  • uCalc.Transformer: t.Text = "input"; can be shortened to t = "input";

The Expression and String classes also have constructors that accept a string, which provides a familiar C# object creation pattern that implicitly uses the default uCalc instance.

// These two are equivalent, using the default uCalc instance.var expr1 = uc.Parse("5 * 2");var expr2 = new uCalc.Expression("5 * 2");

🆚 Comparative Analysis: Why uCalc in C#?

While C# is a powerful language, uCalc provides specialized capabilities not available natively:

  • Runtime Parsing vs. DataTable.Compute: The common C# workaround for evaluating strings, DataTable.Compute, is slow, limited to simple arithmetic, and lacks features like custom functions or operators. uCalc is a high-performance, full-featured parsing engine.

  • Dynamic Language Definition: C# is statically compiled. uCalc allows you to define new functions, operators, and even token syntax at runtime, enabling the creation of dynamic scripting environments and Domain-Specific Languages (DSLs) within your C# application.

  • Token-Aware Transformations: C#'s 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), which is far more robust for code transformation and analysis.

Examples

Succinct: Demonstrates the core C# idioms: `using` for lifetime management, property syntax for setters/getters, and implicit string conversions.
				
					using uCalcSoftware;

var uc = new uCalc();

// 1. Automatic resource management with 'using'
using (var u = new uCalc()) {
   // 2. Property syntax for setting the description
   u.Description = "My C# uCalc instance";
   Console.WriteLine($"Description: {u.Description}");

   // 3. Implicit string conversion for Transformer.Text
   var t = new uCalc.Transformer();
   t.Text = "Hello World"; // Standard assignment
   t = "Hello Again";    // Implicit conversion assignment
   Console.WriteLine($"Transformer Text: {t.Text}");

}


				
			
Description: My C# uCalc instance
Transformer Text: Hello Again
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;


   // This example is meant for C# only
   cout << "Description: My C# uCalc instance" << endl;
   cout << "Transformer Text: Hello Again" << endl;

}
				
			
Description: My C# uCalc instance
Transformer Text: Hello Again
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      
      
      '// This example is meant for C# only
      Console.WriteLine("Description: My C# uCalc instance")
      Console.WriteLine("Transformer Text: Hello Again")
      
   End Sub
End Module
				
			
Description: My C# uCalc instance
Transformer Text: Hello Again
Previous
Next