Artículo técnico

Números PDF vs JSON: NaN, Infinity y null en Delphi

"value":-.25 es lo que produce un escritor de JSON cuando copia un token numérico PDF perfectamente legal tal cual, y un parser RFC 8259 estricto se rinde en el punto justo después del signo menos. Sus vecinos +1.5 y 007.5 del mismo array PDF fallan igual. Convertir números PDF a JSON significa re-deletrear cada token dígito a dígito, escribir null para NaN e Infinity, y mantener la coma decimal regional fuera de la salida

Cuatro grafías que PDF acepta y JSON rechaza

Las dos gramáticas discrepan en cuatro detalles pequeños. ISO 32000-1 §7.3.3 deja que un número empiece con signo más, omita la parte entera (.5), termine en un punto desnudo (4.) y lleve ceros a la izquierda (007.5). RFC 8259 §6 no permite nada de eso. Un número JSON tiene un menos opcional, una parte entera que es 0 o empieza con dígito de 1 a 9, y al menos un dígito tras cualquier punto decimal. Los productores tienen derecho a las formas PDF, y los generadores que imprimen números con su propio código de formato, junto con los archivos que alguien arregló a mano en un editor de texto, los usan

La colisión se agudiza en una biblioteca que respeta el texto fuente. PDF Library for Delphi (PDFlibPas) conserva los caracteres exactos que parseó para cada número real, así que un valor de color calibrado se guarda de vuelta sin cambios en lugar de redondearse a los cuatro decimales por defecto; el razonamiento está en conservar la precisión decimal parseada de PDF. El tokenizador ya remienda .5 en 0.5 y 4. en 4.0 mientras lee, y los enteros se reconstruyen desde su valor, así que +3 regresa como 3. Tres grafías siguen llegando al escritor textualmente: un punto inicial con signo (-.25), un más explícito en un real (+1.5) y ceros a la izquierda (007.5)

Un escritor que pega esos caracteres almacenados directamente en JSON produce un archivo que se ve bien en un editor. El problema empieza en el camino de vuelta. SetObjectJSON devuelve 0, y LastErrorCode reporta PDFLIB_ERROR_OBJECT_JSON_INVALID, que es 105

GetObjectJSON de PDFlibPas reescribe dígito a dígito los tokens numéricos PDF que RFC 8259 rechaza: -.25 se convierte en -0.25, +1.5 pierde el más, 007.5 suelta sus ceros a la izquierda, y dígitos fraccionarios como 1.250000 sobreviven, porque formatear desde el Double guardado añadiría ruido binario
Pegar el texto parseado exacto dejaría que la exportación tuviera éxito mientras un lector estricto se para con Invalid JSON number y el error 105, así que el escritor re-deletrea cada token en su lugar

El viaje de ida y vuelta de abajo es la manera más rápida de ver lo que GetObjectJSON emite de verdad. Cada número llega envuelto como {"type":"number","value":...}, y los tres tokens incómodos salen como -0.25, 1.5 y 7.5

uses
  System.SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  JSON: AnsiString;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('legacy-drawing.pdf', '') = 0 then
      raise Exception.Create('load failed');

    // El objeto 12 es un array escrito como [-.25 +1.5 007.5]
    JSON := Lib.GetObjectJSON(12, 0);
    if JSON = '' then
      raise Exception.CreateFmt('export failed, error %d',
        [Lib.LastErrorCode]);
    // Cada elemento se lee {"type":"number","value":-0.25} y así

    // SetObjectJSON devuelve 1 si tiene éxito; pasa 0 en Options
    if Lib.SetObjectJSON(12, JSON, 0) = 0 then
      raise Exception.CreateFmt('round trip rejected, error %d',
        [Lib.LastErrorCode]);

    Lib.SaveToFile('legacy-drawing-roundtrip.pdf');
  finally
    Lib.Free;
  end;
end;

Re-deletrear el token en lugar de recomputarlo

GetObjectJSON edita los caracteres almacenados en lugar de formatear el Double parseado. Lee un signo opcional, colecciona los dígitos a ambos lados de un único punto decimal, y luego hace solo los cambios que JSON exige: el más se va, los ceros iniciales se recortan hasta uno, una parte entera vacía pasa a 0, un punto final desnudo se suelta, y un menos vuelve a colocarse delante. Un token que contiene cualquier otro carácter, o ningún dígito, se formatea desde su valor parseado con diez decimales en su lugar, y esa ruta escribe null cuando el valor no es finito

PDFNumberTextToJSON de PDFlibPas lee el signo, recolecta dígitos alrededor de un único punto decimal y aplica solo los retoques que JSON exige, mientras que cualquier otro carácter o una tanda de dígitos vacía recurre a PLJSONNumber, que escribe null para NaN e Infinity en lugar de un número
Volver a deletrear gana a recomputar: el tokenizer ya parcheó .5 y 4. en la entrada, así que el writer conserva cada dígito superviviente y el round trip recrea exactamente el mismo valor
  • -.25 se convierte en -0.25, y +.5 en 0.5
  • +1.5 se convierte en 1.5
  • 007.5 se convierte en 7.5, mientras que 0.75 se queda como está
  • 4. se convierte en 4 si semejante token llega alguna vez al writer
  • 2.22221 y 1.250000 conservan cada dígito fraccionario, ceros finales incluidos

Formatear desde el Double habría sido una línea de código, y habría estado mal de dos maneras. La precisión de salida por defecto del documento es de cuatro decimales, así que 2.22221 perdería un dígito. Subir la precisión tampoco lo rescata: 0.1 no tiene forma binaria exacta, y una conversión a 17 dígitos significativos imprime 0.10000000000000001. Conservar los dígitos originales significa que SetObjectJSON y ImportObjectJSON, que le entregan cada número JSON al tokenizador de PDF, reconstruyen exactamente el valor que el archivo declaró

Esa promesa cubre el valor. Los bytes son otra cosa. Tras una reimportación, -.25 se almacena y se guarda como -0.25; ambas grafías son iguales bajo la §7.3.3, y aun así un diff a nivel de bytes marca el cambio. En un documento cuyos rangos de bytes cubre una firma, no pasaríamos objetos por un ciclo de exportación e importación en absoluto salvo que el plan sea volver a firmar después

Qué significa null en la salida de GetDocumentJSON

GetDocumentJSON escribe null para cualquier número que sea NaN o infinito, porque RFC 8259 §6 no tiene sintaxis para ninguno de los dos. Infinity es más fácil de producir de lo que suena. El tokenizador de PDF acumula dígitos por multiplicación repetida en un Double, que se agota cerca de 1.8 × 10308, así que un literal entero de un poco más de 300 dígitos se convierte en +Inf durante el parseo. Los productores corrientes nunca escriben ese literal; los archivos fuzzed y hostiles sí, razón por la que un entero de 400 dígitos pertenece al mismo corpus de tests que los casos de endurecer un parser PDF en Pascal contra archivos maliciosos

La comprobación de finitud tiene que ir primero. GetDocumentJSON imprime los valores integrales por debajo de MaxInt como enteros y todo lo demás con el Str(D:0:6) de Pascal, que va bien para 1.25 y es fatal para +Inf, porque Str escribe entonces el texto +Inf y ningún consumidor de JSON parsea eso. El formato de seis decimales también marca para qué es el JSON del documento. Es una visión general del archivo entero. Cuando necesitas los dígitos exactos de un objeto, pídeselos a GetObjectJSON para ese objeto

El null es con pérdida a propósito, y comparte grafía con otra cosa. Un objeto null de PDF también sale como null en el JSON del documento, así que quien consume no puede distinguir "el archivo dijo null" de "el archivo dijo un número demasiado grande para un Double" mirando ese valor. GetObjectJSON los separa: el objeto null de PDF se escribe como {"type":"null"}, y un número conserva su envoltorio "type":"number". El código que lee el JSON del documento debería aceptar null dondequiera que pueda aparecer un número, loguear el número de objeto, y tratar el archivo como sospechoso en lugar de sustituir un 0

¿Por qué un solo NaN puede abortar una exportación SVG o JSON?

Un formateador de números que escala su entrada y llama a Round encuentra Round(NaN), y en Win32, donde Delphi deja la excepción de operación inválida del x87 sin máscara, eso lanza EInvalidOp. La excepción se dispara después de que el escritor ya emitió parte de su salida. Una medición degenerada, un 0/0 dentro de una métrica o un NaN pasado por quien llama, deja un archivo truncado en disco

PLDoubleToStr en PDFlibExtra, el formateador invariante que la biblioteca usa para content streams, SVG, XML, CSV y la mayor parte de su JSON, devuelve 0 para NaN. Su rama entera acota el valor escalado a ±9.2 × 1018 igual que la rama fraccional, así que Infinity también sale como un literal finito. En un content stream es la decisión correcta. Una ranura de operando debe sostener un número, y un visor que encuentra +Inf en medio de un trazado no tiene nada sensato que dibujar

En un informe, cero es la decisión equivocada, y lo sentimos con fuerza: 0 es un ángulo de deskew o un error de píxel perfectamente plausible, así que escribirlo para "sin respuesta" corrompe los datos sin que nadie lo note. Quien escribe informes usa PLJSONNumber(Value, Decimals) de la misma unidad en su lugar, que escribe null para NaN o Infinity y dígitos invariantes en los demás casos. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON y los informes de código de barras, deskew, texto estructurado y PDF/VCR pasan todos por ahí, así que un ángulo de deskew no finito llega a quien consume como null

PDFlibPas detiene NaN e Infinity por tres vías: AddPageMatrix, ScalePage y RedactRegion rechazan argumentos no finitos de entrada, PLDoubleToStr escribe 0 para los huecos de content streams, y PLJSONNumber escribe null en los informes, donde un cero se leería como medición plausible, así que Round(NaN) nunca llega a tener la ocasión de lanzar EInvalidOp a mitad de exportación
Cero es la respuesta correcta para un content stream y la equivocada para un informe, así que los writers de informes le entregan cada Double a PLJSONNumber y dejan que null diga que el valor estaba ahí pero no era representable

La misma función es pública, así que tu propio JSON junto al de la biblioteca puede seguir la misma regla. El esbozo de abajo construye un pequeño registro de skew; la forma del registro es nuestra, la llamada de formato es de la biblioteca

uses
  SysUtils, PDFlibTypes, PDFlibExtra;

// Tu propio escritor de informes, usando la regla numérica de la biblioteca
function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string;
var
  B: PLStringBuilder;
begin
  B := PLStringBuilder.Create(128);
  try
    // Convierte cada Double a texto primero; PLJSONNumber escribe null
    // para NaN o Infinity y siempre usa punto decimal
    B.Append('{"page":').Append(Page)
     .Append(',"angle":').Append(string(PLJSONNumber(Angle, 4)))
     .Append(',"confidence":').Append(string(PLJSONNumber(Confidence, 4)))
     .Append('}');
    // Nunca B.Append(Angle): en Delphi esa sobrecarga sigue el locale del usuario
    Result := B.ToString;
  finally
    B.Free;
  end;
end;

Por dónde se cuela el locale del usuario en el JSON

Cualquier formateador que consulte los ajustes regionales puede poner una coma donde JSON necesita un punto. PLFloatToStr en PDFlibExtra es un envoltorio fino sobre FloatToStr, y eso es exactamente lo que hace. Escribe un campo como maxAcceptedMeanError con él en un escritorio alemán o francés y obtienes "maxAcceptedMeanError":1,5. Un parser de JSON lee eso como el valor 1 seguido de un token suelto. Ese campo reporta el peor error de píxel aceptado de la deduplicación perceptual de imágenes, y GetSimilarImageDeduplicationReportJSON lo escribe vía PLJSONNumber(Stats.MaxAcceptedMeanError, 6), así que el separador se queda en punto sea lo que sea lo que tenga configurado la máquina

La segunda ruta es más silenciosa. En Delphi, PLStringBuilder es un alias plano de System.SysUtils.TStringBuilder, cuya sobrecarga Append(Double) formatea a través del locale del usuario. Las builds de Free Pascal usan en su lugar una pequeña clase de constructor Unicode de PDFlibTypes, porque el TStringBuilder propio del runtime de FPC es solo ANSI. Compila la misma fuente con ambos y la build de Delphi puede discrepar de la de FPC. Un test que corre solo en Free Pascal, o solo en una máquina en-US, no verá la coma

El test de abajo reproduce un escritorio con comas dentro del proceso y le entrega el informe a un parser estricto. Elige una entrada que realmente contenga imágenes casi duplicadas; sin coincidencias el error medio es 0, y un valor sin parte fraccional esconde el problema del separador

uses
  System.SysUtils, System.JSON, PDFlibrary;

var
  Lib: TPDFlib;
  Report: WideString;
  Parsed: TJSONValue;
begin
  // Haz que este proceso se comporte como un escritorio alemán o francés
  FormatSettings.DecimalSeparator := ',';
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then
      raise Exception.Create('load failed');
    // Ensayo en seco con umbrales 2, 2, 4: el documento no se modifica
    Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report);
    Parsed := TJSONObject.ParseJSONValue(Report);
    // Esta comprobación de nil te toca añadirla a ti, no forma parte de la biblioteca
    if Parsed = nil then
      raise Exception.Create('report is not valid JSON on a comma locale');
    Parsed.Free;
  finally
    Lib.Free;
  end;
end;

Tres entradas que merecen estar en la suite de tests

El manejo de números en JSON es barato de romper y barato de guardar. Una página que lleve -.25, +1.5 y 007.5 cubre el hueco de gramática; comprueba que la salida de GetObjectJSON parsea y que SetObjectJSON devuelve 1. Un objeto que sostenga un entero de 400 dígitos cubre el desbordamiento; el JSON del documento debería mostrar null en esa posición. Un informe producido con DecimalSeparator fijado a coma cubre el locale. Pasa cada uno por un parser estricto en lugar de leer la salida a ojo, porque 1,5 y 1.5 son fáciles de perder en una línea larga de JSON

El JSON de objetos, el JSON de documento y los informes de análisis comparten estas reglas numéricas entre builds de Delphi, C++Builder y Free Pascal. La página del producto PDF Library for Delphi enumera las ediciones y el resto de la API de objetos e informes