Articolo tecnico

Numeri PDF locale-neutral per Delphi con decimali a virgola

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;
La formattazione dei numeri legata al locale su un desktop con virgola decimale scrive 0,5 0 0 0,25 1E-5 12,75 cm, che un parser PDF legge come il numero 0 più token sconosciuti, lasciando cm con operandi sbagliati e la pagina trasformata in silenzio, mentre PLDoubleToStrConst scrive decimali validi col punto
La virgola non è un carattere numerico nella sintassi PDF, quindi il danno si legge come token validi col significato sbagliato — e gli esponenti ffGeneral come 1E-5 sono invalidi su ogni locale, non solo su quelli a virgola

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, ScalePage e DeskewPage, che premettono tutti un cm al contenuto di pagina esistente
  • I reset Tm, gli avanzamenti TJ e le trasformazioni cm scritti 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 RedactRegion premette, i valori /Rect nell'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

PDFlibPas divide la formattazione dei numeri in due: PLFloatToStr e PLStrToFloat restano legati al locale per il testo rivolto all'utente, mentre PLDoubleToStrConst e PLTryStrToFloatInvariant formattano tutto ciò che diventa sintassi PDF con punto, niente esponente e una precisione fissa per compito di sei, quattro o tre decimali
Il formattatore invariante è scritto a mano di proposito: toglie gli zeri finali, non scrive mai un esponente e conserva le cifre significative dei valori minuscoli, perché arrotondare a zero un fattore di scala renderebbe singolare una matrice valida

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

PDFlibPas SetStructElemBBox e i suoi fratelli passano i numeri come stringhe attraverso AddTagAttribute, e lo scrittore /A analizza quelle stringhe, quindi entrambe le estremità si muovono insieme: PLDoubleToStrConst scrive con punto e PLTryStrToFloatLenient legge prima il punto con fallback al locale, così un 1,25 con locale a virgola si legge ancora come 1.25
Correggere solo lo scrittore avrebbe degradato ogni attributo di elemento strutturato in un name PDF, per questo un round trip sposta insieme entrambe le estremità o nessuna
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