[revisit]

✨ Introduction to Smart Strings

Welcome to the uCalc.String library! This is uCalc's answer to the limitations of standard string types. While native strings are great for storage, they are often inefficient for complex manipulation. uCalc.String is a high-performance, mutable, and token-aware string class designed from the ground up for parsing and transformation tasks.

Think of it as a StringBuilder on steroids, combining the features of a text builder, a lightweight transformation engine, and a list processor into a single, fluent API.

1. ⚡ Mutability & Performance

The biggest difference from a standard string is mutability. Native strings are immutable; every modification (like a replace or append) creates a brand new string object in memory, which is inefficient. uCalc.String is designed to be modified in-place, making it ideal for building or manipulating text in loops.

// Standard strings create new objectsvar s = "Hello";s = s + " World"; // 's' now points to a new string object// uCalc.String modifies its internal buffervar ucs = new uCalc.String("Hello");ucs.Append(" World"); // The existing object is modified

2. 🧠 Token-Aware Operations

This is the "smart" part of Smart Strings. Unlike Regex or standard string.Replace(), which are character-aware, uCalc.String is token-aware. It understands the structure of your text.

By default, operations like SubString() or Replace() don't count characters; they count tokens (words, numbers, symbols). This provides structural safety, automatically respecting word boundaries, quoted strings, and nested brackets.

3. ⛓️ Fluent Chaining & Live Views

uCalc.String is designed for a fluent, chainable API. Methods can be linked together to create powerful "one-liner" transformations.

Crucially, methods that extract a portion of a string (like After() or Between()) don't return a disconnected copy. They return a new uCalc.String object that is a live, modifiable view into the parent. Any changes made to the child view are instantly reflected in the original parent string.

This architecture enables powerful editing pipelines and is a core concept you'll see in the following examples.

uCalc.String vs. Transformer

• uCalc.String: Best for fluent, single-string "one-liner" transformations. Think of it as a scripting tool for quick modifications.
• Transformer: Best for managing a complex set of reusable rules or performing multi-pass transformations. Think of it as a compiler for text.

They share the same underlying engine but offer different interfaces for different tasks. Ready to see it in action?