Technisch artikel

FormCalc Round, Mod en Null zijn niet Delphi Round en mod

Een factuurformulier berekent een toeslag met Round(Subtotal * 0.025, 2), en een Delphi-service die de totalen nadeltaelt zit op halfcentregels oneens met de geflattende PDF. FormCalc rondt halven van nul af en geeft een Double terug, terwijl System.Round naar even rondt, dus de betrouwbare controle is: HotPDF het XFA-formulier laten flatteneren en zijn FormCalc-scripts laten uitvoeren

Halven van nul af, en het resultaat blijft een Double

De System.Round van Delphi volgt de rounding mode van de FPU, en de standaardmodus rondt half naar even: Round(2.5) is 2, Round(3.5) is 4 en Round(-2.5) is -2. Bankers rounding past bij statistiek. Voor een formulier dat altijd 3 heeft laten zien is het een slechte match. De Round van FormCalc haalt halven van nul af, dus 2.5 wordt 3 en -2.5 wordt -3. Ook het returntype verschilt. System.Round geeft een Int64 terug, en daarom loopt de vertrouwde idioom Round(X * 100) / 100 over zodra X * 100 het Int64-bereik verlaat, terwijl de Round(X, 2) van FormCalc een Double neemt en er ook één teruggeeft

Afrondmatrix voor Delphi XFA-formulieren met HotPDF: FormCalc Round brengt 2.5 naar 3, van nul af, terwijl System.Round 2 geeft
FormCalc haalt halve ties van nul af en geeft een Double terug, dus 2.5 wordt 3 waar System.Round 2 antwoordt

Grote waarden hebben nog een regel nodig. Een Double heeft 52 expliciete fraction-bits, dus een grootte vanaf 252 (4.503.599.627.370.496) heeft geen fractiedeel meer om af te ronden. HotPDF schaalt de absolute waarde met 10places, en als de geschaalde waarde 252 bereikt geeft hij de invoer ongewijzigd terug — verder vermenigvuldigen verzint alleen maar cijfers of loopt over. Binaire opslag stelt de andere grens, en die geldt voor elke evaluator op basis van Double, FormCalc incluis. Het literal 2.675 wordt opgeslagen als 2.67499999999999982236431605997495353221893310546875. Op twee plaatsen afgerond geeft dat 2.67. FormCalc heeft geen decimaal-exact geldtype, dus een formulier en een port komen hooguit overeen over de binaire waarde die ze allebei vasthouden

uses
  Math;

// Round à la FormCalc voor een Delphi-port: halven van nul af,
// aantal plaatsen richting nul afgekapt en begrensd op 0..12, resultaat blijft 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);                         // geen fractiecijfers meer om af te ronden
  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 plaatsen telt als 2)
// FormCalcRound(1234.5, -2)     = 1235     (een negatief aantal betekent 0 plaatsen)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) overloopt Int64)

Hoeveel decimalen accepteert FormCalc Round?

Hele plaatsen van 0 tot 12. HotPDF kapt het tweede argument richting nul af en begrenst het daarna op dat bereik, dus Round(X, 2.7) rondt op twee plaatsen af, Round(X, 15) op twaalf, en zowel Round(X, -2) als Round(X, -0.5) op een geheel getal. De regel is overal gelijk waar HotPDF FormCalc evalueert, dus een totaal berekend tijdens het flatteneren en één berekend tijdens het invullen van het formulier komen er identiek uit. Spreadsheetgewoonten trekken de andere kant op. De ROUND(1234.5, -2) van Excel geeft 1200, want Excel leest een negatief aantal als cijfers links van de decimale punt; FormCalc geeft 1235. De Delphi-helpers draaien de conventie nog een keer om: Math.RoundTo en SimpleRoundTo nemen een macht van tien, dus RoundTo(X, -2) betekent twee decimalen en RoundTo(1234.567, 2) is 1200. Een port die het tweede argument van het script rechtstreeks in RoundTo kopieert, drukt honderden af waar het formulier cents toont. Houd het plaatsenaantal zoals FormCalc het definieert en stuur het door een helper als FormCalcRound, die ook de tie-regel goed houdt

Waarom geeft a - b * Int(a / b) de verkeerde rest?

Omdat het quotiënt veel eerder inexakt wordt dan het dividend. Neem Mod(1E20, 7). Het dividend is zonder fout representeerbaar — 1020 is 220 × 520, en 520 past in 53 bits — en de echte rest is 2. Het quotiënt, zo'n 1,43 × 1019, is dat niet: Doubles in dat bereik liggen 2.048 uit elkaar, dus Int(a / b) is al verkeerd voordat de vermenigvuldiging begint, en a - b * q geeft terug wat de afrondfouten achterlaten. De mod-operator van Delphi werkt alleen op integers, en Trunc kan een quotiënt boven het Int64-bereik niet vasthouden. Controleer System.Math.FMod voordat u er hierop vertrouwt. Een implementatie die de rest uit het quotiënt afleidt, erft dezelfde fout, en FMod(1E20, 7) vergelijken met de verwachte 2 beslecht de kwestie in één regel

Binaire staartdeling vormt het quotiënt nooit. Verdubbel de deler tot hij voorbij de helft van het dividend komt, en loop dan terug naar beneden, waar u de geschaalde deler telkens aftrekt waar hij past. Elke geschaalde deler is het origineel keer een macht van twee, dus hij draagt geen afrondfout. Elke aftrekking haalt een getal weg tussen de helft en alles van de huidige rest — precies het geval waarin, volgens het Sterbenz-lemma, IEEE 754-subtractie geen afronding kent. Het resultaat is exact. Daarna geldt de tekenregel van FormCalc: de rest neemt het teken van het dividend aan, dus Mod(-7, 3) is -1 en Mod(7, -3) is 1. Een dividend met een kleinere absolute waarde dan de deler komt ongewijzigd terug, en een nuldeler geeft helemaal geen getal

FormCalc Mod in Delphi met HotPDF: de quotiëntformule faalt bij 1E20 terwijl binaire staartdeling de deler verdubbelt en exact aftrekt
het quotiënt rond 1.43E19 zit al op een grof Double-raster, terwijl binaire staartdeling de exacte rest bereikt zonder een quotiënt te vormen
// Exacte drijvende-kommarest, teken van het dividend, geen quotiënt nodig
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;                   // grootste veelvoud dat een macht van twee is
  while Step > Divisor do
  begin
    if Result >= Step then
      Result := Result - Step;          // exact: 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 kapt zijn index af, HasValue negeert witruimte

Choose(n, item1, item2, …) zet zijn eerste argument om in een getal en kapt het af, dus Choose(2.7, "a", "b", "c") geeft "b" terug en gooit geen typefout. Een index onder 1 of voorbij het laatste item geeft een lege string, en een null-index geeft null. HasValue is de functievorm waarmee auteurs optionele velden testen: hij antwoordt 0 voor null en voor tekst die alleen uit Unicode-witruimte bestaat. Het getal 0 telt nog steeds mee. Een aantalsveld met 0 is ingevuld; een opmerkingsveld met drie spaties niet, ook al houden XFA white-space tekstwaarden die spaties intact door een save heen. Samen geven die twee functies de gebruikelijke garde voor optionele regels, if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif, die een niet-ingevulde regel leeg laat en een kolomtotaal beperkt tot wat is ingevoerd. Een Delphi-port die een leeg aantal als 0 behandelt, drukt een regeltotaal van 0.00 af waar het formulier niets drukt

Wat geeft FormCalc terug voor een leeg veld?

Null — en null overleeft de meeste functies die een calculate-script aanroept. In FormCalc is een lege string een echte waarde en null is de afwezigheid daarvan, en de stringfuncties houden de twee uit elkaar:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim en Space geven null terug als hun argument null is
  • Left, Right, At en Replace controleren hun eerste twee argumenten, Stuff zijn eerste drie, en Substr elk meegegeven argument
  • Een lege string die aan een van hen wordt doorgegeven, wordt als tekst verwerkt: Upper("") is "", niet null
  • Scripts kunnen null expliciet produceren met het literal null of Null()

Delphi-strings kennen geen null, en dat is waar handgeschreven ports het meest afdwalen. Concat staat buiten de lijst: hij slaat null-argumenten over, dus Concat(Prefix, Code) op een niet-ingevulde prefix geeft dezelfde tekst als een port opbouwt uit ''. Len niet. Len(Prefix) is null en een numeriek veld dat eraan hangt blijft leeg, terwijl Length('') er 0 neerzet. De aggregates volgen de overslagregel: Sum, Avg, Count, Min en Max negeren lege entries, dus Avg over 10, een lege regel en 20 is 15 en Count is 2. Een port die de lege regel als 0 leest, meldt een gemiddelde van 10. Een kolom waarin niets is ingevoerd geeft Sum helemaal geen waarde, waardoor het eindtotaalveld leeg blijft

Null-propagatiekaart voor FormCalc in Delphi met HotPDF: stringfuncties geven null terug, aggregates slaan lege entries over en HasValue ziet witruimtetekst als niet ingevuld
null blijft door Len en de aggregates heen bewegen terwijl Concat en Sum hem overslaan, dus een port moet velden als Variant modelleren in plaats van null samen te vouwen tot een lege string
uses
  Variants;

// Avg à la FormCalc: lege entries worden overgeslagen, niet als nul geteld
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     de lege entry als 0 lezen geeft 10
// FormCalcAvg([Null, Null])   = Null   het gemiddeldeveld blijft leeg

Modelleer velden in de port als Variant en houd Null gescheiden van ''. Waarden uit een dataset vragen dezelfde zorg: TField.Value geeft Null terug voor een NULL-kolom, terwijl TField.AsString hem in een lege string omzet en het verschil uitwist voordat de port hem ooit ziet

Laat het formulier zijn eigen scripts draaien

De veiligste port is vaak helemaal geen port. THotPDF.FlattenLoadedXFA evalueert het calculate-script van elk veld terwijl hij het formulier indeelt en de velden herbouwt als AcroForm-velden, met de afrond-, rest- en nullregels hierboven. Dezelfde aanroep doet de rest van het werk bij XFA naar AcroForm flatteneren, van indeling tot widget-mapping. Een formule die niet kan worden geëvalueerd — een onopgeloste referentie, een deling door nul, een parsefout — faalt in zijn geheel. Er bereikt niets halfberekends het veld. Het geflatteerde bestand opnieuw laden en zijn veldwaarden vergelijken met de uitvoer van de port, maakt van een vaag meningsverschil een lijst met veldnamen:

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;      // '' tegenover '0.00' is een echte mismatch
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 = velden worden 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;

Lees de waarschuwingen voordat u een totaal vertrouwt; de lijst noemt elk element dat de conversie niet kon mappen, dus zoek naar entries die een berekend veld noemen. Geef de port daarna een sample die op de regels hierboven is gebouwd: regelbedragen die op .5 uitkomen op de tweede decimaal, een rekeningnummer van 20 cijfers door Mod, een Round met een fractioneel plaatsenaantal, en één optionele regel leeg gelaten. Elke regel die de procedure afdrukt is een regel die de port verkeerd heeft. Formulieren die rekenen met AcroForm-format en calculate-scripts volgen de getalregels van JavaScript — Math.round(-2.5) is daar -2, een derde antwoord op dezelfde vraag

Als het getal dat uw service nodig heeft er een is dat het formulier al toont, haal het dan uit het formulier: flatten het met de HotPDF Delphi PDF-component, laad het resultaat opnieuw en lees het veld. De helperfuncties hierboven verdienen hun geld alleen voor getallen die het formulier nooit berekent