lxRegex exposes TXLSRegex, the stateful backend used by the calculator's regular expression functions; ordinary workbook callers can use the formula APIs described in contextual formula evaluation
The backend uses the bundled PCRE2 10.49 16-bit build with UTF mode, automatic budget callouts and no JIT, with static objects for Delphi and C++Builder Windows targets and supported FPC Linux x64 or macOS ARM64 targets; unsupported backend targets report xrsUnavailable
Each instance owns its compiled pattern, allocator and match contexts; create a separate instance for each simultaneous operation and keep the budget callback's owner alive until the instance is freed
| Public declaration | Contract |
|---|---|
TXLSRegex.Create(ABudget: TXLSRegexBudget) | Allocates backend contexts and retains the optional callback; pass nil for no caller budget, then inspect operation results and Status |
TXLSRegex.Destroy | Releases the compiled pattern, match data and contexts; callers normally invoke Free in a finally block |
TXLSRegex.Compile(Pattern, IgnoreCase): Boolean | Compiles a UTF-16 pattern and prepares its capture storage, replacing any previous pattern; IgnoreCase enables PCRE2 case-insensitive matching and False leaves matching case-sensitive |
TXLSRegex.Match(Text, Offset, NonemptyAtStart, out Offsets): Boolean | Requires a successful compilation, searches from the zero-based UTF-16 offset and returns detached capture offsets; NonemptyAtStart=True requests an anchored, nonempty match at that exact offset, which supports advancing past an empty match |
TXLSRegex.Replace(Text, Replacement, Occurrence, out Value): Boolean | Requires a successful compilation and uses PCRE2 replacement syntax, including numbered and named capture references; zero selects all matches, a positive value selects the one-based occurrence from the start, and a negative value counts from the end |
TXLSRegex.Check(AWork, AExtraBytes): Boolean | Calls the budget callback with the current work increment and resident backend bytes plus AdditionalBytes and the proposed extra bytes; negative byte accounting, integer overflow or a latched terminal status returns False |
TXLSRegex.Status: TXLSRegexStatus | Read-only status for the latest operation or terminal budget/backend condition; use it after an operation returns False to distinguish a missing match from failure |
TXLSRegex.CaptureCount: Cardinal | Read-only number of explicit capture groups reported by the most recently compiled pattern, excluding the whole-match slot; use it after Compile succeeds |
TXLSRegex.AdditionalBytes: Int64 | Read/write accounting for caller-owned temporary buffers that should participate in every budget check; it defaults to zero and does not allocate memory itself |
TXLSRegexOffsets is a dynamic array of NativeUInt with two elements per slot; slot zero contains the whole match, followed by explicit capture groups in declaration order
Every pair is a zero-based start and exclusive end measured in UTF-16 code units, rather than Delphi's one-based string indices or Unicode scalar positions; an unset optional capture uses High(NativeUInt) for both endpoints
Match clears its output array before each attempt; Replace clears its output before beginning, and successful replacement with no selected occurrence returns the original text with xrsOk
Replacement references use PCRE2's dollar notation, such as $1 and ${name}; an unset participating capture contributes an empty string, while an invalid replacement reference reports xrsInvalidReplacement
Call Compile successfully before matching or replacing; a call without a prepared pattern returns False and does not manufacture a pattern error status
TXLSRegexBudget = function(AWork, ABytes: Int64): Boolean of object receives a work increment to accumulate and a current byte estimate to compare with the caller's limit; ABytes is not an allocation delta
Checks occur during pattern preparation, backend allocations, matching callouts, result offset allocation and substitution; the caller supplies cancellation and quota policy rather than relying on a process-wide mutable budget
Returning False or raising an exception from the callback aborts the operation with xrsAborted; callback exceptions do not escape through the native backend
xrsResourceLimit, xrsAborted and xrsUnavailable are terminal for that instance, so create another instance before retrying after those conditions; invalid pattern or text errors do not impose that terminal latch
TXLSRegexStatus value | Meaning |
|---|---|
xrsOk | The backend operation completed successfully |
xrsNoMatch | The current match search found no match |
xrsInvalidPattern | The pattern could not be compiled, including invalid pattern encoding |
xrsInvalidReplacement | The replacement expression was rejected or a backend error fell outside the explicit status mappings |
xrsInvalidText | Matching or substitution encountered an explicitly classified UTF-16 input or character-boundary error |
xrsResourceLimit | A backend allocation, internal matching limit or byte-accounting limit prevented completion |
xrsAborted | The budget callback stopped the operation, its callback raised an exception, or a native callout aborted matching |
xrsUnavailable | The target has no supported bundled static backend |
The calculator maps these backend statuses into its own formula errors and evaluation diagnostics; these direct backend APIs do not return Excel error variants