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.

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
				
					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 >
				
					#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 >
				
					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 >
Previous
Next