Artigo Técnico

FormCalc Round, Mod e Null não são o Round e o mod de Delphi

Um formulário de fatura calcula uma sobretaxa com Round(Subtotal * 0.025, 2), e um serviço Delphi que reconfere os totais discorda do PDF achatado nas linhas de meio centavo. FormCalc arredonda metades para longe do zero e retorna um Double, enquanto o System.Round arredonda para o par, então a checagem confiável é deixar o HotPDF achatar o formulário XFA e rodar os scripts FormCalc dele

Metades para longe do zero, e o resultado segue sendo Double

O System.Round do Delphi segue o modo de arredondamento da FPU, e o modo padrão arredonda metades para o par: Round(2.5) é 2, Round(3.5) é 4 e Round(-2.5) é -2. O arredondamento de banqueiro serve para estatística. É um casamento ruim para um formulário que sempre mostrou 3. O Round do FormCalc leva as metades para longe do zero, então 2.5 vira 3 e -2.5 vira -3. O tipo de retorno também difere. O System.Round retorna um Int64, e é por isso que o idiom familiar Round(X * 100) / 100 estoura quando X * 100 sai da faixa do Int64, enquanto o Round(X, 2) do FormCalc recebe um Double e devolve um

Matriz de arredondamento para formulários XFA em Delphi com HotPDF: o Round do FormCalc leva 2.5 para 3, longe do zero, enquanto o System.Round dá 2
o FormCalc leva metades empatadas para longe do zero e retorna um Double, então 2.5 vira 3 onde o System.Round responde 2

Valores grandes precisam de mais uma regra. Um Double tem 52 bits explícitos de fração, então uma magnitude de 252 (4.503.599.627.370.496) ou mais não sobra parte fracionária para arredondar. O HotPDF escala o valor absoluto por 10places, e quando o valor escalado chega a 252 ele devolve a entrada sem mudança — multiplicar mais só inventaria dígitos ou estouraria. O armazenamento binário fixa o outro limite, e esse vale para qualquer avaliador baseado em Double, FormCalc incluído. O literal 2.675 é armazenado como 2.67499999999999982236431605997495353221893310546875. Arredondado a duas casas, dá 2.67. FormCalc não tem tipo monetário exato em decimal, então um formulário e um port só podem concordar sobre o valor binário que ambos carregam

uses
  Math;

// Round estilo FormCalc para um port Delphi: metades para longe do zero,
// contagem de casas truncada para zero e mantida em 0..12, resultado segue Double
function FormCalcRound(Value: Double; Places: Double = 0): Double;
const
  NoFractionBits = 4503599627370496.0;   // 2^52
var
  Digits: Integer;
  Scale, Scaled, Whole: Double;
begin
  if IsNan(Value) or IsNan(Places) then
    Exit(NaN);
  if IsInfinite(Value) or (Value = 0) then
    Exit(Value);
  Digits := Trunc(EnsureRange(Places, 0.0, 12.0));
  Scale := IntPower(10, Digits);
  if Abs(Value) >= NoFractionBits / Scale then
    Exit(Value);                         // não sobra dígito fracionário para arredondar
  Scaled := Abs(Value) * Scale;
  Whole := Int(Scaled);
  if Scaled - Whole >= 0.5 then
    Whole := Whole + 1;
  Result := Whole / Scale;
  if Value < 0 then
    Result := -Result;
end;

// FormCalcRound(2.5)            = 3        System.Round(2.5)  = 2
// FormCalcRound(-2.5)           = -3       System.Round(-2.5) = -2
// FormCalcRound(1234.567, 2.7)  = 1234.57  (2.7 casas contam como 2)
// FormCalcRound(1234.5, -2)     = 1235     (contagem negativa significa 0 casas)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) estoura o Int64)

Quantas casas decimais o Round do FormCalc aceita?

Casas inteiras de 0 a 12. O HotPDF trunca o segundo argumento para zero e depois o mantém nessa faixa, então Round(X, 2.7) arredonda a duas casas, Round(X, 15) a doze, e tanto Round(X, -2) quanto Round(X, -0.5) a um número inteiro. A regra é a mesma onde quer que o HotPDF avalie FormCalc, então um total calculado durante o achatamento e um calculado enquanto o formulário é preenchido saem idênticos. O hábito de planilha puxa para o outro lado. O ROUND(1234.5, -2) do Excel dá 1200 porque o Excel lê uma contagem negativa como dígitos à esquerda da vírgula decimal; o FormCalc dá 1235. Os helpers do Delphi invertem a convenção mais uma vez: Math.RoundTo e SimpleRoundTo recebem uma potência de dez, então RoundTo(X, -2) significa duas decimais e RoundTo(1234.567, 2) é 1200. Um port que copia o segundo argumento do script direto para o RoundTo imprime centenas onde o formulário mostra centavos. Mantenha a contagem de casas como o FormCalc a define e encaminhe por um helper como o FormCalcRound, que também mantém a regra do empate certa

Por que a - b * Int(a / b) devolve o resto errado?

Porque o quociente para de ser exato muito antes que o dividendo. Tome Mod(1E20, 7). O dividendo é representável sem erro — 1020 é 220 × 520, e 520 cabe em 53 bits — e o resto verdadeiro é 2. O quociente, cerca de 1,43 × 1019, não é: Doubles nessa faixa ficam a 2.048 de distância um do outro, então o Int(a / b) está errado antes de a multiplicação começar, e o a - b * q devolve o que os erros de arredondamento deixarem. O operador mod do Delphi funciona só sobre inteiros, e o Trunc não segura um quociente além da faixa do Int64. Confira o System.Math.FMod antes de se apoiar nele aqui. Uma implementação que deriva o resto do quociente herda o mesmo erro, e comparar o FMod(1E20, 7) com o 2 esperado resolve a questão numa linha

A divisão longa binária nunca forma o quociente. Duplique o divisor até passar da metade do dividendo, depois desça de volta, subtraindo o divisor escalado onde couber. Todo divisor escalado é o original vezes uma potência de dois, então não carrega erro de arredondamento. Toda subtração tira um número entre metade e todo o resto atual — o caso em que, pelo lema de Sterbenz, a subtração IEEE 754 não envolve arredondamento. O resultado é exato. A regra de sinal do FormCalc se aplica depois: o resto toma o sinal do dividendo, então Mod(-7, 3) é -1 e Mod(7, -3) é 1. Um dividendo menor em magnitude que o divisor volta sem mudança, e um divisor zero não produz número algum

Mod do FormCalc em Delphi com HotPDF: a fórmula do quociente falha em 1E20 enquanto a divisão longa binária dobra o divisor e subtrai exatamente
o quociente perto de 1.43E19 já assenta numa grade Double grosseira, enquanto a divisão longa binária chega ao resto exato sem formar um quociente
// Resto de ponto flutuante exato, sinal do dividendo, sem precisar de quociente
function FormCalcMod(Dividend, Divisor: Double): Double;
var
  Step, Half: Double;
begin
  if IsNan(Dividend) or IsNan(Divisor) or IsInfinite(Dividend) or (Divisor = 0) then
    Exit(NaN);
  if IsInfinite(Divisor) or (Abs(Dividend) < Abs(Divisor)) then
    Exit(Dividend);
  Divisor := Abs(Divisor);
  Result := Abs(Dividend);
  Half := Result * 0.5;
  Step := Divisor;
  while Step <= Half do
    Step := Step * 2;                   // maior múltiplo potência de dois
  while Step > Divisor do
  begin
    if Result >= Step then
      Result := Result - Step;          // exato: Step <= Result < 2 * Step
    Step := Step * 0.5;
  end;
  if Result >= Divisor then
    Result := Result - Divisor;
  if Dividend < 0 then
    Result := -Result;
end;

// FormCalcMod(1E20, 7) = 2      FormCalcMod(-7, 3) = -1
// FormCalcMod(7, -3)   = 1      FormCalcMod(7.5, 2) = 1.5
// FormCalcMod(1, 0)    = NaN

Choose trunca o índice, HasValue ignora brancos

O Choose(n, item1, item2, …) converte o primeiro argumento em número e o trunca, então Choose(2.7, "a", "b", "c") retorna "b" e não levanta erro de tipo. Um índice abaixo de 1 ou além do último item retorna uma string vazia, e um índice nulo retorna null. O HasValue é a forma funcional que os autores usam para testar campos opcionais: responde 0 para null e para texto feito só de white space Unicode. O número 0 ainda conta. Um campo de quantidade com 0 foi preenchido; uma caixa de comentários com três espaços não, mesmo que os valores de texto white-space do XFA mantenham esses espaços intactos num save. Juntas, as duas funções dão a guarda usual para itens de linha opcionais, if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif, que deixa uma linha não preenchida vazia e mantém o total da coluna limitado ao que foi digitado. Um port Delphi que trata quantidade vazia como 0 imprime um total de linha 0.00 onde o formulário não imprime nada

O que o FormCalc retorna para um campo vazio?

Null — e o null sobrevive à maioria das funções que um script calculate chama. No FormCalc uma string vazia é um valor real e null é a ausência dela, e as funções de string mantêm os dois separados:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim e Space retornam null quando o argumento é null
  • Left, Right, At e Replace checam os dois primeiros argumentos, Stuff os três primeiros, e Substr todo argumento fornecido
  • Uma string vazia passada a qualquer uma delas é processada como texto: Upper("") é "", não null
  • Scripts podem produzir null explicitamente com o literal null ou Null()

Strings Delphi não têm null, e é aí que ports escritos à mão mais derivam. O Concat fica fora da lista: ele pula argumentos null, então o Concat(Prefix, Code) sobre um prefixo não preenchido produz o mesmo texto que um port constrói com ''. O Len não. O Len(Prefix) é null e um campo numérico ligado a ele fica em branco, enquanto o Length('') põe 0 ali. Os agregados seguem a regra de pular: Sum, Avg, Count, Min e Max ignoram entradas vazias, então o Avg sobre 10, uma linha vazia e 20 é 15 e o Count é 2. Um port que lê a linha vazia como 0 informa média de 10. Uma coluna sem nada digitado não dá valor nenhum ao Sum, o que mantém o campo de total geral em branco

Mapa de propagação de null para FormCalc em Delphi com HotPDF: funções de string retornam null, agregados pulam entradas vazias, e HasValue trata texto de white space como não preenchido
o null segue se movendo por Len e os agregados enquanto Concat e Sum o pulam, então um port precisa modelar campos como Variant em vez de colapsar null para string vazia
uses
  Variants;

// Avg estilo FormCalc: entradas vazias são puladas, não contadas como zero
function FormCalcAvg(const Values: array of Variant): Variant;
var
  I, Count: Integer;
  Total: Double;
begin
  Result := Null;
  Total := 0;
  Count := 0;
  for I := Low(Values) to High(Values) do
    if not VarIsNull(Values[I]) then
    begin
      Total := Total + Values[I];
      Inc(Count);
    end;
  if Count > 0 then
    Result := Total / Count;
end;

// FormCalcAvg([10, Null, 20]) = 15     ler a entrada vazia como 0 dá 10
// FormCalcAvg([Null, Null])   = Null   o campo de média fica em branco

Modele os campos como Variant no port e mantenha o Null apartado do ''. Valores puxados de um dataset pedem o mesmo cuidado: o TField.Value retorna Null para uma coluna NULL, enquanto o TField.AsString a transforma em string vazia e apaga a diferença antes de o port ver

Deixe o formulário rodar os próprios scripts

O port mais seguro costuma ser nenhum port. O THotPDF.FlattenLoadedXFA avalia o script calculate de cada campo enquanto dispõe o formulário e reconstrói os campos como campos AcroForm, aplicando as regras de arredondamento, resto e null acima. A mesma chamada cuida do resto do achatamento de XFA para AcroForm, do layout ao mapeamento de widgets. Uma fórmula que não pode ser avaliada — uma referência não resolvida, uma divisão por zero, um erro de parse — falha como um todo. Nada semi-calculado chega ao campo. Recarregar o arquivo achatado e comparar os valores de campo com a saída do port transforma uma discordância vaga numa lista de nomes de campo:

uses
  SysUtils, Classes, HPDFDoc;

function SameFieldValue(const FormText, PortText: string): Boolean;
var
  FS: TFormatSettings;
  A, B: Double;
begin
  FS := TFormatSettings.Create;
  FS.DecimalSeparator := '.';
  if TryStrToFloat(FormText, A, FS) and TryStrToFloat(PortText, B, FS) then
    Result := A = B
  else
    Result := FormText = PortText;      // '' contra '0.00' é uma discrepância real
end;

procedure CheckPortAgainstForm(const XfaFile, FlatFile: string; Port: TStrings);
var
  Pdf: THotPDF;
  Pairs: TStringList;
  I: Integer;
  FieldName: string;
begin
  Pdf := THotPDF.Create(nil);
  try
    if Pdf.LoadFromFile(XfaFile) <= 0 then
      raise Exception.Create('Cannot open the XFA form');
    Pdf.FlattenLoadedXFA(False);        // False = campos viram somente leitura
    for I := 0 to Pdf.XFAFlattenWarnings.Count - 1 do
      Writeln('XFA: ', Pdf.XFAFlattenWarnings[I]);
    Pdf.SaveLoadedDocument(FlatFile);
  finally
    Pdf.Free;
  end;

  Pdf := THotPDF.Create(nil);
  Pairs := TStringList.Create;
  try
    if Pdf.LoadFromFile(FlatFile) <= 0 then
      raise Exception.Create('Cannot open the flattened PDF');
    Pdf.GetLoadedFormFieldNameValuePairs(Pairs);
    for I := 0 to Pairs.Count - 1 do
    begin
      FieldName := Pairs.Names[I];
      if (Port.IndexOfName(FieldName) >= 0) and
         not SameFieldValue(Pairs.ValueFromIndex[I], Port.Values[FieldName]) then
        Writeln(Format('%s: form "%s", port "%s"',
          [FieldName, Pairs.ValueFromIndex[I], Port.Values[FieldName]]));
    end;
  finally
    Pairs.Free;
    Pdf.Free;
  end;
end;

Leia os avisos antes de confiar em qualquer total; a lista nomeia todo elemento que a conversão não conseguiu mapear, então procure entradas que nomeiem um campo calculado. Depois dê ao port uma amostra construída para as regras acima: valores de linha que caem em .5 na segunda decimal, um número de conta de 20 dígitos passado pelo Mod, um Round com contagem de casas fracionária, e uma linha opcional deixada vazia. Cada linha que o procedimento imprime é uma regra que o port erra. Formulários que calculam com scripts format e calculate AcroForm seguem as regras de número do JavaScript — Math.round(-2.5) é -2 lá, uma terceira resposta para a mesma pergunta

Se o número que o seu serviço precisa é um que o formulário já imprime, tire-o do formulário: achate-o com o componente PDF HotPDF para Delphi, recarregue o resultado e leia o campo. As funções helper acima se pagam só para números que o formulário nunca calcula