把一台 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;
在行程內更改 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。把一個微小的縮放因子捨入成零,會讓一個合法的矩陣變成奇異矩陣,這比任何放錯位置的小數點都更糟
如果你要針對這個格式化器寫單元測試,挑範例值時要把二進位浮點數放在心上。「四位有效數字」最直覺的選擇是 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 字串不會被當成數字
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 函式庫產品頁面