✅ uCalc Best Practices: A Developer's Guide

Welcome to the guide for writing effective, high-performance, and maintainable code with uCalc. While the library is designed to be flexible, adhering to these core principles will help you leverage its full power, avoid common pitfalls, and build robust applications.

This guide consolidates the most important concepts into five key areas.

1. 🚀 Performance First: The "Parse-Once, Evaluate-Many" Rule

This is the single most important principle for performance. While convenience methods like EvalStr are great for one-off calculations, they are inefficient in loops because they re-parse the expression string on every call.

• The Wrong Way: Calling Eval() or EvalStr() inside a loop.
• The Right Way: Call Parse() once before the loop to create a compiled Expression object. Then, call Evaluate() on that object inside the loop.

This pattern separates the expensive parsing step from the lightning-fast evaluation step, allowing your code to run at speeds approaching native execution.

➡️ Learn More: Optimizing Performance

2. 🛡️ Safety & Security: Sandbox and Structure

A. Trust the Sandbox

uCalc is a secure sandbox by default. Unlike eval() functions in scripting languages, a uCalc expression has no intrinsic access to the file system, network, or operating system. Leverage this safety by default, especially when processing untrusted user input. Be extremely cautious about creating callbacks that expose risky OS-level functions.

B. Prefer the Transformer over Regex for Code

For transforming structured text like source code or configuration files, always use the token-aware Transformer instead of regular expressions. Regex is character-aware and can easily corrupt text inside string literals or comments. The Transformer understands these structures and is safe by default.

➡️ Learn More: Structural Awareness (Tokens vs. Regex)

3. 🧩 Readability & Maintainability: Build a DSL

Don't just write complex formulas; build a Domain-Specific Language (DSL). Instead of embedding a long, cryptic expression in your code, create custom functions and operators that make the logic human-readable.

• Instead of This: (principal * (rate/12)) / (1 - (1 + rate/12)^-(years*12))
• Do This: LoanPayment(principal, rate, years)

Use DefineFunction() for new functions and DefineOperator() for new operators. For multi-word syntax, use the ExpressionTransformer. This makes your expressions cleaner, easier to debug, and more maintainable.

➡️ Learn More: Creating Custom Functions and Dynamic Syntax

4. ⚙️ Memory Management: Embrace Scoping

uCalc objects wrap powerful C++ resources and must be released to prevent memory leaks. While you can call Release() manually, the best practice is to use language-idiomatic scoping mechanisms.

• C# / VB.NET: Always create uCalc objects within a using block.
• C++: Use RAII by creating objects on the stack and calling Owned().

This guarantees that resources are cleaned up automatically when an object goes out of scope, making your code safer and more robust.

➡️ Learn More: Managing Parser Instances & Lifetime

5. 💣 Error Handling: Recover, Don't Just Crash

For parsing user input, errors are normal, not exceptional. uCalc's state-based error handling model is more lightweight and flexible than traditional try/catch blocks.

Embrace this by creating an error handler with AddHandler(). The most powerful pattern is to use the Resume response to build self-healing parsers. For example, if a Undefined_Identifier error occurs, your handler can automatically define the variable and instruct the engine to continue, providing a seamless user experience.

➡️ Learn More: Handling Errors