技术文章

面向逗号小数区域 Delphi 应用的区域无关 PDF 数字

把一台 Windows 测试机切到德语区域设置,跑一个往页面前插缩放平移矩阵的例程,转储内容流。你看到的不是 0.5 0 0 0.25 0.00001 12.75 cm,而是 0,5 0 0 0,25 1E-5 12,75 cm。内容解析器把它读成数字 0,然后一个它不认识的 token ,5,然后更多再也对不上 cm 所期望的六个操作数的数字,页面带着一个你从没要求的变换渲染出来。机器要解析的数字需要固定的点号、无指数、完全不依赖 FormatSettings——写出端如此,读取端也如此

逗号小数区域为什么会弄坏 PDF 数字?

因为 Delphi 的默认浮点格式化跟随桌面,而 PDF 数字语法是固定的。FloatToStr 用 FormatSettings.DecimalSeparator,所以在 de-DE、fr-FR 或 pt-BR 机器上,每个小数都带着逗号出场。ISO 32000-1 §7.3.3 只允许数字里出现数位、一个小数点和前置符号,别的都不行。于是逗号把一个数字拆成一个合法整数加一堆垃圾,结果是一个能渲染、只是渲染错了的页面

第一个陷阱后面还藏着第二个,它在美式机器上也咬人。FloatToStr 用 ffGeneral 格式,数量级一旦低于 1E-4 就切到指数记法,很小的偏移被写成 1E-5。同一个 §7.3.3 声明 PDF 不支持指数形式。从渲染输出反推这两个问题中的任何一个都很折磨人:漂移的矩阵看起来完全像你自己代码里的布局 bug,页面上没有任何东西指向区域设置

PDFlibPas(losLab 的 Delphi PDF Developer Library)经 PLDoubleToStrConst 以六位小数写出 AddPageMatrix 的操作数,代你生成页面内容的调用点也守同一条规则。我们所知最便宜的回归测试,是在进程内把分隔符切成逗号、调 API、然后扫描结果里的逗号和指数:

uses
  System.SysUtils, PDFlibrary;

// 你自己的检查,不属于库。故意写得粗糙:
// 像 (Hello, world) Tj 这样的文本串也含逗号,所以请
// 在一个只画图形的测试页上运行
function HasLocaleDamage(const Content: AnsiString): Boolean;
var
  I: Integer;
begin
  Result := False;
  for I := 1 to Length(Content) do
  begin
    if Content[I] = ',' then
      Exit(True);
    if (Content[I] in ['E', 'e']) and (I > 1) and (I < Length(Content)) and
       (Content[I - 1] in ['0'..'9']) and (Content[I + 1] in ['0'..'9', '-', '+']) then
      Exit(True);
  end;
end;

var
  Lib: TPDFlib;
  OldSeparator: Char;
  Content: AnsiString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetPageDimensions(300, 200);
    Lib.DrawBox(10, 10, 20, 20, 1);
    OldSeparator := FormatSettings.DecimalSeparator;
    try
      FormatSettings.DecimalSeparator := ',';   // 表现得像一台 de-DE 桌面
      Lib.AddPageMatrix(0.5, 0.25, 1E-5, 12.75);
      Content := Lib.GetPageContentToString;
      // 预期:0.5 0 0 0.25 0.00001 12.75 cm
      // FloatToStr 会产出:0,5 0 0 0,25 1E-5 12,75 cm
      Writeln(Content);
      if HasLocaleDamage(Content) then
        Writeln('Locale leaked into the content stream');
    finally
      FormatSettings.DecimalSeparator := OldSeparator;
    end;
  finally
    Lib.Free;
  end;
end;
修复前,PDFlibPas 的 AddPageMatrix 在逗号小数桌面上写出 0,5 0 0 0,25 1E-5 12,75 cm,PDF 解析器把它读成数字 0 加若干未知 token,cm 拿到错误操作数、页面被无声变换,而 PLDoubleToStrConst 写出合法的点号小数
逗号在 PDF 语法里不是数字字符,所以损坏读起来像含义错误的合法 token——而 1E-5 这类 ffGeneral 指数在任何区域下都是非法的,不只逗号区域

在进程内改 FormatSettings.DecimalSeparator 是条捷径。它没锻炼到那些从操作系统自建 TFormatSettings 的代码,如果你的应用就是这么干的,一台带真实德语区域设置的 CI agent 是更诚实的测试

两种数字,两族辅助函数

PDFlibPas 按受众拆分数字辅助函数:给人看的文本可以跟随区域,写给机器的任何东西永远不跟。PDFlibExtra.pas 里的 PLFloatToStr 和 PLStrToFloat 是 FloatToStr 和 StrToFloat 的薄包装,声明上的注释写明它们只用于人类可读的文本。机器输出(PDF、FDF、XFDF、JSON、XML、CSV)走 invariant 家族:写用 PLDoubleToStrConst,读用 PLTryStrToFloatInvariant,需要带点号小数的 TFormatSettings 记录来喂自己的 TryStrToFloat 时用 PLInvariantFormatSettings

精度按用途逐项选择而不是全局一刀切。矩阵六位,坐标和 TJ 调整四位,颜色和 FDF 矩形三位。机器侧覆盖的地方比 API 表面看起来的多:

  • AddPageMatrix、ScalePage 和 DeskewPage,它们都在既有页面内容前面插一个 cm
  • 页面元素生成时写出的 Tm 重置、TJ 前进和 cm 变换
  • 文字转路径时产出的字形摆放矩阵和轮廓点
  • RedactRegion 前插的黑色填充框、FDF 导出里的 /Rect 值,以及重新着色写出的颜色操作数

PLDoubleToStrConst 是手工写的格式化器,我们认为这比用固定的 TFormatSettings 包一层 FloatToStrF 更对。ffFixed 在整数部分超出精度时仍会回落到科学记数法,而且会在 0.5 更短且等值的地方留下 0.500000。这套自定义例程总是写点号、剥尾零、对有限输入从不写指数。它还保留小于请求精度的非零值的有效数字:PLDoubleToStrConst(1E-9, 6) 返回 0.000000001,只有大约低于 5E-16 的值才变成 0。把微小的缩放因子舍成零,会把合法矩阵变成奇异矩阵——这比任何放错位置的小数点都糟

PDFlibPas 把数字格式化一分为二:PLFloatToStr 与 PLStrToFloat 保持绑定区域、服务面向用户的文本,而 PLDoubleToStrConst 与 PLTryStrToFloatInvariant 用点号、无指数、按用途定死六位、四位或三位的精度格式化一切最终成为 PDF 语法的东西
invariant 格式化器是刻意手工写的:剥尾零、从不写指数、保留微小值的有效数字,因为把缩放因子舍成零会让合法矩阵变奇异

给格式化器写单元测试时,挑样本值要想着二进制浮点。“四位有效数字”的显而易见之选是 0.000012345,但这个 double 乘上 1E8 是 1234.4999…,所以结果是 0.00001234,断言因为一个与区域毫无关系的理由失败。取一个明显偏离中点的值,比如 0.000012346,这场争论就完全不会发生:

uses
  PDFlibExtra;

// Assert 调用是你在自己的测试工程里加的检查
procedure CheckNumberHelpers;
var
  V: Double;
begin
  // 机器输出:点号小数、无指数、剥掉尾零
  Assert(PLDoubleToStrConst(1E-5, 6) = '0.00001');
  Assert(PLDoubleToStrConst(-0.5, 6) = '-0.5');
  Assert(PLDoubleToStrConst(0.000012346, 4) = '0.00001235');  // 保留 4 位有效数字
  Assert(PLDoubleToStrConst(12345.25, 4) = '12345.25');

  // 机器输入:返回 False 而不是 EConvertError
  Assert(PLTryStrToFloatInvariant('0.5', V) and (V = 0.5));
  Assert(PLTryStrToFloatInvariant('  12.75 ', V) and (V = 12.75)); // 输入会先裁掉空白
  Assert(not PLTryStrToFloatInvariant('0,5', V));   // 内容数字从不用逗号
end;

为什么解析端比写出端更危险?

解析端更危险,因为绑定区域的解析器不会产出一个略错的数字——它直接抛。StrToFloat 在文本不匹配系统分隔符时抛 EConvertError。建立在它之上的重新着色过程,一碰到逗号小数机器上普通的 0.5 g 操作符就会中止,等于在几乎所有真实页面上都失败。像 "10.5,20.5,50.5,40.5" 这样的裁剪串会被直接拒绝,SVG 长度、SVG 颜色、注释顶点列表和 output intent 值要么被拒、要么被默认值悄悄顶替。这是在开发者机器上通过全部测试、在慕尼黑第一位客户那里就挂掉的代码——与 碰巧能跑的 Delphi 代码一文 里的案例同属一族

库里每一处 StrToFloat 风格的调用都按输入来源分类。内容流操作数、SVG 属性、painter 颜色串、逗号分隔的裁剪与顶点列表都有固定的点号语法,所以它们走 PLTryStrToFloatInvariant。这个辅助函数裁掉空白、用 PLInvariantFormatSettings 解析,空、畸形、NaN 或无穷输入返回 False(值置 0)。逗号分隔的列表毫无争议:逗号不能既是列表分隔符又是小数点,所以也没有需要兼容的历史形态

对 把 PDF 转到单一色彩空间的指南 里讲的重新着色管线,结果是 RecolorPage 和 RecolorDocument 在任何区域上解析页面内容的行为一致。调用者敲进 CheckDocumentPolicy 的规则值是唯一走宽松路线的解析场景,因为那个字符串是人敲的,很可能用的是本地小数点

经字符串中转的数字需要两端说同一种话

一个数字由代码的一部分写进字符串、由另一部分解析回来时,写出端和读取端必须遵守同一约定,只改一头就会弄断往返。带标记的 PDF 结构属性正是这么工作的。SetStructElemBBox 把四个值格式化进一个字符串,经 AddTagAttribute 存起来。写出 /A 属性字典时,这个字符串再被解析一次,以决定它成为数字、数组还是名称

如果两端都跟随系统区域,在德语机器上往返是自洽的。麻烦始于一个照文档传 "0.5" 给 AddTagAttribute 的调用者:绑定区域的读取端解析不了,吐出 PDF 名称 /0.5。PDF/VCR 占位符撞上镜像版的问题,因为它们的 GTS_BBox 用点号生成,保存前一步绑定区域的校验会拒绝它。而只把写出端换成点号更糟,因为每个 SetStructElem* 值都会在逗号小数系统上变成名称

所以写出端用 PLDoubleToStrConst(v, 6),读取端用 PLTryStrToFloatLenient:先试点号形式,再回落系统区域。传 "1,25" 的逗号区域调用者得到数字 1.25。有一个代价,我们是知情接受的:在德语系统上 "1.500" 读作 1.5 而不是一千五,因为点号形式优先。API 把点号记载为分隔符,所以属性串里德语式的千位分组是我们选择放弃的输入。字面的 NAN 和 INF 字符串不再被当作数字

PDFlibPas 的 SetStructElemBBox 及其同族经 AddTagAttribute 以字符串中转数字,/A 写出器再把这些字符串解析回来,所以 v3.539.32 把两端一起搬:PLDoubleToStrConst 用点号写出,PLTryStrToFloatLenient 先读点号再回落区域,逗号区域的 1,25 仍读作 1.25
只修写出端会让每个结构元素属性退化成 PDF 名称,所以往返要么两端一起动,要么别动
uses
  System.SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
begin
  FormatSettings.DecimalSeparator := ',';   // 逗号小数的调用方
  Lib := TPDFlib.Create;
  try
    Lib.BeginTag('Figure', 'Sales chart', '');
    Lib.SetStructElemBBox(10.5, 20.25, 200.5, 100.75); // /BBox [ 10.5 20.25 200.5 100.75 ]
    Lib.AddTagAttribute('Layout', 'SpaceAfter', '0.5');   // /SpaceAfter 0.5 而不是 /0.5
    Lib.AddTagAttribute('Layout', 'StartIndent', '1,25'); // /StartIndent 1.25,经区域回落
    Lib.DrawText(20, 20, 'figure');
    Lib.EndTag;
    Lib.SaveToFile('tagged.pdf');
  finally
    Lib.Free;
  end;
end;

对你自己的代码,我们的建议是给 AddTagAttribute 传点号小数字符串,把逗号回落留给你控制不了的值,比如从旧配置文件加载的字符串。这些属性周围的结构树如何构建,见 带标记 PDF 结构指南

NaN 和无穷大在哪里被拦下

AddPageMatrix、ScalePage 和 RedactRegion 在前门就拒绝 NaN 和无穷参数并返回 0,因为没有哪个 PDF 数字能表示它们。这个检查必须显式。NaN 能溜过 <= 0 测试,所以只对缩放因子做范围检查,会让 NaN 缩放一路走到格式化器,而在 Win32 上对 NaN 调 Round 会抛 EInvalidOp——x87 单元默认不屏蔽非法操作。PLDoubleToStrConst 对 NaN 写 0 是最后一道防线,但矩阵里的零是奇异变换,所以真正保护页面的是 API 层的检查。在你自己的代码里,请测试返回值:当 ScalePage 对你算出的因子返回 0 时,先把因子打印出来再说别的,因为上游某处的 0/0 产出的正是这种 NaN

两处边界是刻意保留的。元文件状态串在一个进程内用区域读写、从不落盘,所以保持绑定区域。如果你经页面生成路径测试小值,调完立即读内容:之后按文档坐标精度重新发出页面内容的操作会合法地把 1E-5 变成 0,那是舍入,不是区域泄漏

值得养成的习惯很短:用逗号分隔符跑一遍应用里所有产出 PDF 的路径,扫描输出里的逗号和指数,把 FloatToStr 挡在任何解析器要读的东西之外。从既有文件读出的数字遵循一条相关规则,见 保留解析出的十进制精度一文,那里讲原始文本如何在保存后幸存。试用版、API 参考和授权细节都在 PDFlibPas Delphi PDF library 产品页