lxRegex は、計算機の正規表現関数が使うステートフル バックエンド TXLSRegex を公開します。通常のワークブック呼び出し側は、コンテキスト依存の数式評価 で説明する数式 API を使えます
バックエンドは、バンドルされた PCRE2 10.49 の 16 ビット ビルドを UTF モード、自動予算 callout、JIT なしで使用します。Delphi と C++Builder の Windows ターゲット、対応する FPC Linux x64 と macOS ARM64 ターゲットには静的オブジェクトが付属します。未対応のバックエンド ターゲットは xrsUnavailable を報告します
各インスタンスはコンパイル済みパターン、アロケータ、マッチ コンテキストを所有します。同時実行する操作ごとに別インスタンスを作成し、予算コールバックのオーナーはインスタンス解放まで生存させてください
| 公開宣言 | 契約 |
|---|---|
TXLSRegex.Create(ABudget: TXLSRegexBudget) | バックエンド コンテキストを割り当て、省略可能なコールバックを保持します。呼び出し側予算なしでは nil を渡し、その後は操作結果と Status を確認してください |
TXLSRegex.Destroy | コンパイル済みパターン、マッチ データ、コンテキストを解放します。呼び出し側は通常 finally ブロックで Free を呼びます |
TXLSRegex.Compile(Pattern, IgnoreCase): Boolean | UTF-16 パターンをコンパイルし、キャプチャ ストレージを準備します。以前のパターンは置き換わります。IgnoreCase で PCRE2 の大文字小文字を無視するマッチが有効になり、False では大文字小文字を区別するマッチのままです |
TXLSRegex.Match(Text, Offset, NonemptyAtStart, out Offsets): Boolean | コンパイルの成功が必要で、ゼロ始まりの UTF-16 オフセットから検索し、切り離されたキャプチャ オフセットを返します。NonemptyAtStart=True は、その正確なオフセットでのアンカー付き空でないマッチを要求します。空のマッチを越えて進む処理に使えます |
TXLSRegex.Replace(Text, Replacement, Occurrence, out Value): Boolean | コンパイルの成功が必要で、番号付き・名前付きキャプチャ参照を含む PCRE2 置換構文を使います。ゼロはすべてのマッチを選択し、正の値は先頭から 1 始まりで出現を選び、負の値は末尾から数えます |
TXLSRegex.Check(AWork, AExtraBytes): Boolean | 現在の作業増分と、常駐バックエンド バイト数に AdditionalBytes と提案された追加バイトを足した値で、予算コールバックを呼び出します。負のバイト計上、整数オーバーフロー、ラッチされた終端ステータスは False を返します |
TXLSRegex.Status: TXLSRegexStatus | 最新の操作や終端的な予算・バックエンド状態に対する読み取り専用ステータスです。操作が False を返した後に使い、マッチなしと失敗を区別してください |
TXLSRegex.CaptureCount: Cardinal | 最後にコンパイルされたパターンが報告する明示的キャプチャ グループ数です。マッチ全体のスロットは除きます。Compile の成功後に使ってください |
TXLSRegex.AdditionalBytes: Int64 | すべての予算チェックに参加すべき呼び出し側所有の一時バッファの、読み書き可能な計上値です。デフォルトはゼロで、自分でメモリを割り当てることはありません |
TXLSRegexOffsets はスロットごとに 2 要素を持つ NativeUInt の動的配列です。スロット 0 にマッチ全体が入り、その後に宣言順で明示的キャプチャ グループが続きます
各ペアは、Delphi の 1 始まり文字列インデックスや Unicode スカラー位置ではなく、UTF-16 コード単位で測ったゼロ始まりの開始位置と排他的終了位置です。未設定の省略可能キャプチャは、両端点に High(NativeUInt) を使います
Match は各試行の前に出力配列をクリアし、Replace は開始前に出力をクリアします。選択された出現がない成功置換は、元のテキストを xrsOk で返します
置換参照は $1 や ${name} のような PCRE2 のドル表記を使います。参加していない未設定キャプチャは空文字列になり、無効な置換参照は xrsInvalidReplacement を報告します
マッチや置換の前に Compile を成功させてください。準備済みパターンのない呼び出しは False を返し、パターン エラー ステータスを作り出しません
TXLSRegexBudget = function(AWork, ABytes: Int64): Boolean of object は、累積すべき作業増分と、呼び出し側上限と比較する現在のバイト見積もりを受け取ります。ABytes は割り当て差分ではありません
チェックは、パターン準備、バックエンド割り当て、マッチ callout、結果オフセット割り当て、置換の間に行われます。プロセス全体の可変予算に頼るのではなく、キャンセルとクォータのポリシーは呼び出し側が供給します
コールバックから False を返したり例外を発生させたりすると、操作は xrsAborted で中止します。コールバックの例外がネイティブ バックエンドを抜けることはありません
xrsResourceLimit、xrsAborted、xrsUnavailable はそのインスタンスにとって終端状態です。これらの条件の後で再試行するには、別のインスタンスを作成してください。無効なパターンやテキストのエラーは、その終端ラッチを課しません
TXLSRegexStatus の値 | 意味 |
|---|---|
xrsOk | バックエンド操作が正常に完了しました |
xrsNoMatch | 現在のマッチ検索はマッチを見つけられませんでした |
xrsInvalidPattern | パターンをコンパイルできませんでした。無効なパターン エンコーディングも含みます |
xrsInvalidReplacement | 置換式が拒否されたか、バックエンド エラーが明示的なステータス マッピングの外でした |
xrsInvalidText | マッチや置換が、明示的に分類された UTF-16 入力や文字境界のエラーに遭遇しました |
xrsResourceLimit | バックエンド割り当て、内部マッチ上限、バイト計上上限が完了を妨げました |
xrsAborted | 予算コールバックが操作を停止したか、コールバックが例外を発生させたか、ネイティブ callout がマッチを中断しました |
xrsUnavailable | ターゲットに対応するバンドル静的バックエンドがありません |
計算機はこれらのバックエンド ステータスを、自身の数式エラーと評価診断へマッピングします。これらの直接バックエンド API は Excel エラー Variant を返しません