技术文章

FormCalc 与 Delphi 的 Round、Mod、Null 语义差异

一张发票表单用 Round(Subtotal * 0.025, 2) 计算附加费,Delphi 服务复核合计时,在半分钱的行上与扁平化后的 PDF 对不上。FormCalc 把 .5 远离零舍入并返回 Double,System.Round 则舍到偶数,靠得住的做法是让 HotPDF 扁平化 XFA 表单并运行它的 FormCalc 脚本

远离零舍入,结果仍是 Double

Delphi 的 System.Round 跟随 FPU 舍入模式,默认模式舍到偶数: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

Delphi 中配合 HotPDF 处理 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 收的是 10 的幂,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。量级小于除数的被除数原样返回,除数为零则什么都不出

Delphi 中配合 HotPDF 的 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 能穿过 calculate 脚本调用的大多数函数存活。在 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 拿不到任何值,总计字段于是保持为空

Delphi 中配合 HotPDF 的 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 扁平化的其余部分,从布局到控件映射。求不了值的公式——未解析的引用、除零、解析错误——整体失败,半吊子的计算结果碰不到字段。重新加载扁平化后的文件,把字段值与移植版的输出对比,模糊的不一致就变成一份字段名清单:

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;

相信任何合计之前先读警告;清单会点名每个转换未能映射的元素,留意那些指名 calculated 字段的条目。然后给移植版喂一份按上述规则构造的样本:第二位小数落在 .5 上的行金额、过一遍 Mod 的 20 位账号、带小数位数的 Round,以及一行留空的可选项。这个过程打印出的每一行,都是移植版弄错的一条规则。用 AcroForm 格式与 calculate 脚本计算的表单遵循 JavaScript 数字规则——Math.round(-2.5) 在那里是 -2,同一个问题的第三个答案

如果你的服务需要的数字表单本来就打印出来了,直接从表单拿:用 HotPDF Delphi PDF component 扁平化,重新加载结果并读字段。上面的辅助函数只在表单从不计算的数字上才物有所值