コンテキスト依存の数式評価

クラシック XLS と XLSX のワークシートは、1 始まりで選択した行と列に入力されたものとして数式テキストを評価する、同じ読み取り専用 API を公開します

1 回限りの評価

function EvaluateFormulaAt(Row, Col: Integer;
  const Formula: WideString): TXLSFormulaEvaluationResult; overload;

function EvaluateFormulaAt(Row, Col: Integer;
  const Formula: WideString;
  ReferenceStyle: TXLSFormulaReferenceStyle;
  const Options: TXLSFormulaEvaluationOptions): TXLSFormulaEvaluationResult; overload;

ワークシートは、ローカル名、修飾されない参照、テーブル、および外部リンクのコンテキストを提供します。アクティブシート、選択範囲、セルモデル、数式キャッシュ、ダーティ状態、依存関係グラフは変更されません

xlfrsA1 は絶対参照と混合参照を保持しながら、相対参照をターゲットセルから解決します。 xlfrsR1C1 は相対オフセットをそのターゲットから直接解決します

型付きの結果

TXLSFormulaEvaluationResult は、 Status、元の型付きの Value、 IsVolatile、およびステータス、ネイティブコード、メッセージを含む安定した Issue レコードを返します

TXLSFormulaEvaluationStatus = (xlfeOk, xlfeInvalidArgument,
  xlfeWorksheetUnavailable, xlfeParseError, xlfeUnsupportedFunction,
  xlfeCircularReference, xlfeExternalReferenceDenied, xlfeCancelled,
  xlfeResourceLimit, xlfeFailed, xlfeUnsafeFunctionDenied);

TXLSFormulaEvaluationIssue = record
  Status: TXLSFormulaEvaluationStatus;
  NativeCode: Integer;
  Message: WideString;
end;

Formula values such as #DIV/0!、 #REF!などの数式値、空の文字列、配列、ブール値、日付は、区別可能な値のまま保たれます。解析失敗、サポートされない関数、循環参照、拒否された外部参照、拒否された安全でないコールバック、キャンセル、無効な引数、利用できないワークシート、リソースの枯渇には、明示的な API ステータスが使用されます Issue.NativeCode には基盤のエンジンエラーコードが格納され、 Issue.Message the human-readable description when Status is not xlfeOk

再利用可能な不変テンプレート

function CreateFormulaEvaluationTemplate(Row, Col: Integer;
  const Formula: WideString;
  ReferenceStyle: TXLSFormulaReferenceStyle): IXLSFormulaEvaluationTemplate;

テンプレートはアンカーで数式を一度コンパイルし、異なるターゲットセルで繰り返し評価するための EvaluateAt と EvaluateAtWithOptions を公開します

通常の A1 および R1C1 数式はコンパイル済みツリーをそのまま再利用します。意味がターゲットのテーブル行に依存する A1 構造化参照は、そのターゲットコンテキスト向けに解決され、コンパイルされます

テンプレートは書き込み可能なワークシート状態を保持せず、ワークブック破棄後は安全に xlfeWorksheetUnavailable を報告し、ワークブックの変更によって元のコンパイル済みコンテキストが古くなった場合は、コンテキストを考慮した再コンパイルにフォールバックします

リソース、外部参照、およびコールバックのオプション

AllowExternalReferences	既定は true ですが、明示的に登録されたワークスペースターゲットまたはファイルローカルのキャッシュのみを許可し、暗黙的なファイルアクセスやネットワークアクセスは一切行いません
AllowUnsafeFormulaCallbacks	既定は false で、引数が 1 つも評価される前に、危険な関数名がユーザー関数レジストリやコールバックに到達するのを阻止します。拒否された場合は `xlfeUnsafeFunctionDenied`
CancelFlag	評価の前後でチェックされるオプションのブール値ポインターです
MaxFormulaLength	既定は 8192 UTF-16 コード単位です
MaxEvaluationSteps	既定は 1,000,000 構文項目の評価です
MaxRecursionDepth	既定は 256 段階の入れ子になった数式評価です
MaxArrayBytes	生成される配列ペイロードの既定は 64 MiB です

ゼロまたは負の最大値は、その呼び出しごとの上限を無効にします。ワークブック全体の配列メモリポリシーは引き続き適用され、有効な上限に達すると、一時的な評価状態を解放した後で xlfeResourceLimit を返します

明示的なオプションを受け取るオーバーロードは、その呼び出しに対して AllowUnsafeFormulaCallbacks を最優先の設定として扱い、既定の 1 回限りの評価とテンプレート評価は同じ名前のワークブックプロパティを継承します

Delphi の例

Template := Sheet.CreateFormulaEvaluationTemplate(2, 2,
  '=R[-1]C[-1]+1', xlfrsR1C1);

Result := Template.EvaluateAt(2, 2);
if Result.Status = xlfeOk then
  UseValue(Result.Value);

Options := XLSDefaultFormulaEvaluationOptions;
Options.MaxEvaluationSteps := 10000;
Result := Template.EvaluateAtWithOptions(20, 4, Options);

C++Builder の例