Troque uma caixa de teste Windows para as configurações regionais alemãs, rode uma rotina que antepõe uma matriz de escala e deslocamento a uma página e despeje o content stream. Em vez de 0.5 0 0 0.25 0.00001 12.75 cm você recebe 0,5 0 0 0,25 1E-5 12,75 cm. Um parser de conteúdo lê aquilo como o número 0, depois um token ,5 que ele não reconhece, e depois mais números que não se alinham mais com os seis operandos que o cm espera, e a página desenha com uma transformação que você nunca pediu. Números que uma máquina vai interpretar precisam de ponto fixo, sem expoente e sem nenhuma dependência de FormatSettings, do lado da escrita e do lado da leitura
Por que um locale com vírgula decimal quebra números de PDF?
Um locale com vírgula decimal quebra números de PDF porque a formatação de float padrão do Delphi segue o desktop, enquanto a sintaxe de número do PDF é fixa. O FloatToStr usa FormatSettings.DecimalSeparator, então em uma máquina de-DE, fr-FR ou pt-BR toda fração sai com vírgula. A ISO 32000-1 §7.3.3 permite dígitos, um ponto e um sinal inicial em um número. Nada mais. A vírgula portanto divide um número em um inteiro válido mais lixo, e o resultado é uma página que renderiza, só que errada
Há uma segunda pegadinha atrás da primeira, e ela morde em máquinas dos EUA também. O FloatToStr usa o formato ffGeneral, que troca para notação de expoente assim que a magnitude cai abaixo de 1E-4, então um offset minúsculo é gravado como 1E-5. A mesma §7.3.3 diz que o PDF não suporta a forma de expoente. Rastrear qualquer um dos problemas de trás para frente a partir da saída renderizada é miserável, porque uma matriz derivada parece exatamente com um bug de layout no seu próprio código, e nada na página aponta para as configurações regionais
O PDFlibPas, a losLab PDF Developer Library para Delphi, grava os operandos do AddPageMatrix por meio do PLDoubleToStrConst com seis casas decimais, e os pontos de chamada que geram conteúdo de página em seu nome seguem a mesma regra. O teste de regressão mais barato que conhecemos vira o separador para vírgula dentro do processo, chama a API e varre o resultado por vírgulas e expoentes:
uses
System.SysUtils, PDFlibrary;
// Verificação sua, não faz parte da biblioteca. É grosseira de propósito:
// strings de texto como (Hello, world) Tj também contêm vírgulas, então rode-a
// em uma página de teste que só desenha 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 := ','; // aja como um desktop 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 teria produzido: 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;
Trocar o FormatSettings.DecimalSeparator dentro do processo é um atalho. Ele não exercita código que monta seu próprio TFormatSettings a partir do SO, então se a sua aplicação faz isso, um agente de CI com configurações regionais alemãs de verdade é o teste mais honesto
Dois tipos de números, duas famílias de helpers
O PDFlibPas divide seus helpers de número por público: texto mostrado a pessoas pode seguir o locale, e qualquer coisa escrita para uma máquina nunca segue. O PLFloatToStr e o PLStrToFloat em PDFlibExtra.pas são wrappers finos sobre FloatToStr e StrToFloat, e o comentário na declaração deles diz que são apenas para texto legível por humanos. Saída de máquina (PDF, FDF, XFDF, JSON, XML, CSV) passa pela família invariante em vez disso: PLDoubleToStrConst para escrita, PLTryStrToFloatInvariant para leitura, e PLInvariantFormatSettings quando você precisa de um record TFormatSettings com decimal de ponto para suas próprias chamadas TryStrToFloat
A precisão é escolhida por trabalho em vez de globalmente. Matrizes ganham seis decimais, coordenadas e ajustes de TJ ganham quatro, cores e retângulos de FDF ganham três. O lado voltado à máquina cobre mais lugares do que a superfície da API sugere:
AddPageMatrix,ScalePageeDeskewPage, que todos antepõem umcmao conteúdo existente da página- Os resets de
Tm, avanços deTJe transformações decmgravados quando elementos de página são gerados - Matrizes de posicionamento de glifo e pontos de outline produzidos quando texto é convertido em paths
- A caixa de preenchimento preta que o
RedactRegionantepõe, os valores de/Rectno export de FDF e os operandos de cor que o recolor grava
O PLDoubleToStrConst é um formatador feito à mão, e achamos que essa foi a decisão certa em vez de embrulhar o FloatToStrF com um TFormatSettings fixo. O ffFixed ainda cai em notação científica assim que a parte inteira ultrapassa a precisão, e deixaria 0.500000 onde 0.5 é mais curto e idêntico. A rotina personalizada sempre grava um ponto, remove zeros à direita e nunca grava expoente para entrada finita. Ela também mantém os dígitos significativos de um valor não zero menor que a precisão pedida: PLDoubleToStrConst(1E-9, 6) retorna 0.000000001, e apenas valores abaixo de cerca de 5E-16 viram 0. Arredondar um fator de escala minúsculo para zero transformaria uma matriz válida em uma singular, o que é uma falha pior que qualquer decimal fora do lugar
Se você escreve testes de unit contra o formatador, escolha seus valores de exemplo com ponto flutuante binário em mente. A escolha óbvia para "quatro dígitos significativos" é 0.000012345, mas multiplicado por 1E8 esse double é 1234.4999…, então o resultado é 0.00001234 e a asserção falha por um motivo sem relação com locales. Um valor que fica claramente longe do ponto médio, como 0.000012346, evita a discussão inteira:
uses
PDFlibExtra;
// As chamadas Assert são checagens que você acrescenta no seu próprio projeto de testes
procedure CheckNumberHelpers;
var
V: Double;
begin
// Saída de máquina: decimal ponto, sem expoente, zeros à direita removidos
Assert(PLDoubleToStrConst(1E-5, 6) = '0.00001');
Assert(PLDoubleToStrConst(-0.5, 6) = '-0.5');
Assert(PLDoubleToStrConst(0.000012346, 4) = '0.00001235'); // 4 dígitos significativos mantidos
Assert(PLDoubleToStrConst(12345.25, 4) = '12345.25');
// Entrada de máquina: False em vez de EConvertError
Assert(PLTryStrToFloatInvariant('0.5', V) and (V = 0.5));
Assert(PLTryStrToFloatInvariant(' 12.75 ', V) and (V = 12.75)); // a entrada é aparada
Assert(not PLTryStrToFloatInvariant('0,5', V)); // números de conteúdo nunca usam vírgula
end;
Por que o lado de leitura é mais perigoso que o lado de escrita?
O lado da interpretação é mais perigoso porque um parser preso ao locale não produz um número um pouco errado; ele levanta exceção. O StrToFloat lança EConvertError sempre que o texto não bate com o separador do sistema. Uma passada de recoloring construída sobre ele abortaria no momento em que chegasse a um operador 0.5 g comum em uma máquina com vírgula decimal, o que significa que falha em praticamente toda página real. Uma string de clip como "10.5,20.5,50.5,40.5" seria rejeitada de cara, e comprimentos SVG, cores SVG, listas de vértices de anotações e valores de output intent ou seriam recusados ou silenciosamente trocados por padrões. Esse é código que passa em todo teste na máquina do desenvolvedor e falha para o primeiro cliente em Munique, a mesma família de problema que os casos em o artigo sobre código Delphi que funciona por acidente
Toda chamada estilo StrToFloat na biblioteca é classificada pela origem da entrada. Operandos de content stream, atributos SVG, strings de cor do painter e listas de clip e vértices separadas por vírgula têm sintaxe de ponto fixa, então passam pelo PLTryStrToFloatInvariant. Esse helper apara o texto, interpreta com PLInvariantFormatSettings e devolve False (com o valor definido como 0) para entrada vazia, malformada, NaN ou infinita. Listas separadas por vírgula não precisaram de debate nenhum: uma vírgula não pode ser ao mesmo tempo o delimitador de lista e a marca decimal, então não existe forma legada com que manter compatibilidade
Para a pipeline de recoloring descrita em o guia de conversão de um PDF para um único color space, o resultado é que RecolorPage e RecolorDocument interpretam o conteúdo de página de forma idêntica em qualquer locale. Valores de regra que um chamador digita no CheckDocumentPolicy são o único caso de interpretação que segue o caminho leniente, porque uma pessoa digitou aquela string e pode muito bem ter usado a marca decimal local
Um número retransmitido por uma string precisa que as duas pontas concordem
Quando um número é gravado em uma string por uma parte do código e interpretado de volta por outra, o escritor e o leitor precisam seguir a mesma convenção, e mudar só um deles quebra o round trip. Atributos de estrutura de PDF marcado funcionam exatamente assim. O SetStructElemBBox formata quatro valores em uma string e a guarda por meio do AddTagAttribute. Quando o dicionário de atributos /A é gravado, essa string é interpretada de novo para decidir se vira um número, um array ou um name
Se as duas pontas seguissem o locale do sistema, a viagem seria autoconsistente em uma máquina alemã. O problema começa com um chamador que segue a documentação e passa "0.5" ao AddTagAttribute: um leitor preso ao locale não consegue interpretá-la e emite o name PDF /0.5. Os placeholders de PDF/VCR sofrem a imagem espelhada, já que o GTS_BBox deles é gerado com ponto, e um passo de validação preso ao locale antes de salvar o rejeitaria. E trocar só o escritor para ponto piora as coisas, porque todo valor de SetStructElem* viraria um name em sistemas com vírgula decimal
Por isso os escritores usam PLDoubleToStrConst(v, 6) e o leitor usa PLTryStrToFloatLenient, que tenta a forma de ponto primeiro e cai para o locale do sistema. Um chamador com locale de vírgula que passa "1,25" recebe o número 1.25. Há um custo, e o aceitamos de olhos abertos: em um sistema alemão "1.500" é lido como 1.5 em vez de mil e quinhentos, porque a forma de ponto vence. A API documenta o ponto como separador, então um agrupamento de milhar à moda alemã em uma string de atributo é a entrada que escolhemos abandonar. Strings literais NAN e INF não são tratadas como números
uses
System.SysUtils, PDFlibrary;
var
Lib: TPDFlib;
begin
FormatSettings.DecimalSeparator := ','; // chamador com vírgula decimal
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 em vez de /0.5
Lib.AddTagAttribute('Layout', 'StartIndent', '1,25'); // /StartIndent 1.25 via o fallback de locale
Lib.DrawText(20, 20, 'figure');
Lib.EndTag;
Lib.SaveToFile('tagged.pdf');
finally
Lib.Free;
end;
end;
Nossa recomendação para o seu próprio código é passar strings com decimal de ponto ao AddTagAttribute e deixar o fallback de vírgula para valores que você não controla, como strings carregadas de um arquivo de configuração antigo. Como a árvore de estrutura ao redor desses atributos é construída está coberto no guia de estrutura de PDF marcado
Onde NaN e infinito são barrados
O AddPageMatrix, o ScalePage e o RedactRegion rejeitam argumentos NaN e infinitos de cara e retornam 0, já que nenhum número de PDF representa qualquer um dos dois. A checagem precisa ser explícita. NaN escapa de um teste <= 0, então uma verificação de faixa em um fator de escala sozinho deixaria um NaN de escala viajar até o formatador, e chamar Round sobre NaN levanta EInvalidOp no Win32, onde a unidade x87 não mascara operações inválidas por padrão. O PLDoubleToStrConst grava 0 para NaN como última linha de defesa, mas um zero dentro de uma matriz é uma transformação singular, então a checagem no nível da API é a que de fato protege a página. No seu próprio código, teste o valor de retorno: quando o ScalePage retorna 0 para um fator que você calculou, imprima o fator antes de qualquer outra coisa, porque um 0/0 em algum lugar a montante produz exatamente esse NaN
Duas fronteiras são deliberadas. Strings de estado de metafile são gravadas e lidas com o locale dentro de um único processo e nunca chegam a um arquivo, então continuam presas ao locale. E se você testa valores pequenos pelo caminho de geração de página, leia o conteúdo logo depois da chamada: uma operação que reemite o conteúdo da página depois, na precisão de coordenadas do documento, legitimamente transforma 1E-5 em 0, e isso é arredondamento, não vazamento de locale
O hábito que vale adotar é curto. Rode os caminhos que produzem PDF na sua aplicação uma vez com separador vírgula, varra a saída por vírgulas e expoentes, e mantenha o FloatToStr longe de tudo que um parser vai ler. Números lidos de um arquivo existente seguem uma regra relacionada, coberta no artigo sobre preservar precisão decimal interpretada, em que o texto de origem exato sobrevive a um save. Builds de teste, a referência de API e detalhes de licenciamento estão na página de produto da PDFlibPas Delphi PDF library