lxRegex exposes TXLSRegex, the stateful backend behind the calculator's regular expression functions; ordinary workbook callers can use the formula APIs set out 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 the 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 every simultaneous operation and keep the budget callback's owner alive until the instance is freed
| Public declaration | Contract |
|---|---|
TXLSRegex.Create(ABudget: TXLSRegexBudget) | Allocates the backend contexts and retains the optional callback; pass nil for no caller budget, then inspect the operation results and Status |
TXLSRegex.Destroy | Releases the compiled pattern, match data and contexts; callers would normally invoke Free in a finally block |
TXLSRegex.Compile(Pattern, IgnoreCase): Boolean | Compiles a UTF-16 pattern and prepares its capture storage, replacing any earlier pattern; IgnoreCase switches on 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 hands back detached capture offsets; NonemptyAtStart=True asks for 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 applies PCRE2 replacement syntax, numbered and named capture references included; zero selects every match, 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 together with the resident backend bytes plus AdditionalBytes and the proposed extra bytes; negative byte accounting, integer overflow or a latched terminal status yields False |
TXLSRegex.Status: TXLSRegexStatus | Read-only status for the latest operation or a terminal budget/backend condition; consult it after an operation returns False to tell a missing match from failure |
TXLSRegex.CaptureCount: Cardinal | Read-only count of explicit capture groups reported by the most recently compiled pattern, whole-match slot excluded; consult it after Compile succeeds |
TXLSRegex.AdditionalBytes: Int64 | Read/write accounting for caller-owned temporary buffers that should take part in every budget check; it defaults to zero and allocates no memory itself |
TXLSRegexOffsets is a dynamic array of NativeUInt carrying two elements per slot; slot zero holds the whole match, followed by the explicit capture groups in declaration order
Every pair is a zero-based start and exclusive end measured in UTF-16 code units, not Delphi's one-based string indices nor 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 starting, and a successful replacement with no selected occurrence gives back 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, whilst an invalid replacement reference reports xrsInvalidReplacement
Call Compile successfully before matching or replacing; a call made without a prepared pattern returns False and manufactures no pattern error status
TXLSRegexBudget = function(AWork, ABytes: Int64): Boolean of object receives a work increment to accumulate and a current byte estimate to compare against 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 the 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 a fresh instance before retrying after those conditions; invalid pattern or text errors impose no such 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 refused, or a backend error fell outside the explicit status mappings |
xrsInvalidText | Matching or substitution ran into an explicitly classified UTF-16 input or character-boundary error |
xrsResourceLimit | A backend allocation, an internal matching limit or a byte-accounting limit prevented completion |
xrsAborted | The budget callback stopped the operation, the 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 onto its own formula errors and evaluation diagnostics; these direct backend APIs return no Excel error variants