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.

Shortcut notations

Product: 

Class: 

Explains how implicit operators in C#, VB.NET, and C++ allow for more natural and concise code by treating uCalc objects like native strings.

Remarks

🪄 Shortcut Notations

uCalc leverages language features like operator overloading to provide syntactic sugar. This allows certain uCalc objects—specifically Expression, String, and Transformer—to be treated as if they were native strings, significantly reducing boilerplate code and improving readability.

These shortcuts are made possible by the ability in C#, VB.NET, and C++ to define custom, implicit conversions to and from the string type.

1. Expression Shortcuts

The Expression object has the most powerful set of shortcuts, simplifying both parsing and evaluation.

  • Implicit Parse on Assignment: When you assign a string to an Expression variable, uCalc automatically calls the object's Parse method behind the scenes.

    • Verbose Way: expr.Parse("5+4");
    • Shortcut: expr = "5+4";

  • Implicit EvaluateStr on ToString(): When an Expression object is used in a context that requires a string (like wl() or string concatenation), its ToString() method is implicitly called, which in turn executes EvaluateStr().

    • Verbose Way: Console.WriteLine(expr.EvaluateStr());
    • Shortcut: Console.WriteLine(expr);

2. String and Transformer Shortcuts

For String and Transformer objects, assignment to and from a string literal acts as a shortcut for accessing the object's primary text property.

  • Assignment to Object: Assigning a string to the object variable is equivalent to setting its Text property.

    • Verbose Way: t.Text = "Hello World";
    • Shortcut: t = "Hello World";

  • Assignment from Object: Assigning the object to a string variable is equivalent to getting its Text property.

    • Verbose Way: var result = t.Text;
    • Shortcut: var result = t;

💡 Why uCalc? (Comparative Analysis)

This API design demonstrates a focus on developer experience. Most classes in standard libraries require explicit property access (e.g., StringBuilder.ToString(), StreamReader.ReadToEnd()). By providing implicit conversions, uCalc's objects feel more like built-in language primitives. This thoughtful design choice makes code more intuitive and less verbose, allowing developers to focus on their logic rather than on API boilerplate.

Examples

Demonstrates implicit parsing on assignment and implicit evaluation when writing to the console.
				
					using uCalcSoftware;

var uc = new uCalc();
var expr = new uCalc.Expression("3+4");
Console.WriteLine($"Initial: {expr}"); // Implicit EvaluateStr

expr = "20+100"; // Implicit Parse
Console.WriteLine($"Reassigned: {expr}"); // Implicit EvaluateStr
				
			
Initial: 7
Reassigned: 120
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Expression expr("3+4");
   cout << "Initial: " << expr << endl; // Implicit EvaluateStr

   expr = "20+100"; // Implicit Parse
   cout << "Reassigned: " << expr << endl; // Implicit EvaluateStr
}
				
			
Initial: 7
Reassigned: 120
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim expr As New uCalc.Expression("3+4")
      Console.WriteLine($"Initial: {expr}") '// Implicit EvaluateStr
      
      expr = "20+100" '// Implicit Parse
      Console.WriteLine($"Reassigned: {expr}") '// Implicit EvaluateStr
   End Sub
End Module
				
			
Initial: 7
Reassigned: 120
Shows how implicit conversions simplify using uCalc objects for text manipulation.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = new uCalc.Transformer();
var s = new uCalc.String();

// Implicitly set the Text property
t = "Source text with foo.";
s = "bar";

// Use the objects in a standard way
t.FromTo("foo", s.Text);
t.Transform();

// Implicitly get the Text property
Console.WriteLine(t);
				
			
Source text with bar.
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Transformer t;
   uCalc::String s;

   // Implicitly set the Text property
   t = "Source text with foo.";
   s = "bar";

   // Use the objects in a standard way
   t.FromTo("foo", s.Text());
   t.Transform();

   // Implicitly get the Text property
   cout << t << endl;
}
				
			
Source text with bar.
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t As New uCalc.Transformer()
      Dim s As New uCalc.String()
      
      '// Implicitly set the Text property
      t = "Source text with foo."
      s = "bar"
      
      '// Use the objects in a standard way
      t.FromTo("foo", s.Text)
      t.Transform()
      
      '// Implicitly get the Text property
      Console.WriteLine(t)
   End Sub
End Module
				
			
Source text with bar.
Internal Test: Verifies error handling with implicit parsing and evaluation.
				
					using uCalcSoftware;

var uc = new uCalc();
var expr = new uCalc.Expression();

// Implicitly parse an invalid expression. This sets an error state.
expr = "5 * (10 +";

// Implicit EvaluateStr should not throw but return the error message.
Console.WriteLine($"Error Message: {expr}");

// Verify the error code is set.
Console.WriteLine($"Error Code: {(int)expr.uCalc.Error.Code}");

// Now, assign a valid expression.
expr = "10 + 20";

// The new assignment should clear the error state.
Console.WriteLine($"Valid Result: {expr}");
Console.WriteLine($"Error Code after success: {(int)expr.uCalc.Error.Code}");
				
			
Error Message: Bracket delimiter error
Error Code: 265
Valid Result: 30
Error Code after success: 0
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   uCalc::Expression expr;

   // Implicitly parse an invalid expression. This sets an error state.
   expr = "5 * (10 +";

   // Implicit EvaluateStr should not throw but return the error message.
   cout << "Error Message: " << expr << endl;

   // Verify the error code is set.
   cout << "Error Code: " << (int)expr.uCalc().Error().Code() << endl;

   // Now, assign a valid expression.
   expr = "10 + 20";

   // The new assignment should clear the error state.
   cout << "Valid Result: " << expr << endl;
   cout << "Error Code after success: " << (int)expr.uCalc().Error().Code() << endl;
}
				
			
Error Message: Bracket delimiter error
Error Code: 265
Valid Result: 30
Error Code after success: 0
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim expr As New uCalc.Expression()
      
      '// Implicitly parse an invalid expression. This sets an error state.
      expr = "5 * (10 +"
      
      '// Implicit EvaluateStr should not throw but return the error message.
      Console.WriteLine($"Error Message: {expr}")
      
      '// Verify the error code is set.
      Console.WriteLine($"Error Code: {CInt(expr.uCalc.Error.Code)}")
      
      '// Now, assign a valid expression.
      expr = "10 + 20"
      
      '// The new assignment should clear the error state.
      Console.WriteLine($"Valid Result: {expr}")
      Console.WriteLine($"Error Code after success: {CInt(expr.uCalc.Error.Code)}")
   End Sub
End Module
				
			
Error Message: Bracket delimiter error
Error Code: 265
Valid Result: 30
Error Code after success: 0
Previous
Next