⚙️ State, Scoping, and Context Management

The uCalc engine is not a collection of static functions; it is a stateful, object-oriented system. Understanding how it manages state, scope, and context is crucial for building robust, scalable, and memory-safe applications. This topic provides a high-level overview of the core architectural concepts that govern the uCalc environment.

Mastering these concepts will allow you to leverage the full power of the library, from creating isolated sandboxes for parallel processing to building sophisticated, multi-layered parsers.

1. 📦 The uCalc Instance: An Isolated Sandbox

Each instance of the uCalc class is a self-contained "world." It maintains its own isolated symbol table, which includes all defined variables, functions, and operators.

This instance-based architecture ensures that different parser configurations do not interfere with each other, making it ideal for applications with plugins or multiple concurrent tasks. For details on managing the memory of these instances, see the Managing Parser Instances & Lifetime tutorial.

2. 🌍 The Default Instance Stack: A Scoped Global Context

For convenience, uCalc provides a globally accessible context via the static DefaultInstance property. However, this is not a single, rigid global object; it is a LIFO (Last-In, First-Out) stack.

• You can push any uCalc instance onto the stack using IsDefault(true), making it the new "ambient" context.
• When that instance is released or popped from the stack (e.g., via IsDefault(false)), the previous default instance is automatically restored.

This provides the benefits of a global singleton without the rigidity, enabling temporary, scoped overrides for different parts of an application.

3. 🧵 Thread Safety: Clone for Parallelism

• Core Rule: A single uCalc instance is not thread-safe. Do not share one instance across multiple threads without external locking (which is an anti-pattern).
• The Solution: The "One Instance Per Thread" pattern is the recommended approach. You create a master, pre-configured instance at startup, and for each new thread or task, you create a local copy using the highly optimized Clone() method.
• Thread-Local Default: The default instance stack is managed using thread-local storage. This means each thread has its own independent default instance stack, preventing cross-thread interference automatically.

For a detailed explanation, see the Thread safety topic.

4. 🌳 Hierarchical Scopes: Parsing and Data

In addition to instance-level isolation, uCalc provides two powerful mechanisms for managing nested scopes within a single operation.

A. Syntactic Scoping (LocalTransformer)

A Rule can have its own LocalTransformer, which is a nested Transformer that operates only on the text matched by its parent rule. This is the primary mechanism for hierarchical parsing of structured languages like HTML or XML. See the Hierarchical Parsing (LocalTransformer) topic for more details.

B. Data Scoping (Live Views)

The uCalc.String class uses "live views." Methods like After(), Before(), and Between() return new uCalc.String objects that are modifiable windows into the parent. Any change to a child view directly affects the parent, enabling powerful, in-place editing of sub-sections. See Chaining Fluent Operations.

⚖️ Comparative Analysis

uCalc's state and context management model provides distinct advantages over common paradigms:

• vs. Global Singletons: uCalc's stack-based default is safer and more flexible for modular applications than a typical static singleton, as it allows for temporary, scoped overrides.
• vs. Dependency Injection: While DI is a powerful pattern, uCalc's default instance provides a simpler "ambient context" model that can reduce boilerplate for ubiquitous components like a parser engine.
• vs. Manual Substring Manipulation: The LocalTransformer and live views automate complex scoping and coordinate-mapping tasks that would require verbose, error-prone manual implementation with standard string and regex libraries.