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.

ApplyOffset

Method

Product: 

Transformer Library

Class: 

Matches

Adjusts the start and end positions of all matches in the collection by a specified offset value.

Syntax

ApplyOffset(int64)

Parameters

offset
int64
(Default = 0)
The integer value to add to the `StartPosition` and `EndPosition` of every match in the collection. This value can be negative.

Return

int64

Returns the number of matches in the collection whose positions were updated.

Remarks

The Offset method provides a crucial utility for remapping match coordinates. It modifies the StartPosition and EndPosition of every match in the collection by adding the specified offset value. This is an in-place modification.

🎯 Primary Use Case: Remapping Local Coordinates

This method is most powerful when you perform a search on a substring of a larger document. The resulting matches will have positions relative to the start of the substring (index 0), not the original document. Offset allows you to easily translate these local coordinates back into the global coordinate space of the original document.

Consider the following workflow:

  1. Extract a portion of a large text document.
  2. Run a Find() operation on that smaller portion.
  3. Determine the starting position of the substring within the original document.
  4. Call Offset() on the resulting Matches collection, passing the substring's starting position as the offset.

After this operation, the StartPosition and EndPosition of each match will correctly reflect its location within the original, full document.

💡 Comparative Analysis

Without this method, remapping coordinates would require a manual loop, which is both verbose and error-prone:

// Manual, less efficient wayfor ( i = 0; i <= matches.Count() - 1; i++) {    var oldPos = matches[i].StartPosition;    matches[i].StartPosition = oldPos + globalOffset;    // ... and repeat for EndPosition ...}

The Offset method provides a single, high-performance, atomic operation that handles this logic internally, leading to cleaner and more reliable code.

Examples

A simple demonstration of adding a fixed offset to a match's coordinates.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer().SetText("The quick brown fox jumps over.");
t.Pattern("fox");
t.Find();

var matches = t.Matches;
Console.WriteLine($"Original Start Position: {matches[0].StartPosition}");

// Add an offset of 100 to all match positions
matches.ApplyOffset(100);

Console.WriteLine($"New Start Position: {matches[0].StartPosition}");
				
			
Original Start Position: 16
New Start Position: 116
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer().SetText("The quick brown fox jumps over.");
   t.Pattern("fox");
   t.Find();

   auto matches = t.Matches();
   cout << "Original Start Position: " << matches[0].StartPosition() << endl;

   // Add an offset of 100 to all match positions
   matches.ApplyOffset(100);

   cout << "New Start Position: " << matches[0].StartPosition() << endl;
}
				
			
Original Start Position: 16
New Start Position: 116
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer().SetText("The quick brown fox jumps over.")
      t.Pattern("fox")
      t.Find()
      
      Dim matches = t.Matches
      Console.WriteLine($"Original Start Position: {matches(0).StartPosition}")
      
      '// Add an offset of 100 to all match positions
      matches.ApplyOffset(100)
      
      Console.WriteLine($"New Start Position: {matches(0).StartPosition}")
   End Sub
End Module
				
			
Original Start Position: 16
New Start Position: 116
A practical example showing how to remap a match found in a substring back to the global coordinates of the original document.
				
					using uCalcSoftware;

var uc = new uCalc();
string document = "HEADER::BEGIN[data to find]END::FOOTER";

// 1. Isolate the content block we want to search in.
// Assume the block we care about is between BEGIN and END.
var startIndex = document.IndexOf("BEGIN[") + 6;
var endIndex = document.IndexOf("]END");
var contentLength = endIndex - startIndex;
var contentBlock = document.Substring(startIndex, contentLength);
Console.WriteLine($"Searching within substring: '{contentBlock}'");

// 2. Perform a find operation on just that substring.
var t = uc.NewTransformer().SetText(contentBlock);
t.Pattern("find");
t.Find();
var matches = t.Matches;

Console.WriteLine($"Local match StartPosition: {matches[0].StartPosition}"); // Relative to 'contentBlock'

// 3. Apply the offset to remap to the global 'document' coordinate space.
matches.ApplyOffset(startIndex);

Console.WriteLine($"Global match StartPosition: {matches[0].StartPosition}");
				
			
Searching within substring: 'data to find'
Local match StartPosition: 8
Global match StartPosition: 22
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   string document = "HEADER::BEGIN[data to find]END::FOOTER";

   // 1. Isolate the content block we want to search in.
   // Assume the block we care about is between BEGIN and END.
   auto startIndex = document.find("BEGIN[") + 6;
   auto endIndex = document.find("]END");
   auto contentLength = endIndex - startIndex;
   auto contentBlock = document.substr(startIndex, contentLength);
   cout << "Searching within substring: '" << contentBlock << "'" << endl;

   // 2. Perform a find operation on just that substring.
   auto t = uc.NewTransformer().SetText(contentBlock);
   t.Pattern("find");
   t.Find();
   auto matches = t.Matches();

   cout << "Local match StartPosition: " << matches[0].StartPosition() << endl; // Relative to 'contentBlock'

   // 3. Apply the offset to remap to the global 'document' coordinate space.
   matches.ApplyOffset(startIndex);

   cout << "Global match StartPosition: " << matches[0].StartPosition() << endl;
}
				
			
Searching within substring: 'data to find'
Local match StartPosition: 8
Global match StartPosition: 22
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim Document As String = "HEADER::BEGIN[data to find]END::FOOTER"
      
      '// 1. Isolate the content block we want to search in.
      '// Assume the block we care about is between BEGIN and END.
      Dim startIndex = document.IndexOf("BEGIN[") + 6
      Dim endIndex = document.IndexOf("]END")
      Dim contentLength = endIndex - startIndex
      Dim contentBlock = document.Substring(startIndex, contentLength)
      Console.WriteLine($"Searching within substring: '{contentBlock}'")
      
      '// 2. Perform a find operation on just that substring.
      Dim t = uc.NewTransformer().SetText(contentBlock)
      t.Pattern("find")
      t.Find()
      Dim matches = t.Matches
      
      Console.WriteLine($"Local match StartPosition: {matches(0).StartPosition}") '// Relative to 'contentBlock'
      
      '// 3. Apply the offset to remap to the global 'document' coordinate space.
      matches.ApplyOffset(startIndex)
      
      Console.WriteLine($"Global match StartPosition: {matches(0).StartPosition}")
   End Sub
End Module
				
			
Searching within substring: 'data to find'
Local match StartPosition: 8
Global match StartPosition: 22
Previous
Next