Portate una macchina di test Windows sulle impostazioni regionali tedesche, fate girare una routine che premette una matrice di scala e traslazione a una pagina, e buttate fuori il content stream. Invece di 0.5 0 0 0.25 0.00001 12.75 cm ottenete 0,5 0 0 0,25 1E-5 12,75 cm. Un parser di contenuto legge quello come il numero 0, poi un token ,5 che non riconosce, poi altri numeri che non tornano più con i sei operandi che cm si aspetta, e la pagina si disegna con una trasformazione che non avete mai chiesto. I numeri che una macchina deve parsare hanno bisogno di un punto fisso, niente esponente e nessuna dipendenza da FormatSettings, sia sul lato scrittura sia sul lato lettura
Perché un locale con virgola decimale rompe i numeri PDF?
Un locale con virgola decimale rompe i numeri PDF perché la formattazione float predefinita di Delphi segue il desktop, mentre la sintassi dei numeri PDF è fissa. FloatToStr usa FormatSettings.DecimalSeparator, quindi su una macchina de-DE, fr-FR o pt-BR ogni frazione esce con la virgola. ISO 32000-1 §7.3.3 ammette in un numero cifre, un punto e un segno iniziale. Nient'altro. La virgola quindi spacca un numero in un intero valido più spazzatura, e il risultato è una pagina che si renderizza, solo sbagliata
C'è una seconda trappola dietro alla prima, e morde anche sulle macchine statunitensi. FloatToStr usa il formato ffGeneral, che passa alla notazione con esponente appena la magnitudine scende sotto 1E-4, quindi un offset minuscolo viene scritto come 1E-5. Lo stesso §7.3.3 dice che il PDF non supporta la forma con esponente. Risalire a uno dei due problemi dall'output renderizzato è misero, perché una matrice driftata assomiglia esattamente a un bug di layout nel vostro codice e niente sulla pagina punta alle impostazioni regionali
PDFlibPas, la losLab PDF Developer Library per Delphi, scrive gli operandi di AddPageMatrix tramite PLDoubleToStrConst con sei cifre decimali, e i punti di chiamata che generano contenuto di pagina per vostro conto seguono la stessa regola. Il test di regressione più economico che conosciamo ribalta il separatore in virgola dentro il processo, chiama l'API e scansione il risultato in cerca di virgole ed esponenti:
uses
System.SysUtils, PDFlibrary;
// Un controllo vostro, non fa parte della libreria. È volutamente grezzo:
// le stringhe di testo come (Hello, world) Tj contengono anch'esse virgole, quindi eseguitelo
// su una pagina di test che disegna solo forme
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 := ','; // comportati come un desktop de-DE
Lib.AddPageMatrix(0.5, 0.25, 1E-5, 12.75);
Content := Lib.GetPageContentToString;
// Atteso: 0.5 0 0 0.25 0.00001 12.75 cm
// FloatToStr avrebbe prodotto: 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;
Cambiare FormatSettings.DecimalSeparator dentro il processo è una scorciatoia. Non esercita il codice che costruisce il proprio TFormatSettings dall'OS, quindi se la vostra applicazione lo fa, un agente CI con vere impostazioni regionali tedesche è il test più onesto
Due tipi di numeri, due famiglie di helper
PDFlibPas separa i suoi helper numerici per pubblico: il testo mostrato alle persone può seguire il locale, e qualsiasi cosa scritta per una macchina non lo segue mai. PLFloatToStr e PLStrToFloat in PDFlibExtra.pas sono wrapper sottili su FloatToStr e StrToFloat, e il commento sulla loro dichiarazione dice che sono solo per testo leggibile dagli umani. L'output per macchine (PDF, FDF, XFDF, JSON, XML, CSV) passa invece per la famiglia invariante: PLDoubleToStrConst per scrivere, PLTryStrToFloatInvariant per leggere, e PLInvariantFormatSettings quando vi serve un record TFormatSettings con decimale a punto per le vostre chiamate TryStrToFloat
La precisione si sceglie per lavoro e non globalmente. Le matrici ottengono sei decimali, coordinate e aggiustamenti TJ quattro, colori e rettangoli FDF tre. Il lato rivolto alle macchine copre più posti di quanto la superficie API suggerisca:
AddPageMatrix,ScalePageeDeskewPage, che premettono tutti uncmal contenuto di pagina esistente- I reset
Tm, gli avanzamentiTJe le trasformazionicmscritti quando gli elementi di pagina vengono generati - Le matrici di posizionamento dei glifi e i punti di contorno prodotti quando il testo viene convertito in path
- Il box di riempimento nero che
RedactRegionpremette, i valori/Rectnell'export FDF e gli operandi di colore che il recoloring scrive
PLDoubleToStrConst è un formattatore scritto a mano, e pensiamo che sia stata la scelta giusta rispetto a incapsulare FloatToStrF con un TFormatSettings fisso. ffFixed ripiega comunque sulla notazione scientifica appena la parte intera supera la precisione, e lascerebbe 0.500000 dove 0.5 è più corto e identico. La routine custom scrive sempre un punto, rimuove gli zeri finali e non scrive mai un esponente per input finito. Conserva anche le cifre significative di un valore non zero più piccolo della precisione richiesta: PLDoubleToStrConst(1E-9, 6) restituisce 0.000000001, e solo i valori sotto circa 5E-16 diventano 0. Arrotondare a zero un fattore di scala minuscolo trasformerebbe una matrice valida in una singolare, che è un fallimento peggiore di qualsiasi decimale fuori posto
Se scrivete unit test contro il formattatore, scegliete i valori di esempio tenendo presente il floating point binario. La scelta ovvia per "quattro cifre significative" è 0.000012345, ma moltiplicato per 1E8 quel double fa 1234.4999…, quindi il risultato è 0.00001234 e l'asserzione fallisce per un motivo non legato ai locale. Un valore che sta chiaramente fuori dal punto medio, come 0.000012346, evita la discussione del tutto:
uses
PDFlibExtra;
// le chiamate Assert sono controlli che aggiungete nel vostro progetto di test
procedure CheckNumberHelpers;
var
V: Double;
begin
// output per macchine: decimale a punto, niente esponente, zeri finali tolti
Assert(PLDoubleToStrConst(1E-5, 6) = '0.00001');
Assert(PLDoubleToStrConst(-0.5, 6) = '-0.5');
Assert(PLDoubleToStrConst(0.000012346, 4) = '0.00001235'); // 4 cifre significative conservate
Assert(PLDoubleToStrConst(12345.25, 4) = '12345.25');
// input per macchine: False invece di EConvertError
Assert(PLTryStrToFloatInvariant('0.5', V) and (V = 0.5));
Assert(PLTryStrToFloatInvariant(' 12.75 ', V) and (V = 12.75)); // l'input viene trimmed
Assert(not PLTryStrToFloatInvariant('0,5', V)); // i numeri di contenuto non usano mai la virgola
end;
Perché il lato parsing è più pericoloso del lato scrittura?
Il lato parsing è più pericoloso perché un parser legato al locale non produce un numero leggermente sbagliato; solleva. StrToFloat butta EConvertError ogni volta che il testo non corrisponde al separatore di sistema. Un passaggio di recoloring costruito su di esso si interromperebbe nel momento in cui raggiunge un normale operatore 0.5 g su una macchina con virgola decimale, il che significa che fallisce su praticamente ogni pagina reale. Una clip string come "10.5,20.5,50.5,40.5" verrebbe rifiutata in blocco, e lunghezze SVG, colori SVG, liste di vertici delle annotazioni e valori di output intent verrebbero rifiutati o sostituiti in silenzio dai default. È codice che passa ogni test sulla macchina dello sviluppatore e fallisce per il primo cliente a Monaco, la stessa famiglia di problemi dei casi nell'articolo sul codice Delphi che funziona per caso
Ogni chiamata in stile StrToFloat nella libreria è classificata per provenienza del suo input. Gli operandi dei content stream, gli attributi SVG, le stringhe di colore del painter e le liste di clip e vertici separate da virgole hanno tutti una sintassi a punto fissa, quindi passano per PLTryStrToFloatInvariant. Quell'helper fa il trim del testo, lo parsa con PLInvariantFormatSettings e restituisce False (col valore impostato a 0) per input vuoto, malformato, NaN o infinito. Le liste separate da virgole non hanno avuto bisogno di alcuna discussione: una virgola non può essere insieme delimitatore di lista e segno decimale, quindi non c'è nessuna forma legacy con cui restare compatibili
Per la pipeline di recoloring descritta nella guida alla conversione di un PDF a un solo color space, il risultato è che RecolorPage e RecolorDocument parsano il contenuto di pagina in modo identico su ogni locale. I valori delle regole che un chiamante digita in CheckDocumentPolicy sono l'unico caso di parsing che prende la strada permissiva, perché quella stringa l'ha scritta una persona che ben può aver usato il segno decimale locale
Un numero trasmesso attraverso una stringa vuole che entrambe le estremità siano d'accordo
Quando un numero viene scritto in una stringa da una parte del codice e riparsato da un'altra, lo scrittore e il lettore devono seguire la stessa convenzione, e cambiarne uno solo rompe il round trip. Gli attributi di struttura del PDF taggato funzionano esattamente così. SetStructElemBBox formatta quattro valori in una stringa e la memorizza tramite AddTagAttribute. Quando il dizionario di attributi /A viene scritto, quella stringa viene parsata di nuovo per decidere se diventa un numero, un array o un name
Se entrambe le estremità seguissero il locale di sistema, il viaggio sarebbe autoconsistente su una macchina tedesca. Il guaio comincia con un chiamante che segue la documentazione e passa "0.5" a AddTagAttribute: un lettore legato al locale non riesce a parsarlo ed emette il name PDF /0.5. I placeholder PDF/VCR subiscono l'immagine speculare, dato che il loro GTS_BBox viene generato col punto e un passo di validazione legato al locale prima del salvataggio lo rifiuterebbe. E cambiare solo lo scrittore al punto peggiora le cose, perché ogni valore SetStructElem* diventerebbe allora un name sui sistemi con virgola decimale
Quindi gli scrittori usano PLDoubleToStrConst(v, 6) e il lettore usa PLTryStrToFloatLenient, che prova prima la forma col punto e ripiega sul locale di sistema. Un chiamante con locale a virgola che passa "1,25" ottiene il numero 1.25. C'è un costo, e lo abbiamo accettato consapevolmente: su un sistema tedesco "1.500" viene letto come 1.5 invece che come millecinquecento, perché la forma col punto vince. L'API documenta il punto come separatore, quindi un raggruppamento delle migliaia in stile tedesco in una stringa di attributo è l'input a cui abbiamo scelto di rinunciare. Le stringhe literal NAN e INF non sono trattate come numeri
uses
System.SysUtils, PDFlibrary;
var
Lib: TPDFlib;
begin
FormatSettings.DecimalSeparator := ','; // chiamante con virgola decimale
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 anziché /0.5
Lib.AddTagAttribute('Layout', 'StartIndent', '1,25'); // /StartIndent 1.25 tramite il fallback al locale
Lib.DrawText(20, 20, 'figure');
Lib.EndTag;
Lib.SaveToFile('tagged.pdf');
finally
Lib.Free;
end;
end;
La nostra raccomandazione per il vostro codice è passare stringhe decimali a punto a AddTagAttribute e lasciare il ripiego sulla virgola per i valori che non potete controllare, come stringhe caricate da un file di configurazione più vecchio. Come viene costruito l'albero di struttura attorno a quegli attributi è trattato nella guida alla struttura dei PDF taggati
Dove NaN e infinito vengono fermati
AddPageMatrix, ScalePage e RedactRegion rifiutano upfront gli argomenti NaN e infiniti e restituiscono 0, dato che nessun numero PDF può rappresentare né l'uno né l'altro. Il controllo deve essere esplicito. NaN sfugge a un test <= 0, quindi un controllo di intervallo sul solo fattore di scala lascerebbe viaggiare una scala NaN fino al formattatore, e chiamare Round su NaN solleva EInvalidOp su Win32, dove l'unità x87 non maschera per default le operazioni invalide. PLDoubleToStrConst scrive 0 per NaN come ultima linea di difesa, ma uno zero dentro una matrice è una trasformazione singolare, quindi il controllo a livello API è quello che davvero protegge la pagina. Nel vostro codice, testate il valore di ritorno: quando ScalePage restituisce 0 per un fattore che avete calcolato, stampate il fattore prima di ogni altra cosa, perché uno 0/0 da qualche parte a monte produce esattamente questo NaN
Due confini sono deliberati. Le stringhe di stato dei metafile vengono scritte e lette col locale dentro un unico processo e non raggiungono mai un file, quindi restano legate al locale. E se testate valori piccoli attraverso il percorso di generazione di pagina, leggete il contenuto subito dopo la chiamata: un'operazione che più tardi riemette il contenuto di pagina alla precisione di coordinate del documento legittimamente trasformerà 1E-5 in 0, e quello è arrotondamento, non una fuga di locale
L'abitudine da adottare è breve. Fate girare una volta i percorsi di produzione PDF della vostra applicazione col separatore a virgola, scansite l'output in cerca di virgole ed esponenti, e tenete FloatToStr fuori da tutto ciò che un parser leggerà. I numeri letti da un file esistente seguono una regola affine, trattata nell'articolo sulla conservazione della precisione decimale parsed, dove il testo sorgente esatto sopravvive a un salvataggio. Le build di prova, il riferimento API e i dettagli di licenza sono sulla pagina del prodotto PDFlibPas Delphi PDF library