技術文章

FormCalc 的 Round、Mod、Null 有別於 Delphi

發票表單用 Round(Subtotal * 0.025, 2) 算附加費,Delphi 服務重新核對合計時,在落在半分錢上的行與扁平化後的 PDF 對不上。FormCalc 對 .5 以遠離零的方向捨入並回傳 Double,System.Round 則取偶,所以靠得住的核對方式是讓 HotPDF 扁平化 XFA 表單、執行它自己的 FormCalc 指令碼

.5 遠離零捨入,結果仍是 Double

Delphi 的 System.Round 跟著 FPU 捨入模式走,預設模式對 .5 取偶:Round(2.5) 得 2、Round(3.5) 得 4、Round(-2.5) 得 -2。銀行家捨入適合統計,套在一個一直顯示 3 的表單上就不對勁。FormCalc 的 Round 把 .5 推向遠離零,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 以遠離零的方向變 3,System.Round 則給 2
FormCalc 對 .5 平手值以遠離零方向捨入並回傳 Double,所以 2.5 變 3,而 System.Round 答案是 2

大數值還需要一條規則。Double 只有 52 個明示的小數位元,量級達到 252(4,503,599,627,370,496)以上就沒有小數部分可捨入。HotPDF 把絕對值乘上 10places,縮放後的值一旦到達 252,就把輸入原樣退回——再乘下去只會編造位數或溢位。二進位儲存設下另一道限制,這道限制對任何以 Double 為基礎的求值器都適用,FormCalc 也一樣。字面值 2.675 實際存成 2.67499999999999982236431605997495353221893310546875,取兩位得 2.67。FormCalc 沒有十進位精確的金錢型別,表單與移植版能對上的只有雙方都持有的那個二進位值

uses
  Math;

// 給 Delphi 移植版的 FormCalc 風格 Round:.5 遠離零,
// 位數向零截斷並限制在 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 把第二個引數向零截斷,再壓進這個範圍:Round(X, 2.7) 取兩位、Round(X, 15) 取十二位,Round(X, -2) 和 Round(X, -0.5) 都取到整數。HotPDF 在哪裡求值 FormCalc,規則都一樣,所以扁平化期間算出的合計與填表期間算出的完全相同。試算表的習慣卻反著來:Excel 的 ROUND(1234.5, -2) 得 1200,因為 Excel 把負位數讀成小數點左邊的位數;FormCalc 給 1235。Delphi 的輔助函式又把慣例翻了一次:Math.RoundTo 與 SimpleRoundTo 收的是十的冪次,RoundTo(X, -2) 意思是兩位小數,RoundTo(1234.567, 2) 則是 1200。把指令碼的第二個引數原封丟進 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,一行就見分曉

二進位長除法從不形成商。先把除數倍增到越過被除數的一半,再往回走,縮放後的除數放得下就減。每個縮放除數都是原除數乘二的冪次,不帶任何捨入誤差;每次減法減掉的介於目前餘數的一半到全部之間——按 Sterbenz 引理,IEEE 754 減法在這種情況不涉及捨入。結果是精確的。接著套 FormCalc 的正負號規則:餘數跟被除數同號,Mod(-7, 3) 是 -1、Mod(7, -3) 是 1。量級小於除數的被除數原樣退回,除數為零則什麼數字都不給

以 HotPDF 在 Delphi 中實現 FormCalc 的 Mod:商公式在 1E20 失靈,二進位長除法靠倍增除數與精確減法得出餘數
1.43E19 附近的商早已落在粗糙的 Double 網格上,二進位長除法則不形成商就直接得到精確餘數
// 精確浮點餘數,帶被除數正負號,不需形成商
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;                   // 二的冪次倍數中最大的
  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, …) 把第一個引數轉成數字並截斷,所以 Choose(2.7, "a", "b", "c") 回傳 "b",不丟型別錯誤。索引小於 1 或超出最後一項回傳空字串,索引為 null 則回傳 null。HasValue 是作者拿來測試選填欄位的函式形式:對 null 與只由 Unicode 空白組成的文字回傳 0。數字 0 算數:數量欄位放著 0 就是已填;備註框放三個空格就是沒填,即使XFA 空白文字值會在存檔時把那些空格原樣保住。兩個函式湊成選填明細列的標準防護 if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif:沒填的行留空,欄位合計只計實際輸入的值。把空數量當 0 的 Delphi 移植版,會在表單什麼都不印的地方印出 0.00 行合計

空欄位在 FormCalc 回傳什麼?

Null——而且 null 能穿透計算指令碼呼叫的大多數函式活下來。FormCalc 裡空字串是一個真實的值,null 是它的缺席,字串函式把兩者分得清清楚楚:

  • Len、Upper、Lower、Ltrim、Rtrim、Trim 與 Space 在引數為 null 時回傳 null
  • Left、Right、At 與 Replace 檢查前兩個引數,Stuff 檢查前三個,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 則跳過它,所以移植版該把欄位建成 Variant,而不是把 null 塌縮成空字串
uses
  Variants;

// FormCalc 風格 Avg:空項目被跳過,不當成零計數
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 規則。同一個呼叫也處理XFA 轉 AcroForm 扁平化的其餘部分,從版面到 widget 對應。算不出來的公式——未解析的參照、除以零、語法錯誤——整體失敗,算到一半的東西不會進到欄位。重新載入扁平化後的檔案、把欄位值與移植版輸出對照,曖昧的對不上就變成一串欄位名清單:

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;

相信任何合計之前先讀警告清單;它點名每個轉換對不上號的元素,留意提到計算欄位的條目。接著替移植版準備一份為上述規則量身打造的樣本:落在第二位小數 .5 上的行金額、跑過 Mod 的 20 位帳號、帶小數位數的 Round,還有一行留空的選填明細。程序印出的每一行都是移植版搞錯的一條規則。用AcroForm 格式與計算指令碼算東西的表單遵循 JavaScript 數字規則——那邊 Math.round(-2.5) 是 -2,同一個問題的第三種答案

如果您的服務要的數字表單本來就會印,直接跟表單拿:用 HotPDF Delphi PDF 元件扁平化、重新載入結果、讀欄位。上面的輔助函式只在表單從不計算的數字上才派得上用場