Cambie un equipo de pruebas de Windows a configuración regional alemana, corra una rutina que antepone una matriz de escala y desplazamiento a una página, y vuelque el content stream. En lugar de 0.5 0 0 0.25 0.00001 12.75 cm obtiene 0,5 0 0 0,25 1E-5 12,75 cm. Un parser de contenido lee eso como el número 0, luego un token ,5 que no reconoce, y luego más números que ya no se alinean con los seis operandos que cm espera, y la página se dibuja con una transformación que usted nunca pidió. Los números que una máquina va a parsear necesitan punto fijo, sin exponente y sin ninguna dependencia de FormatSettings, en el lado de escritura y en el lado de lectura
¿Por qué un locale con decimal coma rompe los números PDF?
Un locale con decimal coma rompe los números PDF porque el formateo float por defecto de Delphi sigue al escritorio, mientras que la sintaxis de números PDF es fija. FloatToStr usa FormatSettings.DecimalSeparator, así que en una máquina de-DE, fr-FR o pt-BR toda fracción sale con coma. ISO 32000-1 §7.3.3 permite en un número dígitos, un punto y un signo inicial. Nada más. La coma por tanto parte un número en un entero válido más basura, y el resultado es una página que se renderiza, solo que mal
Hay una segunda trampa detrás de la primera, y muerde también en máquinas de US. FloatToStr usa el formato ffGeneral, que salta a notación de exponente en cuanto la magnitud baja de 1E-4, así que un offset diminuto se escribe como 1E-5. El mismo §7.3.3 dice que PDF no soporta la forma exponencial. Rastrear cualquiera de los dos problemas desde la salida renderizada es miserable, porque una matriz desviada se ve exactamente como un bug de layout en su propio código y nada en la página apunta a la configuración regional
PDFlibPas, la PDF Developer Library de losLab para Delphi, escribe los operandos de AddPageMatrix a través de PLDoubleToStrConst con seis decimales, y los call sites que generan contenido de página en su nombre siguen la misma regla. La prueba de regresión más barata que conocemos voltea el separador a coma dentro del proceso, llama a la API y escanea el resultado buscando comas y exponentes:
uses
System.SysUtils, PDFlibrary;
// Su propia verificación, no parte de la biblioteca. Es burda a propósito:
// los strings de texto como (Hello, world) Tj también contienen comas, así que córrala
// sobre una página de prueba que solo dibuja formas
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 := ','; // compórtese como un escritorio de-DE
Lib.AddPageMatrix(0.5, 0.25, 1E-5, 12.75);
Content := Lib.GetPageContentToString;
// Esperado: 0.5 0 0 0.25 0.00001 12.75 cm
// FloatToStr habría producido: 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;
Cambiar FormatSettings.DecimalSeparator dentro del proceso es un atajo. No ejercita el código que construye su propio TFormatSettings desde el OS, así que si su aplicación hace eso, un agente de CI con configuración regional alemana real es la prueba más honesta
Dos clases de números, dos familias de helpers
PDFlibPas parte sus helpers de números por audiencia: el texto que la gente ve puede seguir el locale, y lo que se escribe para una máquina nunca lo hace. PLFloatToStr y PLStrToFloat en PDFlibExtra.pas son wrappers delgados sobre FloatToStr y StrToFloat, y el comentario en su declaración dice que son solo para texto legible por humanos. La salida de máquina (PDF, FDF, XFDF, JSON, XML, CSV) pasa por la familia invariante en su lugar: PLDoubleToStrConst para escribir, PLTryStrToFloatInvariant para leer, y PLInvariantFormatSettings cuando necesita un record TFormatSettings con decimal punto para sus propias llamadas TryStrToFloat
La precisión se elige por tarea en lugar de globalmente. Las matrices obtienen seis decimales, las coordenadas y los ajustes de TJ obtienen cuatro, los colores y los rectángulos FDF obtienen tres. El lado de máquina cubre más lugares de lo que la superficie de la API sugiere:
AddPageMatrix,ScalePageyDeskewPage, que todos anteponen uncmal contenido existente de la página- Los resets de
Tm, los avances deTJy las transformaciones decmque se escriben cuando se generan los elementos de página - Las matrices de colocación de glifos y los puntos de outline producidos cuando el texto se convierte a paths
- La caja de relleno negro que
RedactRegionantepone, los valores/Rectdel export FDF y los operandos de color que escribe el recoloreo
PLDoubleToStrConst es un formateador escrito a mano, y creemos que fue la decisión correcta frente a envolver FloatToStrF con un TFormatSettings fijo. ffFixed igual cae a notación científica una vez que la parte entera supera la precisión, y dejaría 0.500000 donde 0.5 es más corto e idéntico. La rutina propia siempre escribe un punto, recorta los ceros finales y nunca escribe un exponente para entrada finita. También conserva los dígitos significativos de un valor no cero menor que la precisión pedida: PLDoubleToStrConst(1E-9, 6) devuelve 0.000000001, y solo los valores por debajo de unos 5E-16 se vuelven 0. Redondear un factor de escala diminuto a cero convertiría una matriz válida en una singular, lo que es un fallo peor que cualquier decimal mal puesto
Si escribe unit tests contra el formateador, elija sus valores de muestra pensando en el punto flotante binario. La elección obvia para “cuatro dígitos significativos” es 0.000012345, pero multiplicado por 1E8 ese double es 1234.4999…, así que el resultado es 0.00001234 y la aserción falla por una razón no relacionada con locales. Un valor que quede claramente fuera del punto medio, como 0.000012346, evita la discusión por completo:
uses
PDFlibExtra;
// Las llamadas Assert son chequeos que agrega en su propio proyecto de pruebas
procedure CheckNumberHelpers;
var
V: Double;
begin
// Salida de máquina: decimal punto, sin exponente, ceros finales recortados
Assert(PLDoubleToStrConst(1E-5, 6) = '0.00001');
Assert(PLDoubleToStrConst(-0.5, 6) = '-0.5');
Assert(PLDoubleToStrConst(0.000012346, 4) = '0.00001235'); // se conservan 4 dígitos significativos
Assert(PLDoubleToStrConst(12345.25, 4) = '12345.25');
// Entrada de máquina: False en lugar de EConvertError
Assert(PLTryStrToFloatInvariant('0.5', V) and (V = 0.5));
Assert(PLTryStrToFloatInvariant(' 12.75 ', V) and (V = 12.75)); // la entrada se recorta
Assert(not PLTryStrToFloatInvariant('0,5', V)); // los números de contenido nunca usan coma
end;
¿Por qué el lado de parsing es más peligroso que el lado de escritura?
El lado de parsing es más peligroso porque un parser atado al locale no produce un número levemente equivocado; levanta una excepción. StrToFloat lanza EConvertError siempre que el texto no coincida con el separador del sistema. Una pasada de recoloreo construida sobre él abortaría en el momento en que alcanzara un operador 0.5 g ordinario en una máquina con decimal coma, lo que significa que falla en prácticamente toda página real. Un string de clip como "10.5,20.5,50.5,40.5" se rechazaría de plano, y las longitudes SVG, los colores SVG, las listas de vértices de anotaciones y los valores de output intent se rechazarían o se reemplazarían silenciosamente por valores por defecto. Ese es código que pasa todas las pruebas en la máquina del desarrollador y falla con el primer cliente en Múnich, la misma familia de problemas que los casos de el artículo sobre código Delphi que funciona de casualidad
Cada llamada estilo StrToFloat en la biblioteca está clasificada por de dónde viene su entrada. Los operandos de content streams, los atributos SVG, los strings de color del painter y las listas de clip y vértices separadas por coma tienen todas una sintaxis de punto fija, así que pasan por PLTryStrToFloatInvariant. Ese helper recorta el texto, lo parsea con PLInvariantFormatSettings y devuelve False (con el valor puesto en 0) para entrada vacía, malformada, NaN o infinita. Las listas separadas por coma no necesitaron ningún debate: una coma no puede ser a la vez delimitador de lista y marca decimal, así que no hay forma legada con la que quedarse compatible
Para el pipeline de recoloreo descrito en la guía para convertir un PDF a un espacio de color, el resultado es que RecolorPage y RecolorDocument parsean el contenido de página de forma idéntica en cada locale. Los valores de reglas que un llamador teclea en CheckDocumentPolicy son el único caso de parsing que toma la ruta permisiva, porque una persona tecleó ese string y bien pudo usar la marca decimal local
Un número transmitido a través de un string necesita que ambos extremos coincidan
Cuando un número se escribe a un string por una parte del código y se parsea de vuelta por otra, el escritor y el lector tienen que seguir la misma convención, y cambiar solo uno de ellos rompe el round trip. Los atributos de estructura de PDF etiquetado funcionan exactamente así. SetStructElemBBox formatea cuatro valores en un string y lo guarda a través de AddTagAttribute. Cuando el diccionario de atributos /A se escribe, ese string se parsea otra vez para decidir si se vuelve un número, un arreglo o un name
Si ambos extremos siguieran el locale del sistema, el viaje sería autoconsistente en una máquina alemana. El problema empieza con un llamador que sigue la documentación y pasa "0.5" a AddTagAttribute: un lector atado al locale no puede parsearlo y emite el name de PDF /0.5. Los placeholders de PDF/VCR sufren la imagen en espejo, como su GTS_BBox se genera con punto y un paso de validación atado al locale antes de guardar lo rechazaría. Y cambiar solo el escritor a punto empeora las cosas, porque cada valor de SetStructElem* se volvería entonces un name en sistemas con decimal coma
Así que los escritores usan PLDoubleToStrConst(v, 6) y el lector usa PLTryStrToFloatLenient, que prueba primero la forma con punto y cae al locale del sistema. Un llamador con locale coma que pasa "1,25" obtiene el número 1.25. Hay un costo, y lo aceptamos a sabiendas: en un sistema alemán "1.500" se lee como 1.5 en lugar de mil quinientos, porque la forma con punto gana. La API documenta el punto como separador, así que un grupo de miles estilo alemán en un string de atributo es la entrada que elegimos abandonar. Los strings literales NAN e INF no se tratan como números
uses
System.SysUtils, PDFlibrary;
var
Lib: TPDFlib;
begin
FormatSettings.DecimalSeparator := ','; // llamador con decimal coma
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 en lugar de /0.5
Lib.AddTagAttribute('Layout', 'StartIndent', '1,25'); // /StartIndent 1.25 vía el fallback de locale
Lib.DrawText(20, 20, 'figure');
Lib.EndTag;
Lib.SaveToFile('tagged.pdf');
finally
Lib.Free;
end;
end;
Nuestra recomendación para su propio código es pasar strings con decimal punto a AddTagAttribute y dejar el fallback de coma para valores que usted no puede controlar, como strings cargados de un archivo de configuración más viejo. Cómo se construye el árbol de estructura alrededor de esos atributos está cubierto en la guía de estructura de PDF etiquetado
Dónde se frenan NaN y el infinito
AddPageMatrix, ScalePage y RedactRegion rechazan de entrada los argumentos NaN e infinitos y devuelven 0, ya que ningún número de PDF puede representar ninguno de los dos. La verificación tiene que ser explícita. NaN se escapa de un test de <= 0, así que una verificación de rango sobre un factor de escala solo dejaría que un NaN viajara hasta el formateador, y llamar a Round sobre NaN levanta EInvalidOp en Win32, donde la unidad x87 no enmascara las operaciones inválidas por defecto. PLDoubleToStrConst escribe 0 ante NaN como última línea de defensa, pero un cero dentro de una matriz es una transformación singular, así que la verificación a nivel de API es la que de verdad protege la página. En su propio código, verifique el valor de retorno: cuando ScalePage devuelve 0 para un factor que usted computó, imprima el factor antes que cualquier otra cosa, porque un 0/0 en algún lugar upstream produce exactamente este NaN
Dos fronteras son deliberadas. Los strings de estado de metafile se escriben y se leen con el locale dentro de un solo proceso y nunca llegan a un archivo, así que siguen atados al locale. Y si prueba valores pequeños por el camino de generación de página, lea el contenido justo después de la llamada: una operación que luego re-emite el contenido de la página a la precisión de coordenadas del documento convertirá legítimamente 1E-5 en 0, y eso es redondeo, no un leak de locale
El hábito que vale adoptar es corto. Corra los caminos de su aplicación que producen PDF una vez con separador coma, escanee la salida buscando comas y exponentes, y mantenga FloatToStr fuera de cualquier cosa que un parser vaya a leer. Los números leídos de un archivo existente siguen una regla relacionada, cubierta en el artículo sobre preservar la precisión decimal parseada, donde el texto fuente exacto sobrevive a un guardado. Los builds de prueba, la referencia de la API y los detalles de licencia están en la página de producto de la PDFlibPas Delphi PDF library