Technischer Artikel

FormCalc Round, Mod, Null sind nicht Delphi Round und mod

Ein Rechnungsformular berechnet einen Aufschlag mit Round(Subtotal * 0.025, 2), und ein Delphi-Dienst, der die Summen nachprüft, widerspricht dem flachgedrückten PDF bei Halb-Cent-Positionen. FormCalc rundet Halben von null weg und gibt ein Double zurück, während System.Round zur geraden Zahl rundet, also ist die verlässliche Prüfung, HotPDF das XFA-Formular flachlegen und seine FormCalc-Skripte ausführen zu lassen

Halben von null weg, und das Ergebnis bleibt ein Double

Delphis System.Round folgt dem FPU-Rundungsmodus, und der Default-Modus rundet Halben auf gerade: Round(2.5) ist 2, Round(3.5) ist 4 und Round(-2.5) ist -2. Banker's Rounding passt für Statistik. Für ein Formular, das immer 3 gezeigt hat, ist es ein schlechter Deal. FormCals Round nimmt Halben von null weg, also wird aus 2.5 eine 3 und aus -2.5 eine -3. Auch der Rückgabetyp unterscheidet sich. System.Round liefert ein Int64, weshalb der bekannte Ausdruck Round(X * 100) / 100 überläuft, sobald X * 100 die Int64-Range verlässt, während FormCals Round(X, 2) ein Double nimmt und eines zurückgibt

Rundungsmatrix für Delphi-XFA-Formulare mit HotPDF: FormCalc Round bringt 2.5 von null weg auf 3, während System.Round 2 liefert
FormCalc nimmt Halben von null weg und gibt ein Double zurück, also wird 2.5 zu 3, wo System.Round 2 antwortet

Große Werte brauchen noch eine Regel. Ein Double hat 52 explizite Bruchbits, also hat ein Betrag ab 252 (4.503.599.627.370.496) keinen Bruchteil mehr zum Runden. HotPDF skaliert den Absolutbetrag mit 10places, und wenn der skalierte Wert 252 erreicht, reicht es die Eingabe unverändert durch — weiteres Multiplizieren würde nur Ziffern erfinden oder überlaufen. Die binäre Speicherung setzt die andere Grenze, und die gilt für jeden Double-basierten Evaluator, FormCalc eingeschlossen. Das Literal 2.675 wird als 2.67499999999999982236431605997495353221893310546875 gespeichert. Auf zwei Stellen gerundet ergibt das 2.67. FormCalc hat keinen dezimalgenauen Money-Typ, also können Formular und Port nur über den Binärwert übereinstimmen, den beide halten

uses
  Math;

// FormCalc-artiges Round für einen Delphi-Port: Halben von null weg,
// Stellenzahl Richtung null abgeschnitten und auf 0..12 begrenzt, Ergebnis bleibt ein 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);                         // keine Nachkommastellen mehr zum Runden
  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 Stellen gelten als 2)
// FormCalcRound(1234.5, -2)     = 1235     (eine negative Zahl bedeutet 0 Stellen)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) überläuft das Int64)

Wie viele Nachkommastellen nimmt FormCalc Round an?

Ganze Stellen von 0 bis 12. HotPDF schneidet das zweite Argument Richtung null ab und begrenzt es dann auf diese Range, also rundet Round(X, 2.7) auf zwei Stellen, Round(X, 15) auf zwölf, und sowohl Round(X, -2) als auch Round(X, -0.5) auf eine ganze Zahl. Die Regel gilt überall dort, wo HotPDF FormCalc auswertet, also fällt eine Summe, die beim Flattening berechnet wird, identisch zu einer aus, die beim Ausfüllen berechnet wird. Tabellenkalkulations-Gewohnheiten ziehen in die andere Richtung. Excels ROUND(1234.5, -2) gibt 1200, weil Excel eine negative Zahl als Stellen links vom Dezimalpunkt liest; FormCalc gibt 1235. Delphis Helper drehen die Konvention noch mal um: Math.RoundTo und SimpleRoundTo nehmen eine Zehnerpotenz, also bedeutet RoundTo(X, -2) zwei Nachkommastellen und RoundTo(1234.567, 2) ist 1200. Ein Port, der das zweite Argument des Skripts direkt in RoundTo kopiert, druckt Hunderter, wo das Formular Cent zeigt. Behalten Sie die Stellenzahl bei, wie FormCalc sie definiert, und führen Sie sie durch einen Helper wie FormCalcRound, der auch die Tie-Regel korrekt hält

Warum liefert a - b * Int(a / b) den falschen Rest?

Weil der Quotient lange vor dem Dividenden aufhört, exakt zu sein. Nehmen Sie Mod(1E20, 7). Der Dividend ist ohne Fehler darstellbar — 1020 ist 220 × 520, und 520 passt in 53 Bits — und der wahre Rest ist 2. Der Quotient, etwa 1.43 × 1019, ist es nicht: Doubles in dieser Range liegen 2.048 auseinander, also ist Int(a / b) falsch, bevor die Multiplikation überhaupt anfängt, und a - b * q gibt zurück, was die Rundungsfehler übrig lassen. Delphis mod-Operator arbeitet nur auf Integern, und Trunc kann einen Quotienten jenseits der Int64-Range nicht halten. Prüfen Sie System.Math.FMod, bevor Sie sich hier darauf verlassen. Eine Implementierung, die den Rest aus dem Quotienten ableitet, erbt denselben Fehler, und der Vergleich von FMod(1E20, 7) mit den erwarteten 2 entscheidet die Frage in einer Zeile

Die binäre Langdivision bildet den Quotienten nie. Verdoppeln Sie den Divisor, bis er die Hälfte des Dividenden überschreitet, dann laufen Sie zurück und subtrahieren den skalierten Divisor, wo er hineinpasst. Jeder skalierte Divisor ist das Original mal eine Zweierpotenz, trägt also keinen Rundungsfehler. Jede Subtraktion nimmt eine Zahl zwischen der Hälfte und dem gesamten aktuellen Rest weg — der Fall, in dem nach dem Sterbenz-Lemma IEEE-754-Subtraktion ohne Rundung auskommt. Das Ergebnis ist exakt. Danach greift FormCals Vorzeichenregel: Der Rest nimmt das Vorzeichen des Dividenden, also ist Mod(-7, 3) -1 und Mod(7, -3) ist 1. Ein Dividend, der dem Betrag nach kleiner als der Divisor ist, kommt unverändert zurück, und ein Divisor null ergibt gar keine Zahl

FormCalc Mod in Delphi mit HotPDF: Die Quotientenformel scheitert bei 1E20, während die binäre Langdivision den Divisor verdoppelt und exakt subtrahiert
Der Quotient nahe 1.43E19 sitzt bereits auf einem groben Double-Raster, während die binäre Langdivision den exakten Rest erreicht, ohne einen Quotienten zu bilden
// Exakter Gleitkomma-Rest, Vorzeichen des Dividenden, kein Quotient nötig
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;                   // größtes Zweierpotenz-Vielfaches
  while Step > Divisor do
  begin
    if Result >= Step then
      Result := Result - Step;          // exakt: 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 schneidet ihren Index ab, HasValue ignoriert Leerraum

Choose(n, item1, item2, …) wandelt ihr erstes Argument in eine Zahl um und schneidet es ab, also liefert Choose(2.7, "a", "b", "c") "b" und wirft keinen Typfehler. Ein Index unter 1 oder hinter dem letzten Eintrag gibt einen leeren String zurück, und ein Null-Index gibt null zurück. HasValue ist die Funktionsform, mit der Autoren optionale Felder testen: Sie antwortet 0 für null und für Text, der nur aus Unicode-White-Space besteht. Die Zahl 0 zählt weiterhin. Ein Mengenfeld mit 0 ist ausgefüllt; ein Kommentarfeld mit drei Leerzeichen nicht, obwohl XFA-White-Space-Textwerte diese Leerzeichen durch ein Speichern intakt halten. Zusammen ergeben die beiden Funktionen die übliche Absicherung für optionale Positionen, if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif, die eine unausgefüllte Position leer lässt und eine Spaltensumme auf das Eingebene begrenzt. Ein Delphi-Port, der eine leere Menge als 0 behandelt, druckt eine 0.00-Positionssumme, wo das Formular nichts druckt

Was gibt FormCalc für ein leeres Feld zurück?

Null — und null überlebt die meisten Funktionen, die ein Calculate-Skript aufruft. In FormCalc ist ein leerer String ein echter Wert und null seine Abwesenheit, und die String-Funktionen trennen beides:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim und Space geben null zurück, wenn ihr Argument null ist
  • Left, Right, At und Replace prüfen ihre ersten zwei Argumente, Stuff ihre ersten drei, und Substr jedes gelieferte Argument
  • Ein leerer String, der an eine davon übergeben wird, wird als Text verarbeitet: Upper("") ist "", nicht null
  • Skripte können null explizit mit dem null-Literal oder Null() erzeugen

Delphi-Strings haben kein null, und genau dort entfernen sich handgeschriebene Ports am weitesten. Concat steht außerhalb der Liste: Es überspringt null-Argumente, also liefert Concat(Prefix, Code) bei unausgefülltem Prefix denselben Text, den ein Port aus '' baut. Len nicht. Len(Prefix) ist null und ein daran gebundenes Zahlenfeld bleibt leer, während Length('') dort eine 0 ablegt. Die Aggregate folgen der Überspring-Regel: Sum, Avg, Count, Min und Max ignorieren leere Einträge, also ergibt Avg über 10, eine leere Zeile und 20 den Wert 15, und Count ist 2. Ein Port, der die leere Zeile als 0 liest, meldet einen Durchschnitt von 10. Eine Spalte ohne jede Eingabe gibt Sum gar keinen Wert, was das Grand-Total-Feld leer hält

Null-Propagation-Karte für FormCalc in Delphi mit HotPDF: String-Funktionen geben null zurück, Aggregate überspringen leere Einträge, und HasValue behandelt White-Space-Text als unausgefüllt
Null wandert weiter durch Len und die Aggregate, während Concat und Sum es überspringen, also muss ein Port Felder als Variant modellieren, statt null zu einem leeren String kollabieren zu lassen
uses
  Variants;

// FormCalc-artiges Avg: leere Einträge werden übersprungen, nicht als 0 gezählt
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     liest man den leeren Eintrag als 0, ergibt das 10
// FormCalcAvg([Null, Null])   = Null   das Durchschnittsfeld bleibt leer

Modellieren Sie Felder im Port als Variant und halten Sie Null von '' getrennt. Werte aus einem Dataset brauchen dieselbe Sorgfalt: TField.Value gibt für eine NULL-Spalte Null zurück, während TField.AsString sie in einen leeren String verwandelt und den Unterschied ausradiert, bevor der Port ihn je zu sehen bekommt

Lassen Sie das Formular seine eigenen Skripte ausführen

Der sicherste Port ist oft gar kein Port. THotPDF.FlattenLoadedXFA wertet das Calculate-Skript jedes Felds aus, während es das Formular layoutet und die Felder als AcroForm-Felder neu aufbaut, und wendet dabei die Rundungs-, Rest- und Null-Regeln von oben an. Derselbe Aufruf erledigt den Rest des XFA-zu-AcroForm-Flattening, vom Layout bis zum Widget-Mapping. Eine Formel, die nicht auswertbar ist — eine unauflösbare Referenz, eine Division durch null, ein Parse-Fehler — scheitert als Ganzes. Nichts Halb-Berechnetes erreicht das Feld. Die flachgelegte Datei neu zu laden und ihre Feldwerte mit der Ausgabe des Ports zu vergleichen, macht aus einer vagen Diskrepanz eine Liste von Feldnamen:

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;      // '' gegen '0.00' ist eine echte Diskrepanz
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 = Felder werden schreibgeschützt
    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;

Lesen Sie die Warnungen, bevor Sie einer Summe vertrauen; die Liste nennt jedes Element, das die Konvertierung nicht zuordnen konnte, also suchen Sie nach Einträgen, die ein berechnetes Feld nennen. Geben Sie dem Port dann einen Sample-Baukasten nach den Regeln von oben: Positionsbeträge, die auf der zweiten Dezimale auf .5 landen, eine 20-stellige Kontonummer durch Mod, ein Round mit gebrochener Stellenzahl und eine optionale Zeile, die leer bleibt. Jede Zeile, die die Prozedur druckt, ist eine Regel, die der Port falsch hat. Formulare, die mit AcroForm-Format- und Calculate-Skripten rechnen, folgen den JavaScript-Zahlenregeln — Math.round(-2.5) ist dort -2, eine dritte Antwort auf dieselbe Frage

Ist die Zahl, die Ihr Dienst braucht, eine, die das Formular ohnehin druckt, nehmen Sie sie aus dem Formular: Mit der HotPDF Delphi PDF Component flachlegen, das Ergebnis neu laden und das Feld lesen. Die Hilfsfunktionen von oben lohnen sich nur für Zahlen, die das Formular nie berechnet