uCalc API Version: 5.7.0-preview.1 Released: 7/30/2026

Warning

uCalc API Preview Release Notice:This preview documentation describes the intended behavior of the API. It is not fully accurate or complete.The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.Use of the preview version in your production code is not recommended.

(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

A simple find-and-replace operation using the fluent, chainable API.

ID: 1156

See: (Constructor) 
				
					using uCalcSoftware;

var uc = new uCalc();
using (var s = new uCalc.String("The quick brown fox.")) {
   
   // Replace returns the modified String object
   s.Replace("brown", "red");

   // Use implicit conversion to print the result
   Console.WriteLine(s);
}
				
			
The quick red fox.
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::String s("The quick brown fox.");
      s.Owned(); // Causes s to be released when it goes out of scope

      // Replace returns the modified String object
      s.Replace("brown", "red");

      // Use implicit conversion to print the result
      cout << s << endl;
   }
}
				
			
The quick red fox.
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using s As New uCalc.String("The quick brown fox.")
         
         '// Replace returns the modified String object
         s.Replace("brown", "red")
         
         '// Use implicit conversion to print the result
         Console.WriteLine(s)
      End Using
   End Sub
End Module
				
			
The quick red fox.
Explore 600+ other examples
Demonstrates interoperability between `Transformer` and `String` objects, and chaining methods to create nested views.

ID: 1159

See: (Constructor) 
				
					using uCalcSoftware;

var uc = new uCalc();
// Create a transformer and perform a transformation
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();

// --- Interoperability and Chaining ---

var Pattern = "if ({cond})";

// 1. Create a uCalc.String from a Transformer.
// 2. Chain .After() to get a "live view" of the text after the pattern.
var s = new uCalc.String(t);
var after_first_if = s.After(Pattern);
Console.WriteLine(after_first_if.Text);

// 3. Chain another .After() on the child string.
var after_second_if = after_first_if.After(Pattern);
Console.WriteLine(after_second_if.Text);

// --- String to Transformer Conversion ---

// 4. Create a uCalc.String and assign it text.
var s2 = new uCalc.String();
s2 = "This is a test";

// 5. Create a Transformer from the uCalc.String to use transformer-specific methods.
var t2 = new uCalc.Transformer(s2);
Console.WriteLine(t2.Text);
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   // Create a transformer and perform a transformation
   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();

   // --- Interoperability and Chaining ---

   auto Pattern = "if ({cond})";

   // 1. Create a uCalc.String from a Transformer.
   // 2. Chain .After() to get a "live view" of the text after the pattern.
   uCalc::String s(t);
   auto after_first_if = s.After(Pattern);
   cout << after_first_if.Text() << endl;

   // 3. Chain another .After() on the child string.
   auto after_second_if = after_first_if.After(Pattern);
   cout << after_second_if.Text() << endl;

   // --- String to Transformer Conversion ---

   // 4. Create a uCalc.String and assign it text.
   uCalc::String s2;
   s2 = "This is a test";

   // 5. Create a Transformer from the uCalc.String to use transformer-specific methods.
   uCalc::Transformer t2(s2);
   cout << t2.Text() << endl;
}
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      '// Create a transformer and perform a transformation
      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()
      
      '// --- Interoperability and Chaining ---
      
      Dim Pattern = "if ({cond})"
      
      '// 1. Create a uCalc.String from a Transformer.
      '// 2. Chain .After() to get a "live view" of the text after the pattern.
      Dim s As New uCalc.String(t)
      Dim after_first_if = s.After(Pattern)
      Console.WriteLine(after_first_if.Text)
      
      '// 3. Chain another .After() on the child string.
      Dim after_second_if = after_first_if.After(Pattern)
      Console.WriteLine(after_second_if.Text)
      
      '// --- String to Transformer Conversion ---
      
      '// 4. Create a uCalc.String and assign it text.
      Dim s2 As New uCalc.String()
      s2 = "This is a test"
      
      '// 5. Create a Transformer from the uCalc.String to use transformer-specific methods.
      Dim t2 As New uCalc.Transformer(s2)
      Console.WriteLine(t2.Text)
   End Sub
End Module
				
			
y = x * 2; else if(x == 5) y = x - 100;
 y = x - 100;
This is a test
Explore 600+ other examples
To_uCalcString

ID: 154

See: (Constructor), (Constructor), Text = [string] 
				
					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
Explore 600+ other examples
				
					#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
Explore 600+ other examples
				
					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
Explore 600+ other examples