Article technique

Nombres PDF sans locale pour apps Delphi à décimales virgule

Basculez une machine de test Windows sur les paramètres régionaux allemands, lancez une routine qui préfixe une matrice d'échelle et de décalage à une page, et videz le flux de contenu. Au lieu de 0.5 0 0 0.25 0.00001 12.75 cm vous obtenez 0,5 0 0 0,25 1E-5 12,75 cm. Un parseur de contenu lit là le nombre 0, puis un jeton ,5 qu'il ne reconnaît pas, puis d'autres nombres qui ne s'alignent plus avec les six opérandes qu'attend cm, et la page se dessine avec une transformation que vous n'avez jamais demandée. Les nombres qu'une machine va parser ont besoin d'un point figé, sans exposant et sans aucune dépendance à FormatSettings, du côté écriture comme du côté lecture

Pourquoi une locale à décimales virgule casse-t-elle les nombres PDF ?

Une locale à décimales virgule casse les nombres PDF parce que le formatage flottant par défaut de Delphi suit le bureau, tandis que la syntaxe des nombres PDF est figée. FloatToStr utilise FormatSettings.DecimalSeparator, si bien que sur une machine de-DE, fr-FR ou pt-BR chaque fraction sort avec une virgule. ISO 32000-1 §7.3.3 admet des chiffres, une période et un signe initial dans un nombre. Rien d'autre. La virgule coupe donc un nombre en un entier valide plus des déchets, et le résultat est une page qui se rend, juste de travers

Un second piège se cache derrière le premier, et il mord aussi sur les machines US. FloatToStr utilise le format ffGeneral, qui bascule en notation exposant dès que la magnitude passe sous 1E-4, si bien qu'un minuscule décalage s'écrit 1E-5. Le même §7.3.3 précise que PDF ne prend pas en charge la forme exposant. Remonter l'un ou l'autre problème depuis le rendu est misérable, parce qu'une matrice qui a dérivé ressemble exactement à un bug de mise en page dans votre propre code et que rien sur la page ne pointe vers les paramètres régionaux

PDFlibPas, la PDF Developer Library losLab pour Delphi, écrit les opérandes d'AddPageMatrix via PLDoubleToStrConst avec six décimales, et les sites d'appel qui génèrent du contenu de page en votre nom suivent la même règle. Le test de régression le moins cher que nous connaissions bascule le séparateur en virgule à l'intérieur du processus, appelle l'API et passe le résultat au peigne à la recherche de virgules et d'exposants :

uses
  System.SysUtils, PDFlibrary;

// Votre propre vérification, hors de la bibliothèque. Volontairement grossière :
// les chaînes de texte telles que (Hello, world) Tj contiennent aussi des virgules, donc exécutez-la
// sur une page de test qui ne dessine que des formes
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 := ',';   // se comporter comme un bureau de-DE
      Lib.AddPageMatrix(0.5, 0.25, 1E-5, 12.75);
      Content := Lib.GetPageContentToString;
      // Attendu : 0.5 0 0 0.25 0.00001 12.75 cm
      // FloatToStr aurait produit : 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;
Le formatage de nombres lié à la locale sur un bureau à décimales virgule écrit 0,5 0 0 0,25 1E-5 12,75 cm, ce qu'un parseur PDF lit comme le nombre 0 plus des jetons inconnus, laissant cm avec de mauvais opérandes et la page transformée en silence, tandis que PLDoubleToStrConst écrit des décimales à point valides
La virgule n'est pas un caractère de nombre dans la syntaxe PDF, donc le dégât se lit comme des jetons valides au sens faux — et les exposants ffGeneral comme 1E-5 sont invalides sous toutes les locales, pas seulement celles à virgule

Changer FormatSettings.DecimalSeparator dans le processus est un raccourci. Il ne sollicite pas le code qui construit son propre TFormatSettings depuis l'OS, donc si votre application fait cela, un agent de CI avec de vrais paramètres régionaux allemands est le test plus honnête

Deux sortes de nombres, deux familles de helpers

PDFlibPas découpe ses helpers de nombres selon le public : le texte montré à des humains peut suivre la locale, et tout ce qui est écrit pour une machine ne la suit jamais. PLFloatToStr et PLStrToFloat dans PDFlibExtra.pas sont de fins wrappers autour de FloatToStr et StrToFloat, et le commentaire de leur déclaration dit qu'ils sont réservés au texte lisible par des humains. La sortie machine (PDF, FDF, XFDF, JSON, XML, CSV) passe par la famille invariante à la place : PLDoubleToStrConst pour écrire, PLTryStrToFloatInvariant pour lire, et PLInvariantFormatSettings quand vous avez besoin d'un enregistrement TFormatSettings à décimales point pour vos propres appels à TryStrToFloat

La précision se choisit par tâche plutôt que globalement. Les matrices reçoivent six décimales, les coordonnées et les ajustements TJ en reçoivent quatre, les couleurs et les rectangles FDF en reçoivent trois. Le côté orienté machine couvre plus d'endroits que la surface d'API ne le suggère :

  • AddPageMatrix, ScalePage et DeskewPage, qui préfixent tous un cm au contenu existant de la page
  • Les remises à zéro Tm, les avancées TJ et les transformations cm écrites quand les éléments de page sont générés
  • Les matrices de placement de glyphes et les points de contour produits quand le texte est converti en chemins
  • La boîte de remplissage noire que RedactRegion préfixe, les valeurs /Rect de l'export FDF et les opérandes de couleur qu'écrit la recoloration

PLDoubleToStrConst est un formateur écrit à la main, et nous pensons que c'était le bon choix par rapport à envelopper FloatToStrF avec un TFormatSettings figé. ffFixed retombe de toute façon en notation scientifique dès que la partie entière dépasse la précision, et il laisserait 0.500000 là où 0.5 est plus court et identique. La routine personnalisée écrit toujours une période, rogne les zéros traînants et n'écrit jamais d'exposant pour une entrée finie. Elle garde aussi les chiffres significatifs d'une valeur non nulle plus petite que la précision demandée : PLDoubleToStrConst(1E-9, 6) renvoie 0.000000001, et seules les valeurs en dessous d'environ 5E-16 deviennent 0. Arrondir un minuscule facteur d'échelle à zéro transformerait une matrice valide en matrice singulière, ce qui est une défaillance pire que n'importe quelle décimale mal placée

PDFlibPas découpe le formatage des nombres en deux : PLFloatToStr et PLStrToFloat restent liés à la locale pour le texte destiné aux utilisateurs, tandis que PLDoubleToStrConst et PLTryStrToFloatInvariant formatent tout ce qui devient syntaxe PDF avec un point, sans exposant et une précision fixe par tâche de six, quatre ou trois décimales
Le formateur invariant est écrit à la main à dessein : il rogne les zéros traînants, n'écrit jamais d'exposant et garde les chiffres significatifs des valeurs minuscules, car arrondir un facteur d'échelle à zéro rendrait une matrice valide singulière

Si vous écrivez des tests unitaires contre le formateur, choisissez vos valeurs d'échantillon en pensant au flottant binaire. Le choix évident pour « quatre chiffres significatifs » est 0.000012345, mais multiplié par 1E8 ce double fait 1234.4999…, si bien que le résultat est 0.00001234 et l'assertion échoue pour une raison sans rapport avec les locales. Une valeur qui se tient clairement à l'écart du point milieu, telle que 0.000012346, évite l'argument entièrement :

uses
  PDFlibExtra;

// Les appels Assert sont des vérifications à ajouter dans votre propre projet de test
procedure CheckNumberHelpers;
var
  V: Double;
begin
  // Sortie machine : décimales à point, pas d'exposant, zéros traînants rognés
  Assert(PLDoubleToStrConst(1E-5, 6) = '0.00001');
  Assert(PLDoubleToStrConst(-0.5, 6) = '-0.5');
  Assert(PLDoubleToStrConst(0.000012346, 4) = '0.00001235');  // 4 chiffres significatifs gardés
  Assert(PLDoubleToStrConst(12345.25, 4) = '12345.25');

  // Entrée machine : échec doux au lieu d'un EConvertError
  Assert(PLTryStrToFloatInvariant('0.5', V) and (V = 0.5));
  Assert(PLTryStrToFloatInvariant('  12.75 ', V) and (V = 12.75)); // l'entrée est rognée
  Assert(not PLTryStrToFloatInvariant('0,5', V));   // les nombres de contenu n'utilisent jamais de virgule
end;

Pourquoi le côté lecture est-il plus dangereux que le côté écriture ?

Le côté lecture est plus dangereux parce qu'un parseur lié à la locale ne produit pas un nombre légèrement faux ; il lève. StrToFloat déclenche EConvertError chaque fois que le texte ne colle pas au séparateur système. Une passe de recoloration construite dessus abandonnerait dès qu'elle atteindrait un banal opérateur 0.5 g sur une machine à décimales virgule, ce qui signifie qu'elle échoue sur pratiquement chaque page réelle. Une chaîne de clip telle que "10.5,20.5,50.5,40.5" serait rejetée sans autre forme de procès, et les longueurs SVG, les couleurs SVG, les listes de sommets d'annotations et les valeurs d'output intent seraient soit refusées soit remplacées en silence par des défauts. C'est du code qui passe tous les tests sur la machine du développeur et qui échoue sur le premier client à Munich, la même famille de problèmes que les cas de l'article sur le code Delphi qui marche par accident

Chaque appel de style StrToFloat dans la bibliothèque est trié selon la provenance de son entrée. Les opérandes de flux de contenu, les attributs SVG, les chaînes de couleur du painter et les listes de clip et de sommets séparées par des virgules ont tous une syntaxe à point figée, donc ils passent par PLTryStrToFloatInvariant. Cet helper rogne le texte, le parse avec PLInvariantFormatSettings et renvoie False (avec la valeur fixée à 0) pour une entrée vide, mal formée, NaN ou infinie. Les listes séparées par des virgules n'ont demandé aucun débat : une virgule ne peut pas être à la fois le délimiteur de liste et la marque décimale, donc il n'existe aucune forme historique avec laquelle rester compatible

Pour le pipeline de recoloration décrit dans le guide de conversion d'un PDF vers un seul espace de couleur, le résultat est que RecolorPage et RecolorDocument parsent le contenu des pages de façon identique sur chaque locale. Les valeurs de règles qu'un appelant tape dans CheckDocumentPolicy sont le seul cas de lecture qui emprunte la voie tolérante, parce qu'une personne a tapé cette chaîne et a sans doute utilisé la marque décimale locale

Un nombre relayé par une chaîne demande que les deux bouts s'accordent

Quand un nombre est écrit dans une chaîne par une partie du code et parsé en retour par une autre, l'écrivain et le lecteur doivent suivre la même convention, et n'en changer qu'un seul casse l'aller-retour. Les attributs de structure du PDF balisé fonctionnent exactement ainsi. SetStructElemBBox formate quatre valeurs en une chaîne et la stocke via AddTagAttribute. Quand le dictionnaire d'attributs /A est écrit, cette chaîne est parsée de nouveau pour décider si elle devient un nombre, un tableau ou un name

Si les deux bouts suivaient la locale système, l'aller-retour serait auto-cohérent sur une machine allemande. L'ennui commence avec un appelant qui suit la documentation et passe "0.5" à AddTagAttribute : un lecteur lié à la locale ne peut pas le parser et émet le name PDF /0.5. Les placeholders PDF/VCR touchent l'image miroir, puisque leur GTS_BBox est généré avec un point et qu'une étape de validation liée à la locale avant la sauvegarde le rejetterait. Et ne basculer que l'écrivain vers le point aggrave les choses, parce que chaque valeur SetStructElem* se transformerait alors en name sur les systèmes à décimales virgule

Les écrivains emploient donc PLDoubleToStrConst(v, 6) et le lecteur emploie PLTryStrToFloatLenient, qui essaie d'abord la forme à point et retombe sur la locale système. Un appelant en locale virgule qui passe "1,25" obtient le nombre 1.25. Il y a un coût, et nous l'avons accepté en connaissance de cause : sur un système allemand "1.500" se lit 1.5 plutôt que mille cinq cents, parce que la forme à point gagne. L'API documente le point comme séparateur, donc un groupement de milliers à l'allemande dans une chaîne d'attribut est l'entrée que nous avons choisi d'abandonner. Les chaînes littérales NAN et INF ne sont pas traitées comme des nombres

PDFlibPas SetStructElemBBox et ses frères relaient les nombres sous forme de chaînes via AddTagAttribute, et l'écrivain /A parse ces chaînes en retour, si bien que les deux bouts bougent ensemble : PLDoubleToStrConst écrit avec un point et PLTryStrToFloatLenient lit d'abord le point avec repli sur la locale, pour qu'un 1,25 en locale virgule se lise toujours comme 1.25
Ne réparer que l'écrivain aurait dégradé chaque attribut d'élément structuré en PDF name, voilà pourquoi un aller-retour déplace les deux bouts ensemble ou pas du tout
uses
  System.SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
begin
  FormatSettings.DecimalSeparator := ',';   // appelant à décimales virgule
  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 plutôt que /0.5
    Lib.AddTagAttribute('Layout', 'StartIndent', '1,25'); // /StartIndent 1.25 via le repli sur la locale
    Lib.DrawText(20, 20, 'figure');
    Lib.EndTag;
    Lib.SaveToFile('tagged.pdf');
  finally
    Lib.Free;
  end;
end;

Notre recommandation pour votre propre code est de passer des chaînes à décimales point à AddTagAttribute et de laisser le repli virgule pour les valeurs que vous ne contrôlez pas, telles que les chaînes chargées depuis un ancien fichier de configuration. La façon dont l'arbre de structure autour de ces attributs se construit est couverte dans le guide de structure PDF balisée

Là où NaN et infini se font arrêter

AddPageMatrix, ScalePage et RedactRegion rejettent les arguments NaN et infinis d'entrée de jeu et renvoient 0, puisqu'aucun nombre PDF ne peut représenter ni l'un ni l'autre. La vérification doit être explicite. NaN passe un test <= 0, si bien qu'une vérification de plage sur un facteur d'échelle seul laisserait un facteur NaN voyager jusqu'au formateur, et appeler Round sur NaN lève EInvalidOp en Win32, où l'unité x87 ne masque pas les opérations invalides par défaut. PLDoubleToStrConst écrit 0 pour NaN en dernière ligne de défense, mais un zéro à l'intérieur d'une matrice est une transformation singulière, donc la vérification au niveau de l'API est celle qui protège réellement la page. Dans votre propre code, testez la valeur de retour : quand ScalePage renvoie 0 pour un facteur que vous avez calculé, imprimez le facteur avant toute autre chose, parce qu'un 0/0 quelque part en amont produit exactement ce NaN

Deux frontières sont délibérées. Les chaînes d'état des metafiles sont écrites et lues avec la locale à l'intérieur d'un seul processus et n'atteignent jamais un fichier, donc elles restent liées à la locale. Et si vous testez de petites valeurs par le chemin de génération de page, lisez le contenu juste après l'appel : une opération qui réémet plus tard le contenu de la page à la précision de coordonnées du document transformera légitimement 1E-5 en 0, et c'est un arrondi, pas une fuite de locale

L'habitude à adopter est courte. Faites tourner une fois les chemins de production de PDF de votre application avec un séparateur virgule, passez la sortie au peigne à la recherche de virgules et d'exposants, et gardez FloatToStr hors de tout ce qu'un parseur lira. Les nombres lus depuis un fichier existant suivent une règle apparentée, couverte dans l'article sur la préservation de la précision décimale parsée, où le texte source exact survit à une sauvegarde. Les builds d'essai, la référence API et les détails de licence sont sur la page produit de la PDFlibPas Delphi PDF library