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.

Introduction

Product: 

String Library

Class: 

String

An overview of the uCalc.String class, a mutable, token-aware string object designed for high-performance, chainable text manipulation.

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, similar to a StringBuilder but with far more functionality.

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, or user-defined constructs like 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. uCalc.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.

📖 Class Member Reference

Below is a list of members available on the uCalc.String class, grouped by functionality.

These methods return a new uCalc.String object that is a live view into a portion of the original.

MemberDescription
AfterCreates a live, modifiable view of the substring that follows a specified pattern match.
BeforeCreates a live, modifiable view of the substring that precedes a specified pattern match.
BetweenCreates a live, modifiable view of the substring located between two specified patterns.
BetweenInclusiveCreates a live, modifiable view of the substring that includes the text between two specified patterns and the patterns themselves.
StartingFromCreates a live, modifiable view of the substring that begins with and includes a specified pattern match.
SubStringExtracts a substring of a specified length starting at a given token position.
UpToReturns a substring with all text up to and including the matched pattern.

✍️ Modification & Transformation

These methods modify the string's content in-place or change its representation.

MemberDescription
FindSearches for occurrences of a pattern, populating the internal match list.
RemoveRemoves all occurrences of a specified pattern from the string.
ReplaceReplaces all occurrences of a specified pattern with a new string.
ToLowerConverts the string or a specified pattern match to lowercase.
ToUpperConverts the string or a specified pattern match to uppercase.
MapApplies a transformation expression to each item in the string's internal list.
TransformApplies the rules of a specified Transformer object to this string.

🧐 Inspection & State

These members return information about the string's content or state.

MemberDescription
TextGets or sets the full text content of the string object.
CountGets the number of items in the string's current view (e.g., tokens, matches, lines).
ParentRetrieves the parent uCalc.String object from which this view was created.
RootRetrieves the top-level uCalc.String object in a chain of views.
uCalcRetrieves the parent uCalc instance that provides the execution context.
DescriptionGets or sets a user-defined description for the object.

Examples

A practical example of parsing a value from a simple key-value pair in a configuration string.
				
					using uCalcSoftware;

var uc = new uCalc();
using (var s = new uCalc.String("User: admin; Role: user; Department: Sales;")) {
   
   // Extract the text between 'Department: ' and the trailing semicolon
   var department = s.Between("Department: ", ";");

   Console.WriteLine($"Department is '{department}'");
}
				
			
Department is ' Sales'
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::String s("User: admin; Role: user; Department: Sales;");
      s.Owned(); // Causes s to be released when it goes out of scope

      // Extract the text between 'Department: ' and the trailing semicolon
      auto department = s.Between("Department: ", ";");

      cout << "Department is '" << department << "'" << endl;
   }
}
				
			
Department is ' Sales'
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using s As New uCalc.String("User: admin; Role: user; Department: Sales;")
         
         '// Extract the text between 'Department: ' and the trailing semicolon
         Dim department = s.Between("Department: ", ";")
         
         Console.WriteLine($"Department is '{department}'")
      End Using
   End Sub
End Module
				
			
Department is ' Sales'
Chains `Before` and `Replace` to modify only the scheme of a URL, demonstrating the live view concept.
				
					using uCalcSoftware;

var uc = new uCalc();
using (var url = new uCalc.String("http://example.com")) {
   Console.WriteLine($"Original URL: {url}");
   // Get a view of the scheme part
   var schemeView = url.Before("://");
   // Modify the view
   schemeView.Replace("http", "https");
   // The original string is updated
   Console.WriteLine($"Modified URL: {url}");
}
				
			
Original URL: http://example.com
Modified URL: https://example.com
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   {
      uCalc::String url("http://example.com");
      url.Owned(); // Causes url to be released when it goes out of scope
      cout << "Original URL: " << url << endl;
      // Get a view of the scheme part
      auto schemeView = url.Before("://");
      // Modify the view
      schemeView.Replace("http", "https");
      // The original string is updated
      cout << "Modified URL: " << url << endl;
   }
}
				
			
Original URL: http://example.com
Modified URL: https://example.com
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Using url As New uCalc.String("http://example.com")
         Console.WriteLine($"Original URL: {url}")
         '// Get a view of the scheme part
         Dim schemeView = url.Before("://")
         '// Modify the view
         schemeView.Replace("http", "https")
         '// The original string is updated
         Console.WriteLine($"Modified URL: {url}")
      End Using
   End Sub
End Module
				
			
Original URL: http://example.com
Modified URL: https://example.com
Previous
Next