技術記事

FormCalc の Round・Mod・Null は Delphi と違う

請求書フォームは手数料を Round(Subtotal * 0.025, 2) で計算し、合計を再確認する Delphi サービスは、半端のある行でフラット化済み PDF と食い違います。FormCalc は半分を 0 から遠い方向へ丸めて Double を返しますが、System.Round は偶数への丸めをするので、頼れる確認方法は、HotPDF に XFA フォームをフラット化させて FormCalc スクリプトを走らせることです

0 から遠い方へ丸め、結果は Double のまま

Delphi の System.Round は FPU の丸めモードに従い、既定のモードは偶数への丸めです。Round(2.5) は 2、Round(3.5) は 4、Round(-2.5) は -2 です。銀行丸めは統計には向いています。ずっと 3 と表示してきたフォームには悪い組み合わせです。FormCalc の Round は半分を 0 から遠い方へ取るので、2.5 は 3 に、-2.5 は -3 になります。戻り値の型も違います。System.Round は Int64 を返すので、おなじみの Round(X * 100) / 100 の定石は、X * 100 が Int64 の範囲を外れた途端に溢れます。FormCalc の Round(X, 2) は Double を受け取り Double を返します

HotPDF による Delphi XFA フォームの丸めマトリクス。FormCalc の Round は 2.5 を 0 から遠い 3 に、System.Round は 2 を返す
FormCalc はちょうど半分を 0 から遠い方へ取って Double を返すので、System.Round が 2 を返す場面で 2.5 は 3 になります

大きい値にはもう 1 つの規則が要ります。Double には明示的な仮数ビットが 52 個あるので、大きさが 252(4,503,599,627,370,496)以上になると丸める端数が残っていません。HotPDF は絶対値を 10places でスケールし、スケール後の値が 252 に届くと入力をそのまま返します。それ以上掛けても桁を作り出したり溢れたりするだけだからです。2 進格納がもう 1 つの限界を設け、こちらは FormCalc を含むあらゆる Double ベースの評価器に当たります。リテラルの 2.675 は 2.67499999999999982236431605997495353221893310546875 として格納されます。2 桁に丸めると 2.67 です。FormCalc に 10 進で正確な金銭型はないので、フォームと移植版が一致できるのは、両者が抱える 2 進の値についてだけです

uses
  Math;

// Delphi 移植用の FormCalc 流 Round: 半分は 0 から遠い方へ、
// 桁数は 0 へ向かって切り捨てて 0..12 に収め、結果は Double のまま
function FormCalcRound(Value: Double; Places: Double = 0): Double;
const
  NoFractionBits = 4503599627370496.0;   // 2^52
var
  Digits: Integer;
  Scale, Scaled, Whole: Double;
begin
  if IsNan(Value) or IsNan(Places) then
    Exit(NaN);
  if IsInfinite(Value) or (Value = 0) then
    Exit(Value);
  Digits := Trunc(EnsureRange(Places, 0.0, 12.0));
  Scale := IntPower(10, Digits);
  if Abs(Value) >= NoFractionBits / Scale then
    Exit(Value);                         // 丸める端数の桁はもう残っていない
  Scaled := Abs(Value) * Scale;
  Whole := Int(Scaled);
  if Scaled - Whole >= 0.5 then
    Whole := Whole + 1;
  Result := Whole / Scale;
  if Value < 0 then
    Result := -Result;
end;

// FormCalcRound(2.5)            = 3        System.Round(2.5)  = 2
// FormCalcRound(-2.5)           = -3       System.Round(-2.5) = -2
// FormCalcRound(1234.567, 2.7)  = 1234.57  (桁数 2.7 は 2 として扱う)
// FormCalcRound(1234.5, -2)     = 1235     (負の桁数は 0 桁を意味する)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) は Int64 を溢れる)

FormCalc の Round が受け取る小数桁数はいくつか

0 から 12 までの整数桁です。HotPDF は第 2 引数を 0 へ向かって切り捨ててからその範囲に収めるので、Round(X, 2.7) は 2 桁、Round(X, 15) は 12 桁に丸め、Round(X, -2) と Round(X, -0.5) はどちらも整数に丸めます。HotPDF が FormCalc を評価する場所ならどこでも規則は同じなので、フラット化の間に計算された合計と、フォームの記入途中に計算された合計は一致して出てきます。表計算の癖は逆方向に引っ張ります。Excel の ROUND(1234.5, -2) は 1200 になります。Excel は負の桁数を小数点より左の桁と読むからです。FormCalc は 1235 を返します。Delphi のヘルパーはこの規約をもう 1 度ひっくり返します。Math.RoundTo と SimpleRoundTo は 10 の冪を取るので、RoundTo(X, -2) は小数 2 桁を意味し、RoundTo(1234.567, 2) は 1200 です。スクリプトの第 2 引数をそのまま RoundTo に渡す移植版は、フォームがセントを表示する場面で百の位を印字します。桁数は FormCalc の定義のまま保持し、FormCalcRound のようなヘルパーへ通しましょう。タイの規則もこれが正しく保ちます

なぜ a - b * Int(a / b) は間違った剰余を返すのか

商が被除数よりずっと早く厳密さを失うからです。Mod(1E20, 7) を見てください。被除数は誤差なく表現できます。1020 は 220 × 520 で、520 は 53 ビットに収まります。真の剰余は 2 です。商の約 1.43 × 1019 はそうではありません。この範囲の Double は 2,048 刻みで並んでいるので、乗算が始まる前に Int(a / b) はすでに間違っており、a - b * q は丸め誤差の取り残しをそのまま返します。Delphi の mod 演算子は整数専用で、Trunc は Int64 の範囲を超える商を保持できません。ここに頼る前に System.Math.FMod を確認してください。商から剰余を導く実装は同じ誤差を受け継ぎます。FMod(1E20, 7) を期待値 2 と比べれば、1 行で決着します

2 進の筆算除法は商を作りません。除数を被除数の半分を超えるまで 2 倍し続け、それから降りてきて、スケールした除数が収まる場所ですべて引いていきます。スケールした除数はどれも元の数 × 2 の冪なので、丸め誤差を運びません。どの引き算も現在の剰余の半分から全部を取り去ります。Sterbenz の補題により、IEEE 754 の減算では丸めが起こらないケースです。結果は厳密です。FormCalc の符号規則がその後に適用されます。剰余は被除数の符号を取るので、Mod(-7, 3) は -1、Mod(7, -3) は 1 です。大きさが除数より小さい被除数はそのまま返り、ゼロの除数は何の数も返しません

HotPDF による Delphi での FormCalc Mod。商の公式は 1E20 で破綻し、2 進の筆算除法は除数を倍増させて厳密に引いていく
1.43E19 付近の商はすでに粗い Double の格子に載っている一方、2 進の筆算除法は商を作らずに厳密な剰余へ届きます
// 厳密な浮動小数点剰余、被除数の符号を引き継ぐ、商は不要
function FormCalcMod(Dividend, Divisor: Double): Double;
var
  Step, Half: Double;
begin
  if IsNan(Dividend) or IsNan(Divisor) or IsInfinite(Dividend) or (Divisor = 0) then
    Exit(NaN);
  if IsInfinite(Divisor) or (Abs(Dividend) < Abs(Divisor)) then
    Exit(Dividend);
  Divisor := Abs(Divisor);
  Result := Abs(Dividend);
  Half := Result * 0.5;
  Step := Divisor;
  while Step <= Half do
    Step := Step * 2;                   // 2 の冪倍数のうち最大のもの
  while Step > Divisor do
  begin
    if Result >= Step then
      Result := Result - Step;          // 厳密: Step <= Result < 2 * Step
    Step := Step * 0.5;
  end;
  if Result >= Divisor then
    Result := Result - Divisor;
  if Dividend < 0 then
    Result := -Result;
end;

// FormCalcMod(1E20, 7) = 2      FormCalcMod(-7, 3) = -1
// FormCalcMod(7, -3)   = 1      FormCalcMod(7.5, 2) = 1.5
// FormCalcMod(1, 0)    = NaN

Choose はインデックスを切り捨て、HasValue は空白を無視する

Choose(n, item1, item2, …) は第 1 引数を数値に変換して切り捨てるので、Choose(2.7, "a", "b", "c") は "b" を返し、型エラーは上げません。1 未満か最後の項目を超えるインデックスは空文字列を返し、null のインデックスは null を返します。HasValue は省略可能なフィールドをテストするために作者が使う関数形式です。null と、Unicode の空白だけからなるテキストに対して 0 を返します。数値の 0 は依然としてカウントされます。0 が入った数量フィールドは記入済みです。スペース 3 つだけが入ったコメント欄は未記入のままです。保存を経ても空白を保持するのは XFA の空白テキスト値の扱いですが、それでも未記入扱いです。この 2 関数を合わせれば、省略可能な明細行のおなじみのガード、if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif になります。未記入の行は空のまま、列の合計は入力された分に限定されます。空の数量を 0 として扱う Delphi 移植版は、フォームが何も印字しない場所に 0.00 の行合計を印字します

空のフィールドに対して FormCalc は何を返すのか

null です。そして null は、calculate スクリプトが呼ぶほとんどの関数を生き延びます。FormCalc では空文字列は実在の値で、null はその不在です。文字列関数はこの 2 つを区別し続けます:

  • Len、Upper、Lower、Ltrim、Rtrim、Trim、Space は引数が null なら null を返します
  • Left、Right、At、Replace は最初の 2 引数を、Stuff は最初の 3 引数を、Substr は与えられたすべての引数を確認します
  • どれに渡しても空文字列はテキストとして処理されます。Upper("") は "" であって null ではありません
  • スクリプトは null リテラルや Null() で明示的に null を作れます

Delphi の文字列に null はなく、手書きの移植版が最も流されるのがここです。Concat はリストの外にいます。null の引数を飛ばすので、未記入のプレフィックスに対する Concat(Prefix, Code) は、移植版が '' から組み立てるのと同じテキストになります。Len は違います。Len(Prefix) は null で、それに束縛された数値フィールドは空欄のままです。Length('') はそこに 0 を置きます。集約関数はスキップ規則に従います。Sum、Avg、Count、Min、Max は空のエントリを無視するので、10、空の行、20 に対する Avg は 15 で、Count は 2 です。空の行を 0 と読む移植版は平均 10 を報告します。何も入力されていない列は Sum に値をまったく渡さないので、総合計フィールドは空欄のままです

HotPDF による Delphi の FormCalc null 伝播マップ。文字列関数は null を返し、集約は空エントリをスキップし、HasValue は空白テキストを未記入とみなす
null は Len と集約を通っても運ばれ続ける一方、Concat と Sum はそれを飛ばすので、移植版は null を空文字列へ潰さず、フィールドを Variant でモデル化する必要があります
uses
  Variants;

// FormCalc 流 Avg: 空のエントリはスキップされ、0 とは数えない
function FormCalcAvg(const Values: array of Variant): Variant;
var
  I, Count: Integer;
  Total: Double;
begin
  Result := Null;
  Total := 0;
  Count := 0;
  for I := Low(Values) to High(Values) do
    if not VarIsNull(Values[I]) then
    begin
      Total := Total + Values[I];
      Inc(Count);
    end;
  if Count > 0 then
    Result := Total / Count;
end;

// FormCalcAvg([10, Null, 20]) = 15     空のエントリを 0 と読むと 10 になる
// FormCalcAvg([Null, Null])   = Null   平均フィールドは空欄のまま

移植版ではフィールドを Variant でモデル化し、Null を '' と切り離して保持しましょう。データセットから引き出した値にも同じ配慮が要ります。TField.Value は NULL 列に Null を返しますが、TField.AsString はそれを空文字列に変え、移植版が目にする前に違いを消します

フォーム自身にスクリプトを走らせる

最も安全な移植は、移植しないことです。THotPDF.FlattenLoadedXFA はフォームをレイアウトしながら各フィールドの calculate スクリプトを評価し、フィールドを AcroForm フィールドとして再構築します。上記の丸め、剰余、null の規則を適用してです。同じ 1 呼び出しが、レイアウトからウィジェットマッピングまで、XFA から AcroForm へのフラット化の残りをすべて処理します。評価できない式——未解決の参照、ゼロ除算、パースエラー——は全体として失敗します。半分だけ計算された値がフィールドへ届くことはありません。フラット化済みファイルを再読み込みし、フィールド値を移植版の出力と比較すれば、漠然とした食い違いはフィールド名のリストになります:

uses
  SysUtils, Classes, HPDFDoc;

function SameFieldValue(const FormText, PortText: string): Boolean;
var
  FS: TFormatSettings;
  A, B: Double;
begin
  FS := TFormatSettings.Create;
  FS.DecimalSeparator := '.';
  if TryStrToFloat(FormText, A, FS) and TryStrToFloat(PortText, B, FS) then
    Result := A = B
  else
    Result := FormText = PortText;      // '' 対 '0.00' は本物の不一致
end;

procedure CheckPortAgainstForm(const XfaFile, FlatFile: string; Port: TStrings);
var
  Pdf: THotPDF;
  Pairs: TStringList;
  I: Integer;
  FieldName: string;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile(XfaFile) <= 0 then
      raise Exception.Create('Cannot open the XFA form');
    Pdf.FlattenLoadedXFA(False);        // False = フィールドは読み取り専用になる
    for I := 0 to Pdf.XFAFlattenWarnings.Count - 1 do
      Writeln('XFA: ', Pdf.XFAFlattenWarnings[I]);
    Pdf.SaveLoadedDocument(FlatFile);
  finally
    Pdf.Free;
  end;

  Pdf := THotPDF.Create(nil);
  Pairs := TStringList.Create;
  try
    if Pdf.LoadFromFile(FlatFile) <= 0 then
      raise Exception.Create('Cannot open the flattened PDF');
    Pdf.GetLoadedFormFieldNameValuePairs(Pairs);
    for I := 0 to Pairs.Count - 1 do
    begin
      FieldName := Pairs.Names[I];
      if (Port.IndexOfName(FieldName) >= 0) and
         not SameFieldValue(Pairs.ValueFromIndex[I], Port.Values[FieldName]) then
        Writeln(Format('%s: form "%s", port "%s"',
          [FieldName, Pairs.ValueFromIndex[I], Port.Values[FieldName]]));
    end;
  finally
    Pairs.Free;
    Pdf.Free;
  end;
end;

合計を信用する前に警告を読みましょう。リストは変換がマッピングできなかったすべての要素を名指すので、calculate フィールドを名指すエントリを探してください。次に、上記の規則のために作ったサンプルを移植版に与えます。2 位の小数が .5 に着地する金額、Mod を通す 20 桁の口座番号、端数の桁数を伴う Round、空のままの省略可能な明細 1 行。この手続きが印字するすべての行は、移植版が間違えている規則です。AcroForm の format と calculate スクリプトで計算するフォームは JavaScript の数値規則に従います。そこでは Math.round(-2.5) が -2 で、同じ問いへの 3 つ目の答えです

サービスが必要な数値がフォームがすでに印字しているものなら、フォームから取りましょう。HotPDF Delphi PDF component でフラット化し、結果を再読み込みしてフィールドを読みます。上のヘルパー関数が報われるのは、フォームが決して計算しない数値の場合だけです