Artykuł techniczny

FormCalc Round, Mod i Null to nie Delphi Round i mod

Formularz faktury liczy dopłatę przez Round(Subtotal * 0.025, 2), a serwis w Delphi sprawdzający jej sumy nie zgadza się ze spłaszczonym PDF-em na pozycjach z półgroszem. FormCalc zaokrągla połówki od zera i zwraca Double, podczas gdy System.Round zaokrągla do parzystej, więc pewna kontrola to spłaszczenie formularza XFA przez HotPDF i odpalenie jego skryptów FormCalc

Połówki od zera, a wynik zostaje Double

System.Round w Delphi podąża za trybem zaokrąglania FPU, a tryb domyślny zaokrągla połówki do parzystej: Round(2.5) daje 2, Round(3.5) daje 4, a Round(-2.5) daje -2. Zaokrąglanie bankierskie służy statystyce. Do formularza, który od zawsze pokazywał 3, pasuje źle. Round w FormCalc bierze połówki od zera, więc 2.5 staje się 3, a -2.5 staje się -3. Typ zwracany też się różni. System.Round zwraca Int64, dlatego znany idiom Round(X * 100) / 100 przepełnia się, jak tylko X * 100 wyjdzie poza zakres Int64, podczas gdy Round(X, 2) w FormCalc bierze Double i Double oddaje

Matryca zaokrągleń dla formularzy XFA w Delphi z HotPDF: FormCalc Round bierze 2.5 na 3 od zera, a System.Round daje 2
FormCalc bierze połówki od zera i zwraca Double, więc 2.5 staje się 3 tam, gdzie System.Round odpowiada 2

Duże wartości potrzebują jeszcze jednej reguły. Double ma 52 jawne bity ułamka, więc wielkość 252 (4 503 599 627 370 496) i więcej nie ma już części ułamkowej do zaokrąglenia. HotPDF skaluje wartość bezwzględną przez 10places i kiedy przeskalowana wartość dochodzi do 252, oddaje wejście bez zmian — dalsze mnożenie tylko wymyślałoby cyfry albo przepełniało. Binarny zapis wyznacza drugi limit i ten dotyczy każdego ewaluatora opartego na Double, FormCalca włącznie. Literal 2.675 jest zapisany jako 2.67499999999999982236431605997495353221893310546875. Zaokrąglony do dwóch miejsc daje 2.67. FormCalc nie ma dziesiętnie dokładnego typu na pieniądze, więc formularz i port mogą się zgodzić tylko co do binarnej wartości, którą oba trzymają

uses
  Math;

// Round w stylu FormCalc dla portu w Delphi: połówki od zera,
// liczba miejsc ucięta ku zeru i trzymana w 0..12, wynik zostaje 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);                         // nie ma już cyfr ułamkowych do zaokrąglenia
  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 miejsca liczą się jako 2)
// FormCalcRound(1234.5, -2)     = 1235     (ujemna liczba znaczy 0 miejsc)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) przepełnia Int64)

Ile miejsc dziesiętnych przyjmuje Round w FormCalcu?

Całkowite miejsca od 0 do 12. HotPDF ucina drugi argument ku zeru i trzyma go w tym zakresie, więc Round(X, 2.7) zaokrągla do dwóch miejsc, Round(X, 15) do dwunastu, a zarówno Round(X, -2), jak i Round(X, -0.5) do liczby całkowitej. Reguła jest ta sama wszędzie, gdzie HotPDF liczy FormCalc, więc suma policzona podczas spłaszczania i ta policzona w trakcie wypełniania formularza wychodzą identyczne. Nawyki arkuszowe ciągną w drugą stronę. ROUND(1234.5, -2) w Excelu daje 1200, bo Excel czyta ujemną liczbę jako cyfry na lewo od przecinka dziesiętnego; FormCalc daje 1235. Pomocniki Delphi odwracają konwencję jeszcze raz: Math.RoundTo i SimpleRoundTo biorą potęgę dziesięciu, więc RoundTo(X, -2) znaczy dwa miejsca po przecinku, a RoundTo(1234.567, 2) to 1200. Port, który przepisuje drugi argument skryptu wprost do RoundTo, drukuje setki tam, gdzie formularz pokazuje grosze. Trzymaj liczbę miejsc tak, jak definiuje ją FormCalc, i przepuszczaj ją przez pomocnik typu FormCalcRound, który dodatkowo trzyma regułę połówek

Dlaczego a - b * Int(a / b) zwraca złą resztę?

Bo iloraz przestaje być dokładny na długo przed dzielną. Weź Mod(1E20, 7). Dzielna jest reprezentowalna bez błędu — 1020 to 220 × 520, a 520 mieści się w 53 bitach — i prawdziwa reszta to 2. Iloraz, około 1,43 × 1019, już nie: Double w tym zakresie siedzą co 2 048, więc Int(a / b) jest zły, zanim mnożenie się zacznie, a a - b * q zwraca cokolwiek zostawią po sobie błędy zaokrągleń. Operator mod w Delphi działa wyłącznie na liczbach całkowitych, a Trunc nie pomieści ilorazu poza zakresem Int64. Zanim się tu oprzesz na System.Math.FMod, sprawdź go. Implementacja wywodząca resztę z ilorazu dziedziczy ten sam błąd, a porównanie FMod(1E20, 7) z oczekiwaną dwójką rozstrzyga sprawę w jednym wierszu

Binarne dzielenie pisemne nigdy nie tworzy ilorazu. Podwajaj dzielnik, aż przeskoczy połowę dzielnej, a potem schodź w dół, odejmując przeskalowany dzielnik wszędzie, gdzie się mieści. Każdy przeskalowany dzielnik to oryginał razy potęga dwójki, więc nie niesie błędu zaokrąglenia. Każde odejmowanie zabiera liczbę między połową a całością bieżącej reszty — przypadek, w którym z lematu Sterbenza odejmowanie w IEEE 754 nie wymaga zaokrąglenia. Wynik jest dokładny. Potem działa reguła znaku FormCalca: reszta bierze znak dzielnej, więc Mod(-7, 3) to -1, a Mod(7, -3) to 1. Dzielna o mniejszej wartości bezwzględnej niż dzielnik wraca bez zmian, a dzielnik zerowy nie daje żadnej liczby

FormCalc Mod w Delphi z HotPDF: formuła z ilorazem zawodzi przy 1E20, a binarne dzielenie pisemne podwaja dzielnik i odejmuje dokładnie
Iloraz blisko 1.43E19 siedzi już na grubej siatce Double, a binarne dzielenie pisemne dochodzi do dokładnej reszty bez tworzenia ilorazu
// Dokładna reszta zmiennoprzecinkowa, znak dzielnej, iloraz niepotrzebny
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;                   // największa wielokrotność będąca potęgą dwójki
  while Step > Divisor do
  begin
    if Result >= Step then
      Result := Result - Step;          // dokładnie: 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 ucina swój indeks, HasValue ignoruje puste

Choose(n, item1, item2, …) konwertuje swój pierwszy argument na liczbę i ucina go, więc Choose(2.7, "a", "b", "c") zwraca "b" i nie podnosi błędu typu. Indeks poniżej 1 albo za ostatnią pozycją zwraca pusty string, a indeks null zwraca null. HasValue to forma funkcyjna, której autorzy używają do testowania opcjonalnych pól: odpowiada 0 dla null i dla tekstu złożonego wyłącznie z białych znaków Unicode. Liczba 0 nadal się liczy. Pole ilości z 0 zostało wypełnione; pole uwag z trzema spacjami nie, choć tekstowe wartości białych znaków XFA trzymają te spacje nietknięte przez zapis. Razem te dwie funkcje dają zwykłą straż dla opcjonalnych pozycji, if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif, która zostawia niewypełnioną pozycję pustą i trzyma sumę kolumny ograniczoną do tego, co wpisano. Port w Delphi traktujący pustą ilość jak 0 wydrukuje sumę pozycji 0.00 tam, gdzie formularz nie drukuje nic

Co FormCalc zwraca dla pustego pola?

Null — i null przeżywa większość funkcji, które woła skrypt calculate. W FormCalcu pusty string to realna wartość, a null to jej brak, i funkcje stringowe trzymają je osobno:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim i Space zwracają null, kiedy ich argument jest nullem
  • Left, Right, At i Replace sprawdzają swoje dwa pierwsze argumenty, Stuff trzy pierwsze, a Substr każdy podany
  • Pusty string podany do którejś z nich jest przetwarzany jako tekst: Upper("") to "", nie null
  • Skrypty mogą wyrabiać null wprost literałem null albo Null()

Stringi w Delphi nie mają nulla i to jest miejsce, w którym porty pisane ręcznie odjeżdżają najdalej. Concat siedzi poza listą: pomija argumenty null, więc Concat(Prefix, Code) przy niewypełnionym prefiksie daje ten sam tekst, który port zbuduje z ''. Len nie. Len(Prefix) to null i pole numeryczne związane z nim zostaje puste, podczas gdy Length('') wstawia tam 0. Agregaty podążają za regułą pomijania: Sum, Avg, Count, Min i Max ignorują puste pozycje, więc Avg po 10, pustej pozycji i 20 to 15, a Count to 2. Port czytający pustą pozycję jako 0 raportuje średnią 10. Kolumna bez niczego wpisanego nie daje Sum żadnej wartości, co trzyma pole sumy głównej puste

Mapa propagacji nulla dla FormCalca w Delphi z HotPDF: funkcje stringowe zwracają null, agregaty pomijają puste pozycje, a HasValue traktuje tekst białych znaków jako niewypełniony
Null dalej płynie przez Len i agregaty, podczas gdy Concat i Sum go pomijają, więc port musi modelować pola jako Variant, a nie zwijać nulla do pustego stringa
uses
  Variants;

// Avg w stylu FormCalca: puste pozycje są pomijane, nie liczone jako 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     czytanie pustej pozycji jako 0 daje 10
// FormCalcAvg([Null, Null])   = Null   pole średniej zostaje puste

Modeluj pola jako Variant w porcie i trzymaj Null z dala od ''. Wartości wyciągane z datasetu potrzebują tej samej pieczołowitości: TField.Value zwraca Null dla kolumny NULL, podczas gdy TField.AsString zamienia ją na pusty string i zaciera różnicę, zanim port w ogóle ją zobaczy

Pozwól formularzowi odpalić własne skrypty

Najbezpieczniejszy port to często żaden port. THotPDF.FlattenLoadedXFA liczy skrypt calculate każdego pola, w trakcie gdy rozkłada formularz, i przebudowuje pola na pola AcroForm, stosując powyższe reguły zaokrąglania, reszty i nulla. To samo wołanie ogarnia resztę spłaszczania XFA do AcroForm, od layoutu po mapowanie widgetów. Formuła, której nie da się policzyć — nierozwiązane odwołanie, dzielenie przez zero, błąd parsowania — zawodzi w całości. Nic półpoliczonego nie dociera do pola. Ponowne wczytanie spłaszczonego pliku i porównanie wartości pól z wyjściem portu zamienia mgliste niezgodności na listę nazw pól:

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;      // '' kontra '0.00' to realna niezgodność
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 = pola stają się tylko do odczytu
    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;

Przeczytaj ostrzeżenia, zanim uwierzysz w jakąkolwiek sumę; lista wymienia każdy element, którego konwersja nie umiała zmapować, więc wypatruj wpisów nazywających pole liczone. Potem daj portowi próbkę zbudowaną pod powyższe reguły: kwoty pozycji lądujące na .5 na drugim miejscu dziesiętnym, 20-cyfrowy numer konta przepuszczony przez Mod, Round z ułamkową liczbą miejsc i jedną pozycję opcjonalną zostawioną pustą. Każdy wiersz, który wypisze procedura, to reguła, którą port robi źle. Formularze liczące przez skrypty format i calculate AcroForm podążają za regułami liczb JavaScript — Math.round(-2.5) daje tam -2, trzecią odpowiedź na to samo pytanie

Jeśli liczba, której potrzebuje twój serwis, to jedna z tych, które formularz już drukuje, weź ją z formularza: spłaszcz go komponentem HotPDF Delphi PDF, wczytaj ponownie wynik i przeczytaj pole. Funkcje pomocnicze powyżej zarabiają na swój utrzymanie tylko przy liczbach, których formularz nigdy nie liczy