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.

(Constructor)

Constructor

Product: 

String Library

Class: 

String

A high-performance, mutable, token-aware string object for complex searching, manipulation, and chained transformations.

Remarks

✨ 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.

Future Direction: The View PropertyA planned View property will allow you to switch the operational context between tokens, characters, lines, bytes, and other units, providing ultimate control over how the string is processed.

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.

🪄 Shortcut Notations

uCalc.String supports implicit conversions, allowing it to be treated like a native string for assignment and output, which significantly reduces boilerplate code. See the Shortcut notations topic for details.

🏗️ Constructor Overloads

A uCalc.String object can be created via its constructor or by using the uCalc.NewString() factory method.

1. New(uCalc::String, myString(initialValue))

This is the most common constructor. It creates a new uCalc.String object in the context of the default uCalc instance.

  • initialValue (optional): The starting text content for the string.

2. New(uCalc::String, myString(ucalcInstance, initialValue))

Creates a new string within the context of a specific uCalc instance, bypassing the default. This is the preferred method when working with multiple, isolated parser environments.

  • ucalcInstance: The parent uCalc engine that provides context.
  • initialValue (optional): The starting text content.

3. New(uCalc::String, myString(uCalc::String::Empty))

Creates an empty placeholder handle that does not allocate significant resources. It can be assigned a real uCalc.String instance later.

🆚 Why uCalc? (Comparative Analysis)

  • vs. StringBuilder: A StringBuilder is for simple concatenation. uCalc.String adds a full, token-aware search and replace engine.
  • vs. Regex: Regex is character-based and struggles with nested or structured text. uCalc.String is token-aware and handles this complexity safely by default.
  • vs. uCalc.Transformer: A Transformer is for managing a complex set of reusable rules. A uCalc.String is for fluent, single-string "one-liner" transformations. They share the same underlying engine but offer different interfaces for different tasks.

Examples

To_uCalcString
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "if (x > 3) y = x * 2; else if(x == 5) y = x - 1;";
t.FromTo("1", "100");
t.Transform();

var Pattern = "if ({cond})";
Console.WriteLine(new uCalc.String(t).After(Pattern).Text);
Console.WriteLine(new uCalc.String(t).After(Pattern).After(Pattern));

var s = new uCalc.String();
s = "This is a test";
Console.WriteLine(new uCalc.Transformer(s).Text);
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("if (x > 3) y = x * 2; else if(x == 5) y = x - 1;");
   t.FromTo("1", "100");
   t.Transform();

   auto Pattern = "if ({cond})";
   cout <<  uCalc::String(t).After(Pattern).Text() << endl;
   cout <<  uCalc::String(t).After(Pattern).After(Pattern) << endl;

   uCalc::String s;
   s = "This is a test";
   cout <<  uCalc::Transformer(s).Text() << endl;
}
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "if (x > 3) y = x * 2; else if(x == 5) y = x - 1;"
      t.FromTo("1", "100")
      t.Transform()
      
      Dim Pattern = "if ({cond})"
      Console.WriteLine(new uCalc.String(t).After(Pattern).Text)
      Console.WriteLine(new uCalc.String(t).After(Pattern).After(Pattern))
      
      Dim s As New uCalc.String()
      s = "This is a test"
      Console.WriteLine(new uCalc.Transformer(s).Text)
   End Sub
End Module
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
Previous
Next