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.

Whitespace Retention $

Product: 

Class: 

Remarks

Whitespace Retention

[Note: for now the $ character is what's implemented instead of _]

Shortcut: _ (underscore)Associated Method: uCalc.Rule.WhitespaceCounts(bool)

Description: A postfix modifier that determines whether leading and trailing whitespace surrounding a matched token is captured as part of the variable's value.

By default, uCalc is "Whitespace Aware" in a way that prioritizes data cleanliness. When a pattern variable (like {v}) captures a token, the engine automatically strips any horizontal whitespace (spaces or tabs) that immediately precedes or follows that token. This ensures that a capture like 123 results in the clean string 123.

The Whitespace Retention (_) modifier is used to override this stripping behavior.

Default vs. Retention Behavior

  • Default (Stripped): Whitespace is matched by the engine to satisfy the pattern but is not included in the variable's stored string.
  • Retention ({v_}): Every whitespace character encountered that belongs to the variable's capture zone is preserved. This is essential for formatting-sensitive transformations.

The WhitespaceCounts() Method

You can toggle this behavior globally using the WhitespaceCounts() method on the uCalc object.

  • uc.WhitespaceCounts(false): (Default) Variables strip surrounding whitespace.
  • uc.WhitespaceCounts(true): All variables behave as if they have the _ postfix, retaining whitespace by default.

Examples

1. Succinct (Stripping vs. Retention)

Comparing how the engine handles a word surrounded by spaces.

New(uCalc::Transformer, t)// Default: " Word " results in "[Word]"t.FromTo("find {v}", "GOT:[{v}]")// Retention: " Word " results in "[ Word ]"t.FromTo("keep {v_}", "GOT:[{v}]")wl(t.Transform("find  Hello ")) // Output: GOT:[Hello]wl(t.Transform("keep  Hello ")) // Output: GOT:[ Hello ]

2. Practical (Preserving Alignment)

When moving or wrapping blocks of text where the original horizontal alignment or indentation is part of the data's meaning.

New(uCalc::Transformer, t)// Use '_' to ensure indentation is kept when wrapping lines in tagst.FromTo("{line_}", "<li>{line}</li>")wl(t.Transform("    Indented Line"))

[Expected Output]<li> Indented Line</li>

3. Internal Test (Global Configuration)

Verifying that enabling global whitespace retention makes all variables include padding by default.

// Enable whitespace retention globallyuc.WhitespaceCounts(true)New(uCalc::Transformer, t)t.FromTo("id {v}", "ID:{v}")wl(t.Transform("id   101"))

[Expected Output]ID: 101

Strategy & Critique

  • Data Integrity: Default stripping is usually what you want for mathematical or logical evaluation (e.g., passing a number to {@Eval}).
  • Visual Integrity: Retention is what you want for document reconstruction, code prettifiers, or transpilers where the "look" of the source is as important as the content.
  • Naming: WhitespaceCounts() is the established method name, though Whitespace Retention is used here as the descriptive title to better contrast with the default "stripping" behavior.
  • See Also: Refer to Topic 801 (Whitespace Directive) and Topic 812 (Newline Directive) for structural spacing controls.

Examples

WhitespaceCounts

ID: 215

See: Whitespace Retention $ 
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();

t.FromTo("A {txtA}. B {txtB$}.", "<{txtA}> <{txtB}>");

Console.WriteLine(t.Transform("A     x y z . B     x y z ."));
				
			
<x y z> <     x y z >
Explore 600+ other examples
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();

   t.FromTo("A {txtA}. B {txtB$}.", "<{txtA}> <{txtB}>");

   cout << t.Transform("A     x y z . B     x y z .") << endl;
}
				
			
<x y z> <     x y z >
Explore 600+ other examples
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      
      t.FromTo("A {txtA}. B {txtB$}.", "<{txtA}> <{txtB}>")
      
      Console.WriteLine(t.Transform("A     x y z . B     x y z ."))
   End Sub
End Module
				
			
<x y z> <     x y z >
Explore 600+ other examples