技術文章

與地區設定無關的 PDF 數字:逗號小數 Delphi 環境對策

把一台 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 數字?

逗號小數的地區設定會弄壞 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 的 PDF Developer Library for Delphi,透過 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;
在逗號小數桌面上,受地區設定束縛的數字格式化寫出 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 代理機才是更誠實的測試

兩種數字,兩個輔助函式家族

PDFlibPas 依受眾區分它的數字輔助函式:給人看的文字可以跟著地區設定走,寫給機器的東西則永遠不跟。PDFlibExtra.pas 裡的 PLFloatToStr 與 PLStrToFloat 是 FloatToStr 與 StrToFloat 的薄包裝,宣告處的註解寫明它們只用於人類可讀的文字。機器輸出(PDF、FDF、XFDF、JSON、XML、CSV)則改走不變量家族:寫入用 PLDoubleToStrConst,讀取用 PLTryStrToFloatInvariant,而當你自己的 TryStrToFloat 呼叫需要一個點號小數的 TFormatSettings 記錄時,用 PLInvariantFormatSettings

精度是按工作而不是全域選定的。矩陣六位小數,座標與 TJ 調整四位,顏色與 FDF 矩形三位。面向機器的這一側涵蓋的地方,比 API 表面看起來的更多:

  • AddPageMatrix、ScalePage 與 DeskewPage,三者都會在既有頁面內容前面加上一個 cm
  • 產生頁面元素時寫出的 Tm 重設、TJ 前進量與 cm 變換
  • 把文字轉成路徑時產生的字形放置矩陣與外框點
  • RedactRegion 前置的黑色填滿方塊、FDF 匯出中的 /Rect 值,以及重新上色所寫出的顏色運算元

PLDoubleToStrConst 是手刻的格式化器,我們認為比起用固定的 TFormatSettings 去包 FloatToStrF,這是正確的決定。ffFixed 在整數部分超出精度之後仍會退回科學記號,而且它會留下 0.500000,而 0.5 更短也完全等價。自訂的常式永遠寫句點、去掉尾隨零,對有限輸入絕不寫指數。它也會保留小於所要求精度的非零值的有效數字:PLDoubleToStrConst(1E-9, 6) 回傳 0.000000001,只有大約 5E-16 以下的值才會變成 0。把一個微小的縮放因子捨入成零,會讓一個合法的矩陣變成奇異矩陣,這比任何放錯位置的小數點都更糟

PDFlibPas 把數字格式化一分為二:PLFloatToStr 與 PLStrToFloat 為面向使用者的文字保持地區設定相依,而 PLDoubleToStrConst 與 PLTryStrToFloatInvariant 用點號、無指數,以及六、四或三位小數的固定逐工作精度,格式化一切會變成 PDF 語法的東西
不變量格式化器刻意手刻:它去掉尾隨零、絕不寫指數,並保留微小值的有效數字,因為把縮放因子捨入成零會讓合法矩陣變成奇異矩陣

如果你要針對這個格式化器寫單元測試,挑範例值時要把二進位浮點數放在心上。「四位有效數字」最直覺的選擇是 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 顏色、註解頂點清單與輸出意圖值不是被拒收,就是被悄悄換成預設值。那是一種在開發者機器上通過所有測試、卻在慕尼黑的第一位客戶那裡失敗的程式碼,跟 那篇談碰巧能跑的 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 寫入器再把這些字串剖析回來,所以兩端一起動: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 函式庫產品頁面