Техническая статья

FormCalc Round, Mod и Null — не Delphi Round и mod

Форма-накладная считает надбавку через Round(Subtotal * 0.025, 2), и сервис на Delphi, перепроверяющий итоги, расходится со сглаженным PDF на строках с суммами в полкопейки. FormCalc округляет половины от нуля и возвращает Double, тогда как System.Round округляет к чётному, поэтому надёжная проверка — дать HotPDF сгладить XFA-форму и выполнить её FormCalc-скрипты

Половины от нуля, и результат остаётся Double

System.Round в Delphi следует режиму округления FPU, а режим по умолчанию округляет половины к чётному: Round(2.5) даёт 2, Round(3.5) даёт 4, а Round(-2.5) даёт -2. Банкирское округление подходит статистике. Форме, всегда показывавшей 3, оно не подходит вовсе. Round в FormCalc уводит половины от нуля, поэтому 2.5 становится 3, а -2.5 становится -3. Отличается и тип возврата. System.Round возвращает Int64, оттого знакомый приём Round(X * 100) / 100 переполняется, как только X * 100 покидает диапазон Int64, тогда как Round(X, 2) в FormCalc принимает Double и возвращает Double

Матрица округления для XFA-форм Delphi с HotPDF: FormCalc Round уводит 2.5 к 3 от нуля, а System.Round даёт 2
FormCalc уводит половинные связи от нуля и возвращает Double, поэтому 2.5 становится 3 там, где System.Round отвечает 2

Большим значениям нужно ещё одно правило. У Double 52 явных бита дробной части, поэтому величина от 252 (4 503 599 627 370 496) и выше не имеет дробной части, которую можно округлить. HotPDF масштабирует абсолютное значение на 10places, и когда масштабированное значение достигает 252, возвращает вход без изменений — дальнейшее умножение только выдумало бы цифры или переполнилось. Второй предел ставит двоичное хранение, и он касается любого вычислителя на Double, FormCalc не исключение. Литерал 2.675 хранится как 2.67499999999999982236431605997495353221893310546875. При округлении до двух знаков выходит 2.67. У FormCalc нет десятично-точного денежного типа, поэтому форма и перенос могут сойтись только на двоичном значении, которое держат оба

uses
  Math;

// Round в стиле FormCalc для переноса на Delphi: половины от нуля,
// число знаков усекается к нулю и держится в 0..12, результат остаётся 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);                         // дробных цифр для округления не осталось
  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 знака считаются как 2)
// FormCalcRound(1234.5, -2)     = 1235     (отрицательное число означает 0 знаков)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) переполняет Int64)

Сколько десятичных знаков принимает Round в FormCalc?

Целые знаки от 0 до 12. HotPDF усекает второй аргумент к нулю и затем удерживает его в этом диапазоне, поэтому Round(X, 2.7) округляет до двух знаков, Round(X, 15) — до двенадцати, а Round(X, -2) и Round(X, -0.5) — до целого. Правило одно всюду, где HotPDF вычисляет FormCalc, поэтому итог, посчитанный при сглаживании, и итог, посчитанный при заполнении формы, выходят одинаковыми. Табличные привычки тянут в другую сторону. ROUND(1234.5, -2) в Excel даёт 1200, потому что Excel читает отрицательное число как цифры слева от десятичной точки; FormCalc даёт 1235. Помощники Delphi переворачивают конвенцию ещё раз: Math.RoundTo и SimpleRoundTo принимают степень десяти, поэтому RoundTo(X, -2) означает два десятичных знака, а RoundTo(1234.567, 2) — это 1200. Перенос, копирующий второй аргумент скрипта прямо в RoundTo, печатает сотни там, где форма показывает копейки. Держите число знаков, как его определяет FormCalc, и пропускайте его через помощник вроде FormCalcRound, который заодно сохраняет и правило половин

Почему a - b * Int(a / b) возвращает неверный остаток?

Потому что частное перестаёт быть точным задолго до делимого. Возьмите Mod(1E20, 7). Делимое представимо без ошибки — 1020 это 220 × 520, и 520 влезает в 53 бита, — а истинный остаток равен 2. Частное, около 1.43 × 1019, — нет: Double в этом диапазоне сидят с шагом 2 048, поэтому Int(a / b) неверно ещё до начала умножения, и a - b * q возвращает всё, что оставили ошибки округления. Оператор mod в Delphi работает только с целыми, а Trunc не вместит частное за пределами диапазона Int64. Прежде чем опираться здесь на System.Math.FMod, проверьте его. Реализация, выводящая остаток из частного, наследует ту же ошибку, и сравнение FMod(1E20, 7) с ожидаемой двойкой решает вопрос одной строкой

Двоичное длинное деление вообще не строит частное. Удваивайте делитель, пока он не перевалит за половину делимого, затем шагайте обратно вниз, вычитая масштабированный делитель всюду, где он помещается. Каждый масштабированный делитель — исходный, умноженный на степень двойки, поэтому он не несёт ошибки округления. Каждое вычитание снимает число от половины до всего текущего остатка — тот случай, когда, по лемме Стербенза, вычитание IEEE 754 обходится без округления. Результат точен. Дальше действует знаковое правило FormCalc: остаток берёт знак делимого, поэтому Mod(-7, 3) даёт -1, а Mod(7, -3) даёт 1. Делимое меньше делителя по модулю возвращается без изменений, а нулевой делитель не даёт никакого числа

FormCalc Mod в Delphi с HotPDF: формула через частное ломается на 1E20, а двоичное длинное деление удваивает делитель и вычитает точно
частное около 1.43E19 уже сидит на грубой сетке Double, а двоичное длинное деление добирается до точного остатка, не строя частного
// Точный остаток с плавающей точкой, знак делимого, частное не нужно
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;                   // крупнейшая кратная степень двойки
  while Step > Divisor do
  begin
    if Result >= Step then
      Result := Result - Step;          // точно: 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 усекает свой индекс, HasValue игнорирует пробелы

Choose(n, item1, item2, …) конвертирует свой первый аргумент в число и усекает его, поэтому Choose(2.7, "a", "b", "c") возвращает "b" и не поднимает ошибки типа. Индекс ниже 1 или за последним элементом возвращает пустую строку, а null-индекс возвращает null. HasValue — функциональная форма, которой авторы проверяют необязательные поля: она отвечает 0 на null и на текст, состоящий только из пробельных символов Unicode. Число 0 всё ещё считается. Поле количества с 0 заполнено; поле комментариев с тремя пробелами — нет, хотя пробельные текстовые значения XFA переживают сохранение нетронутыми. Вместе две функции дают обычную защиту необязательных позиций, if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif, которая оставляет незаполненную строку пустой и держит итог колонки в пределах введённого. Перенос на Delphi, читающий пустое количество как 0, печатает итог строки 0.00 там, где форма не печатает ничего

Что FormCalc возвращает для пустого поля?

Null — и null переживает большинство функций, которые вызывает calculate-скрипт. В FormCalc пустая строка — настоящее значение, null — её отсутствие, и строковые функции держат их порознь:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim и Space возвращают null, когда их аргумент null
  • Left, Right, At и Replace проверяют свои первые два аргумента, Stuff — первые три, а Substr — каждый переданный
  • Пустая строка, переданная любой из них, обрабатывается как текст: Upper("") — это "", а не null
  • Скрипты могут получить null явно — литералом null или вызовом Null()

У строк Delphi нет null, и именно здесь переносимые вручную порты уплывают дальше всего. Concat стоит вне списка: он пропускает null-аргументы, поэтому Concat(Prefix, Code) при незаполненном префиксе даёт тот же текст, который порт соберёт из ''. Len — нет. Len(Prefix) — null, и связанное с ним числовое поле остаётся пустым, тогда как Length('') кладёт туда 0. Агрегаты следуют правилу пропуска: Sum, Avg, Count, Min и Max игнорируют пустые записи, поэтому Avg по 10, пустой строке и 20 — это 15, а Count — 2. Порт, читающий пустую строку как 0, отчитается средним 10. Колонка, куда не ввели ничего, не даёт Sum никакого значения, и поле общего итога остаётся пустым

Карта распространения null для FormCalc в Delphi с HotPDF: строковые функции возвращают null, агрегаты пропускают пустые записи, а HasValue считает текст из пробелов незаполненным
null продолжает движение через Len и агрегаты, тогда как Concat и Sum его пропускают, поэтому порт должен моделировать поля как Variant, а не схлопывать null в пустую строку
uses
  Variants;

// Avg в стиле FormCalc: пустые записи пропускаются, а не считаются нулём
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     чтение пустой записи как 0 даёт 10
// FormCalcAvg([Null, Null])   = Null   поле среднего остаётся пустым

Моделируйте поля в порте как Variant и держите Null отдельно от ''. Значения, вытащенные из датасета, требуют той же осторожности: TField.Value возвращает Null для колонки NULL, тогда как TField.AsString превращает его в пустую строку и стирает разницу ещё до того, как её увидит порт

Пусть форма исполняет свои собственные скрипты

Самый безопасный перенос — часто никакой перенос вовсе. THotPDF.FlattenLoadedXFA вычисляет calculate-скрипт каждого поля, пока раскладывает форму, и пересобирает поля как поля AcroForm, применяя правила округления, остатка и null выше. Тот же вызов закрывает и остальное в сглаживании XFA в AcroForm, от раскладки до сопоставления виджетов. Формула, которую нельзя вычислить, — неразрешённая ссылка, деление на ноль, ошибка разбора — падает целиком. Ничто вычисленное наполовину до поля не добирается. Перезагрузка сглаженного файла и сравнение его значений полей с выводом порта превращает смутное расхождение в список имён полей:

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;      // '' против '0.00' — настоящее расхождение
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 = поля становятся 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;

Прочтите предупреждения, прежде чем верить любому итогу; список называет каждый элемент, который конверсия не смогла смаппить, так что ищите записи, называющие вычисляемое поле. Затем дайте порту образец, собранный под правила выше: суммы позиций, попадающие на .5 во втором знаке, 20-значный номер счёта, прогнанный через Mod, Round с дробным числом знаков и одна необязательная строка, оставленная пустой. Каждая строка, которую напечатает процедура, — правило, которое порт понимает неверно. Формы, вычисляющие через форматные и calculate-скрипты AcroForm, следуют числовым правилам JavaScript — Math.round(-2.5) там равен -2, третий ответ на тот же вопрос

Если та цифра, что нужна вашему сервису, — одна из тех, что форма уже печатает, берите её из формы: сгладьте её PDF-компонентом HotPDF для Delphi, перезагрузите результат и прочтите поле. Вспомогательные функции выше окупаются только на числах, которые форма никогда не вычисляет