Artigo Técnico

Número de PDF vs JSON: NaN, Infinity e null no Delphi

"value":-.25 é o que um escritor JSON produz quando copia um token de número PDF perfeitamente legal como está, e um parser RFC 8259 estrito desiste no ponto logo depois do sinal de menos. Seus vizinhos +1.5 e 007.5 do mesmo array PDF falham do mesmo jeito. Transformar números de PDF em JSON significa reescrever cada token dígito por dígito, gravar null para NaN e Infinity, e manter a vírgula decimal regional fora da saída

Quatro grafias que o PDF aceita e o JSON rejeita

As duas gramáticas discordam em quatro detalhes pequenos. A ISO 32000-1 §7.3.3 deixa um número começar com sinal de mais, omitir a parte inteira (.5), terminar em um ponto solto (4.) e carregar zeros à esquerda (007.5). O RFC 8259 §6 não permite nada disso. Um número JSON tem um menos opcional, uma parte inteira que é 0 ou começa com dígito de 1 a 9, e pelo menos um dígito depois de qualquer ponto decimal. Produtores têm direito às formas do PDF, e geradores que imprimem números com seu próprio código de formatação, junto com arquivos que alguém consertou à mão em um editor de texto, as usam

A colisão fica mais aguda em uma biblioteca que respeita o texto de origem. A PDF Library for Delphi (PDFlibPas) guarda os caracteres exatos que parseou para todo número real, então um valor de cor calibrado é salvo de volta sem mudança em vez de ser arredondado para as quatro casas decimais padrão; o raciocínio está em preservando a precisão decimal parseada do PDF. O tokenizer já conserta .5 em 0.5 e 4. em 4.0 durante a leitura, e inteiros são reconstruídos do seu valor, então +3 volta como 3. Três grafias ainda chegam ao escritor verbatim: um ponto precedente com sinal (-.25), um mais explícito em um real (+1.5) e zeros à esquerda (007.5)

Um escritor que cola esses caracteres guardados direto no JSON produz um arquivo que parece bem em um editor. O problema começa na volta. O SetObjectJSON devolve 0, e o LastErrorCode reporta PDFLIB_ERROR_OBJECT_JSON_INVALID, que é 105

O GetObjectJSON do PDFlibPas reescreve os tokens de número PDF que o RFC 8259 rejeita dígito por dígito: -.25 vira -0.25, +1.5 perde o mais, 007.5 derruba seus zeros à esquerda, e dígitos fracionários como 1.250000 sobrevivem, porque formatar a partir do Double guardado adicionaria ruído binário
Anexar o texto parseado exato deixaria a exportação ter sucesso enquanto um leitor estrito para com Invalid JSON number e erro 105, então o escritor reescreve cada token em vez disso

A ida e volta abaixo é o jeito mais rápido de ver o que o GetObjectJSON realmente emite. Cada número chega embrulhado como {"type":"number","value":...}, e os três tokens desajeitados saem como -0.25, 1.5 e 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');

    // O objeto 12 é um array gravado 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 lê {"type":"number","value":-0.25} e por aí vai

    // SetObjectJSON devolve 1 em caso de sucesso; passe 0 para 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;

Reescrevendo o token em vez de recalculá-lo

O GetObjectJSON edita os caracteres guardados em vez de formatar o Double parseado. Ele lê um sinal opcional, coleta os dígitos dos dois lados de um único ponto decimal, e então faz só as mudanças que o JSON insiste: o mais sai, os zeros à esquerda são reduzidos a um, uma parte inteira vazia vira 0, um ponto final solto é derrubado, e um menos é recolocado na frente. Um token que contém qualquer outro caractere, ou nenhum dígito, é formatado do seu valor parseado com dez casas decimais em vez disso, e essa rota grava null quando o valor não é finito

O GetObjectJSON do PDFlibPas lê o sinal, coleta dígitos em volta de um único ponto decimal e aplica só as edições que o JSON exige, enquanto qualquer outro caractere ou uma sequência vazia de dígitos cai no PLJSONNumber, que grava null para NaN e Infinity em vez de um número
Reescrever vence recalcular: o tokenizer já consertou .5 e 4. na entrada, então o escritor mantém todo dígito sobrevivente e a ida e volta recria exatamente o mesmo valor
  • -.25 vira -0.25, e +.5 vira 0.5
  • +1.5 vira 1.5
  • 007.5 vira 7.5, enquanto 0.75 fica como está
  • 4. vira 4 se tal token um dia chegar ao escritor
  • 2.22221 e 1.250000 mantêm todo dígito fracionário, zeros à direita incluídos

Formatar a partir do Double teria sido um one-liner, e teria estado errado de duas maneiras. A precisão de saída padrão do documento é de quatro casas decimais, então 2.22221 perderia um dígito. Aumentar a precisão também não o resgata: 0.1 não tem forma binária exata, e uma conversão de 17 dígitos significativos imprime 0.10000000000000001. Manter os dígitos originais significa que o SetObjectJSON e o ImportObjectJSON, que entregam cada número JSON de volta ao tokenizer do PDF, reconstruem exatamente o valor que o arquivo declarou

Essa promessa cobre o valor. Os bytes são outra história. Depois de uma reimportação, -.25 é guardado e salvo como -0.25; as duas grafias são iguais sob a §7.3.3, mas um diff no nível de bytes marca a mudança. Em um documento cujos intervalos de bytes estão cobertos por uma assinatura, não rodaríamos objetos por um ciclo de exportação e importação de forma alguma, a menos que o plano seja assinar de novo depois

O que null significa na saída do GetDocumentJSON?

O GetDocumentJSON grava null para qualquer número que seja NaN ou infinito, porque o RFC 8259 §6 não tem sintaxe para nenhum dos dois. Infinity é mais fácil de produzir do que parece. O tokenizer do PDF acumula dígitos por multiplicações repetidas em um Double, que satura perto de 1,8 × 10308, então um literal inteiro um pouco acima de 300 dígitos vira +Inf durante o parsing. Produtores comuns nunca gravam tal literal; arquivos fuzzados e hostis gravam, e é por isso que um inteiro de 400 dígitos pertence ao mesmo corpus de teste que os casos em endurecendo um parser PDF em Pascal contra arquivos maliciosos

A checagem de finitude tem que vir primeiro. O GetDocumentJSON imprime valores integrais abaixo de MaxInt como inteiros e todo o resto com o Str(D:0:6) do Pascal, que serve para 1.25 e é fatal para +Inf, porque o Str então grava o texto +Inf e nenhum consumidor JSON vai parsear isso. A formatação de seis decimais também marca para que serve o documento JSON. É uma visão geral do arquivo inteiro. Quando você precisa dos dígitos exatos de um objeto, peça o GetObjectJSON para aquele objeto

O null é deliberadamente lossy, e compartilha sua grafia com outra coisa. Um objeto null PDF também sai como null no documento JSON, então um consumidor não consegue distinguir "o arquivo disse null" de "o arquivo disse um número grande demais para um Double" olhando aquele valor. O GetObjectJSON os mantém separados: o objeto null do PDF é gravado como {"type":"null"}, e um número mantém seu embrulho "type":"number". Código que lê documento JSON deve aceitar null em qualquer lugar onde um número pode aparecer, registrar o número do objeto e tratar o arquivo como suspeito em vez de substituir por 0

Por que um único NaN pode abortar uma exportação SVG ou JSON?

Um formatador de números que escala sua entrada e chama Round esbarra em Round(NaN), e no Win32, onde o Delphi deixa a exceção de operação inválida do x87 sem máscara, isso lança EInvalidOp. A exceção dispara depois de o escritor já ter emitido parte de sua saída. Uma medição degenerada, um 0/0 dentro de uma métrica ou um NaN passado por um chamador deixa um arquivo truncado no disco

O PLDoubleToStr no PDFlibExtra, o formatador invariante que a biblioteca usa para content streams, SVG, XML, CSV e a maior parte de seu JSON, devolve 0 para NaN. Seu branch inteiro grampa o valor escalado em ±9,2 × 1018 exatamente como o branch fracionário, então Infinity também sai como um literal finito. Em um content stream essa é a decisão certa. Um slot de operando tem que segurar um número, e um visualizador que encontra +Inf no meio de um path não tem nada sensato para desenhar

Em um relatório, zero é a decisão errada, e temos opinião forte sobre essa: 0 é um ângulo de deskew ou erro de pixel perfeitamente plausível, então gravá-lo para "sem resposta" corrompe os dados sem ninguém notar. Escritores de relatório usam o PLJSONNumber(Value, Decimals) da mesma unit em vez dele, que grava null para NaN ou Infinity e dígitos invariantes caso contrário. GetSimilarImageDeduplicationReportJSON, GetAnnotationHitsJSON e os relatórios de barcode, deskew, structured text e PDF/VCR todos passam por ele, então um ângulo de deskew não finito chega ao consumidor como null

O PDFlibPas barra NaN e Infinity de três formas: AddPageMatrix, ScalePage e RedactRegion rejeitam argumentos não finitos de cara, o PLDoubleToStr grava 0 para slots de content stream, e o PLJSONNumber grava null em relatórios, onde zero leria como uma medição plausível, então o Round(NaN) nunca ganha a chance de lançar EInvalidOp no meio da exportação
Zero é a resposta certa para um content stream e a errada para um relatório, então os escritores de relatório entregam todo Double ao PLJSONNumber e deixam o null dizer que o valor estava presente mas não era representável

A mesma função é pública, então o seu JSON ao lado do da biblioteca pode seguir a mesma regra. O esboço abaixo constrói um registro pequeno de skew; a forma do registro é nossa, a chamada de formatação é da biblioteca

uses
  SysUtils, PDFlibTypes, PDFlibExtra;

// Seu próprio escritor de relatório, usando a regra de número da biblioteca
function SkewReportJSON(Page: Integer; Angle, Confidence: Double): string;
var
  B: PLStringBuilder;
begin
  B := PLStringBuilder.Create(128);
  try
    // Transforme todo Double em texto primeiro; o PLJSONNumber grava null
    // para NaN ou Infinity e sempre usa ponto 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): no Delphi essa sobrecarga segue o locale do usuário
    Result := B.ToString;
  finally
    B.Free;
  end;
end;

Onde o locale do usuário escapa para o JSON

Qualquer formatador que consulta configurações regionais pode pôr uma vírgula onde o JSON precisa de um ponto. O PLFloatToStr no PDFlibExtra é um wrapper fino sobre o FloatToStr, e é exatamente isso que ele faz. Escreva um campo como maxAcceptedMeanError com ele em um desktop alemão ou francês e você recebe "maxAcceptedMeanError":1,5. Um parser JSON lê isso como o valor 1 seguido de um token estranho. Aquele campo reporta o pior erro de pixel aceito da deduplicação perceptual de imagens, e o GetSimilarImageDeduplicationReportJSON o grava por meio de PLJSONNumber(Stats.MaxAcceptedMeanError, 6), então o separador continua um ponto seja lá o que a máquina estiver configurada

A segunda rota é mais silenciosa. No Delphi, o PLStringBuilder é um alias puro do System.SysUtils.TStringBuilder, cuja sobrecarga Append(Double) formata pelo locale do usuário. Builds em Free Pascal usam uma pequena classe construtora Unicode da PDFlibTypes em vez dela, porque o TStringBuilder do próprio runtime FPC é só-ANSI. Compile a mesma fonte com ambos e o build Delphi pode discordar do build FPC. Um teste que só roda no Free Pascal, ou só em uma máquina en-US, não vê a vírgula

O teste abaixo reproduz um desktop de vírgula dentro do processo e alimenta o relatório a um parser estrito. Escolha uma entrada que realmente contenha imagens quase duplicadas; sem correspondências o erro médio é 0, e um valor sem parte fracionária esconde o problema do separador

uses
  System.SysUtils, System.JSON, PDFlibrary;

var
  Lib: TPDFlib;
  Report: WideString;
  Parsed: TJSONValue;
begin
  // Faça este processo se comportar como um desktop alemão ou francês
  FormatSettings.DecimalSeparator := ',';
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('scanned-batch.pdf', '') = 0 then
      raise Exception.Create('load failed');
    // Dry run com limiares 2, 2, 4: o documento não é modificado
    Lib.GetSimilarImageDeduplicationReportJSON(2, 2, 4, Report);
    Parsed := TJSONObject.ParseJSONValue(Report);
    // Essa checagem de nil é sua para adicionar, não faz parte da biblioteca
    if Parsed = nil then
      raise Exception.Create('report is not valid JSON on a comma locale');
    Parsed.Free;
  finally
    Lib.Free;
  end;
end;

Três entradas que valem lugar na suíte de testes

Tratamento de números em JSON é barato de quebrar e barato de guardar. Uma página carregando -.25, +1.5 e 007.5 cobre a lacuna da gramática; cheque que a saída do GetObjectJSON parseia e que o SetObjectJSON devolve 1. Um objeto segurando um inteiro de 400 dígitos cobre overflow; o documento JSON deve mostrar null naquela posição. Um relatório produzido com DecimalSeparator definido como vírgula cobre o locale. Rode cada um por um parser estrito em vez de ler a saída a olho, porque 1,5 e 1.5 são fáceis de perder em uma linha longa de JSON

Object JSON, document JSON e os relatórios de análise compartilham essas regras de número entre builds Delphi, C++Builder e Free Pascal. A página do produto PDF Library for Delphi lista as edições e o resto da API de nível de objeto e de relatórios