Articolo tecnico

Il Round, Mod e Null di FormCalc non sono Round e mod Delphi

Un modulo fattura calcola una maggiorazione con Round(Subtotal * 0.025, 2), e un servizio Delphi che ricontrolla i totali è in disaccordo con il PDF dopo il flattening sulle righe da mezzo centesimo. FormCalc arrotonda la metà lontano da zero e restituisce un Double, mentre System.Round arrotonda la metà al pari, così il controllo affidabile è lasciare che HotPDF esegua il flattening del modulo XFA e i suoi script FormCalc

Metà lontano da zero, e il risultato resta un Double

La System.Round di Delphi segue la modalità di rounding della FPU, e la modalità predefinita arrotonda la metà al pari: Round(2.5) è 2, Round(3.5) è 4 e Round(-2.5) è -2. Il banker's rounding va bene per la statistica. Per un modulo che ha sempre mostrato 3 è un pessimo accordo. La Round di FormCalc porta la metà lontano da zero, quindi 2.5 diventa 3 e -2.5 diventa -3. Diverso è anche il tipo di ritorno. System.Round restituisce un Int64, ed è per questo che il familiare idioma Round(X * 100) / 100 va in overflow appena X * 100 esce dal range Int64, mentre la Round(X, 2) di FormCalc prende un Double e ne restituisce uno

Matrice di rounding per moduli XFA Delphi con HotPDF: il Round di FormCalc porta 2.5 a 3 lontano da zero mentre System.Round dà 2
FormCalc porta la metà lontano da zero e restituisce un Double, così 2.5 diventa 3 dove System.Round risponde 2

I valori grandi vogliono una regola in più. Un Double ha 52 bit di frazione espliciti, quindi una magnitudine di 252 (4.503.599.627.370.496) o più non ha più parte frazionaria da arrotondare. HotPDF scala il valore assoluto di 10places, e quando il valore scalato raggiunge 252 restituisce l'ingresso immutato — moltiplicare oltre non farebbe che inventare cifre o andare in overflow. La memorizzazione binaria fissa l'altro limite, e quello vale per qualunque valutatore basato su Double, FormCalc incluso. Il letterale 2.675 è memorizzato come 2.67499999999999982236431605997495353221893310546875. Arrotondato a due posti, dà 2.67. FormCalc non ha un tipo moneta decimale-esatto, quindi un modulo e una porta possono accordarsi solo sul valore binario che entrambi tengono

uses
  Math;

// Round in stile FormCalc per una porta Delphi: pari lontano da zero,
// numero di posti troncato verso zero e tenuto in 0..12, il risultato resta un 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);                         // nessuna cifra frazionaria rimasta da arrotondare
  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 places count as 2)
// FormCalcRound(1234.5, -2)     = 1235     (a negative count means 0 places)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) overflows Int64)

Quanti posti decimali accetta il Round di FormCalc?

Posti interi da 0 a 12. HotPDF tronca il secondo argomento verso zero e poi lo tiene in quel range, così Round(X, 2.7) arrotonda a due posti, Round(X, 15) a dodici, e sia Round(X, -2) sia Round(X, -0.5) a un numero intero. La regola è la stessa ovunque HotPDF valuti FormCalc, quindi un totale calcolato durante il flattening e uno calcolato mentre il modulo viene compilato escono identici. Le abitudini da foglio di calcolo tirano dall'altra parte. La ROUND(1234.5, -2) di Excel dà 1200 perché Excel legge un conteggio negativo come cifre a sinistra della virgola; FormCalc dà 1235. Gli helper Delphi capovolgono la convenzione ancora una volta: Math.RoundTo e SimpleRoundTo prendono una potenza di dieci, quindi RoundTo(X, -2) significa due decimali e RoundTo(1234.567, 2) è 1200. Una porta che copia il secondo argomento dello script direttamente in RoundTo stampa centinaia dove il modulo mostra centesimi. Tenete il conteggio dei posti come lo definisce FormCalc e fatelo passare da un helper come FormCalcRound, che tiene giusta anche la regola del pareggio

Perché a - b * Int(a / b) restituisce il resto sbagliato?

Perché il quoziente smette di essere esatto molto prima del dividendo. Prendete Mod(1E20, 7). Il dividendo è rappresentabile senza errore — 1020 è 220 × 520, e 520 sta in 53 bit — e il resto vero è 2. Il quoziente, circa 1.43 × 1019, no: i Double in quel range stanno a 2.048 di distanza, così Int(a / b) è sbagliato prima ancora che la moltiplicazione parta, e a - b * q restituisce quel che gli errori di rounding lasciano dietro. L'operatore mod di Delphi lavora solo su interi, e Trunc non può tenere un quoziente oltre il range Int64. Controllate System.Math.FMod prima di appoggiarvi qui. Un'implementazione che deriva il resto dal quoziente eredita lo stesso errore, e confrontare FMod(1E20, 7) con il 2 atteso decide la questione in una riga

La divisione lunga binaria non forma mai il quoziente. Raddoppiate il divisore finché supera metà del dividendo, poi tornate giù, sottraendo il divisore scalato ovunque ci stia. Ogni divisore scalato è l'originale per una potenza di due, quindi non porta alcun errore di rounding. Ogni sottrazione toglie un numero tra metà e la totalità del resto corrente — il caso in cui, per il lemma di Sterbenz, la sottrazione IEEE 754 non coinvolge rounding. Il risultato è esatto. Vale poi la regola del segno di FormCalc: il resto prende il segno del dividendo, così Mod(-7, 3) è -1 e Mod(7, -3) è 1. Un dividendo di magnitudine minore del divisore torna immutato, e un divisore zero non produce alcun numero

Mod di FormCalc in Delphi con HotPDF: la formula del quoziente fallisce a 1E20 mentre la divisione lunga binaria raddoppia il divisore e sottrae in modo esatto
Il quoziente vicino a 1.43E19 sta già su una griglia Double grossolana, mentre la divisione lunga binaria raggiunge il resto esatto senza formare un quoziente
// Resto floating-point esatto, segno del dividendo, nessun quoziente necessario
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;                   // il più grande multiplo potenza di due
  while Step > Divisor do
  begin
    if Result >= Step then
      Result := Result - Step;          // esatto: 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 tronca il suo indice, HasValue ignora gli spazi

Choose(n, item1, item2, …) converte il suo primo argomento in numero e lo tronca, così Choose(2.7, "a", "b", "c") restituisce "b" senza alzare alcun errore di tipo. Un indice sotto 1 o oltre l'ultimo elemento restituisce una stringa vuota, e un indice null restituisce null. HasValue è la forma funzione che gli autori usano per testare i campi opzionali: risponde 0 per null e per testo fatto solo di white space Unicode. Il numero 0 conta ancora. Un campo quantità che contiene 0 è stato compilato; una casella commenti che contiene tre spazi no, anche se gli XFA white-space text values tengono quegli spazi intatti attraverso un salvataggio. Insieme le due funzioni danno la solita guardia per le voci opzionali, if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif, che lascia vuota una riga non compilata e tiene il totale di colonna limitato a ciò che è stato inserito. Una porta Delphi che tratta una quantità vuota come 0 stampa una riga totale di 0.00 dove il modulo non stampa nulla

Cosa restituisce FormCalc per un campo vuoto?

Null — e null sopravvive alla maggior parte delle funzioni che uno script calculate chiama. In FormCalc una stringa vuota è un valore vero e null è la sua assenza, e le funzioni stringa tengono i due separati:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim e Space restituiscono null quando il loro argomento è null
  • Left, Right, At e Replace controllano i loro primi due argomenti, Stuff i primi tre, e Substr ogni argomento fornito
  • Una stringa vuota passata a qualunque di loro viene elaborata come testo: Upper("") è "", non null
  • Gli script possono produrre null esplicitamente con il letterale null oppure Null()

Le stringhe Delphi non hanno null, ed è lì che le porte scritte a mano deviano di più. Concat sta fuori dalla lista: salta gli argomenti null, così Concat(Prefix, Code) su un prefisso non compilato produce lo stesso testo che una porta costruisce da ''. Len no. Len(Prefix) è null e un campo numerico legato a lei resta vuoto, mentre Length('') ci mette 0. Gli aggregati seguono la regola del salto: Sum, Avg, Count, Min e Max ignorano le voci vuote, così Avg su 10, una riga vuota e 20 è 15 e Count è 2. Una porta che legge la riga vuota come 0 riporta una media di 10. Una colonna senza nulla di inserito non dà a Sum alcun valore, il che tiene vuoto il campo del totale generale

Mappa di propagazione null per FormCalc in Delphi con HotPDF: le funzioni stringa restituiscono null, gli aggregati saltano le voci vuote, e HasValue tratta il testo di spazi come non compilato
Null continua a muoversi attraverso Len e gli aggregati mentre Concat e Sum lo saltano, così una porta deve modellare i campi come Variant invece di collassare null in una stringa vuota
uses
  Variants;

// Avg in stile FormCalc: le voci vuote si saltano, non contano come 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     leggere la voce vuota come 0 dà 10
// FormCalcAvg([Null, Null])   = Null   il campo della media resta vuoto

Modellate i campi come Variant nella porta e tenete Null separato da ''. I valori tirati da un dataset vogliono la stessa cura: TField.Value restituisce Null per una colonna NULL, mentre TField.AsString la trasforma in una stringa vuota e cancella la differenza prima ancora che la porta la veda

Lasciate che il modulo esegua i suoi script

La porta più sicura è spesso nessuna porta. THotPDF.FlattenLoadedXFA valuta lo script calculate di ogni campo mentre dispone il modulo e ricostruisce i campi come campi AcroForm, applicando le regole di rounding, resto e null viste sopra. La stessa chiamata gestisce il resto del flatten da XFA ad AcroForm, dal layout alla mappatura dei widget. Una formula che non si può valutare — un riferimento irrisolto, una divisione per zero, un errore di parsing — fallisce nel suo complesso. Nulla di calcolato a metà raggiunge il campo. Ricaricare il file dopo il flattening e confrontare i valori dei suoi campi con l'output della porta trasforma un disaccordo vago in una lista di nomi di 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;      // '' contro '0.00' è una discrepanza vera
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 = i campi diventano read-only
    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;

Leggete gli avvisi prima di fidarvi di qualunque totale; la lista nomina ogni elemento che la conversione non è riuscita a mappare, quindi cercate le voci che nominano un campo calcolato. Poi date alla porta un campione costruito per le regole viste sopra: importi di riga che cadono su .5 al secondo decimale, un numero di conto di 20 cifre passato per Mod, una Round con un conteggio di posti frazionario, e una riga opzionale lasciata vuota. Ogni riga che la procedura stampa è una regola che la porta sbaglia. I moduli che calcolano con gli script format e calculate AcroForm seguono le regole numeriche JavaScript — Math.round(-2.5) è -2 lì, una terza risposta alla stessa domanda

Se la cifra che il vostro servizio vuole è una che il modulo stampa già, prendetela dal modulo: fate girare il flattening con il componente PDF HotPDF per Delphi, ricaricate il risultato e leggete il campo. Le funzioni helper viste sopra si guadagnano il posto solo per i numeri che il modulo non calcola mai