✨ uCalc.String: The Smart String Builder

The uCalc.String object is a powerful, mutable string class designed for high-performance text manipulation. It goes far beyond a standard string or StringBuilder, acting as a hybrid of three components in one:

1. A Mutable String Builder: Efficiently modify, append, and replace text without the performance penalty of creating new string objects for every change.
2. A Lightweight Transformation Engine: Perform token-aware find-and-replace operations using a fluent, chainable API.
3. A List Processor: Treat a string's contents—or the results of a search—as a collection that can be iterated, filtered, and transformed.

Its core design philosophy is to provide a rich, fluent interface for single-string operations. For managing complex sets of reusable rules or multi-pass transformations, the more powerful uCalc.Transformer is the preferred tool.

⚙️ Core Concepts

1. ⚡ Mutability and Performance

Unlike native string types in C# and other languages, which are immutable, uCalc.String is designed to be modified in-place. This makes it highly efficient for building or manipulating strings in a loop.

2. 🧠 Token-Aware Operations

By default, all operations (like SubString, After, and Before) are token-based, not character-based. The string is first broken down into tokens (words, numbers, symbols), and operations are performed on this stream. This provides structural awareness, safely handling nested brackets, quotes, and comments.

3. ⛓️ Chaining and Live Views

Methods that extract a portion of a string (e.g., SubString, After, Between) do not create a disconnected copy. Instead, they return a new uCalc.String object that is a live, modifiable view into the parent.

• Operations are chained, flowing from parent to child.
• Modifying a child string directly modifies the content of its parent.

This architecture enables powerful, non-destructive editing pipelines.

4. 📜 List-like Behavior

After a Find() operation or by calling methods like ListOfTokens(), the uCalc.String object begins to act like a collection of results. Subsequent chained operations are then applied to each item in that collection, enabling powerful batch processing with methods like Map().

uCalc.String vs. Transformer

It's important to choose the right tool for the job. While both share the same underlying tokenization engine, they offer different interfaces for different tasks:

• uCalc.String: Best for fluent, single-string "one-liner" transformations. Think of it as a scripting tool for quick modifications and data extraction on a single piece of text.

• Transformer: Best for building a robust, rule-based system. It excels at managing a complex set of reusable rules or performing multi-pass transformations. Think of it as a compiler for text.