기술 문서

FormCalc의 Round·Mod·Null은 Delphi와 다릅니다

청구서 폼이 Round(Subtotal * 0.025, 2)로 추가 요금을 계산하는데, 합계를 재검산하는 Delphi 서비스는 반 센트 줄에서 flatten된 PDF와 의견이 어긋납니다. FormCalc는 0.5 타이를 0에서 멀어지는 쪽으로 반올림하고 Double을 반환하는 반면 System.Round는 짝수로 반올림하므로, 믿을 수 있는 검사는 HotPDF가 XFA 폼을 flatten하고 FormCalc 스크립트를 실행하게 두는 것입니다

0에서 멀어지는 타이 처리, 그리고 결과는 Double로 남습니다

Delphi의 System.Round는 FPU 반올림 모드를 따르고, 기본 모드는 0.5 타이를 짝수로 반올림합니다. Round(2.5)는 2, Round(3.5)는 4, Round(-2.5)는 -2죠. banker's rounding은 통계에는 어울리지만 늘 3을 보여 온 폼에는 나쁜 짝입니다. FormCalc의 Round는 0.5 타이를 0에서 멀어지는 쪽으로 가져가므로 2.5는 3이 되고 -2.5는 -3이 됩니다. 반환 타입도 다릅니다. System.Round는 Int64를 반환하니, 익숙한 관용구 Round(X * 100) / 100이 X * 100이 Int64 범위를 벗어나는 순간 넘쳐버리는 이유이며, FormCalc의 Round(X, 2)는 Double을 받아 Double을 돌려줍니다

HotPDF와 함께하는 Delphi XFA 폼의 반올림 매트릭스: FormCalc Round는 2.5를 0에서 멀어지는 3으로 가져가고 System.Round는 2를 줍니다
FormCalc는 0.5 타이를 0에서 멀어지는 쪽으로 가져가고 Double을 반환하므로, System.Round가 2로 답하는 곳에서 2.5는 3이 됩니다

큰 값에는 규칙이 하나 더 필요합니다. Double은 명시적 fraction 비트 52개를 지니므로, 크기가 252(4,503,599,627,370,496) 이상이면 반올림할 fractional 부분이 남지 않습니다. HotPDF는 절댓값을 10places로 스케일하고, 스케일된 값이 252에 닿으면 입력을 그대로 돌려줍니다. 더 곱하는 것은 숫자를 지어내거나 넘쳐버릴 뿐이니까요. binary 저장이 다른 한계를 정하는데, 이는 Double 기반 어떤 평가기에도, FormCalc를 포함해 적용됩니다. literal 2.675는 2.67499999999999982236431605997495353221893310546875로 저장됩니다. 두 자리로 반올림하면 2.67이죠. FormCalc에는 decimal로 정확한 화폐 타입이 없으므로, 폼과 포트가 서로 합의할 수 있는 것은 둘이 함께 지닌 binary 값뿐입니다

uses
  Math;

// Delphi 포트를 위한 FormCalc식 Round: 0.5 타이는 0에서 멀어지는 쪽으로,
// 자릿수는 0 방향으로 잘라 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);                         // 반올림할 fractional 자릿수가 남지 않았습니다
  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를 넘칩니다)

FormCalc Round는 몇 자리 소수까지 받는가

0부터 12까지의 정수 자릿수입니다. HotPDF는 둘째 인자를 0 방향으로 잘라 그 범위로 묶으므로, Round(X, 2.7)은 두 자리로, Round(X, 15)는 열두 자리로, Round(X, -2)와 Round(X, -0.5)는 모두 정수로 반올림합니다. 이 규칙은 HotPDF가 FormCalc를 평가하는 곳이라면 어디서나 같으므로, flatten 중에 계산된 합계와 폼이 채워지는 동안 계산된 합계는 똑같이 나옵니다. 스프레드시트 습관은 반대쪽으로 끕니다. Excel의 ROUND(1234.5, -2)는 1200을 줍니다. Excel은 음수 자릿수를 소수점 왼쪽 자리로 읽기 때문이죠. FormCalc는 1235를 줍니다. Delphi의 헬퍼는 관례를 한 번 더 뒤집습니다. Math.RoundTo와 SimpleRoundTo는 10의 거듭제곱을 받으므로 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는 반올림 오류가 남긴 무엇이든 돌려줍니다. Delphi의 mod 연산자는 정수에만 동작하고 Trunc는 Int64 범위를 넘는 몫을 담지 못합니다. 여기에 기대기 전에 System.Math.FMod를 검증하세요. 몫에서 나머지를 유도하는 구현은 같은 오류를 물려받으며, FMod(1E20, 7)을 기대값 2와 비교하면 한 줄로 문제가 정리됩니다

binary long division은 몫을 전혀 만들지 않습니다. 제수가 피제수의 절반을 지나칠 때까지 제수를 두 배로 늘리고, 다시 내려오면서 스케일된 제수가 들어맞는 곳마다 뺍니다. 스케일된 제수는 모두 원래 값에 2의 거듭제곱을 곱한 것이므로 반올림 오류를 실지 않습니다. 모든 뺄셈은 현재 나머지의 절반부터 전부 사이의 수를 뺍니다. Sterbenz lemma에 따라 IEEE 754 뺄셈이 반올림을 수반하지 않는 경우죠. 결과는 정확합니다. 이어서 FormCalc의 부호 규칙이 적용됩니다. 나머지는 피제수의 부호를 따르므로 Mod(-7, 3)은 -1이고 Mod(7, -3)은 1입니다. 크기가 제수보다 작은 피제수는 그대로 돌아오고, 0 제수는 아무 숫자도 내주지 않습니다

HotPDF와 함께하는 Delphi의 FormCalc Mod: 몫 공식은 1E20에서 실패하지만 binary long division은 제수를 두 배로 늘려 정확히 뺍니다
1.43E19 근처의 몫은 이미 성긴 Double 격자 위에 놓여 있지만, binary long division은 몫을 만들지 않고 정확한 나머지에 도달합니다
// 정확한 부동소수점 나머지, 피제수의 부호, 몫은 필요 없습니다
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;                   // 가장 큰 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 아래나 마지막 항목을 넘는 인덱스는 빈 string을 반환하고, null 인덱스는 null을 반환합니다. HasValue는 작성자가 선택적 필드를 검사하는 데 쓰는 함수 형태입니다. null과 Unicode 공백으로만 이루어진 텍스트에 0으로 답하죠. 숫자 0은 여전히 세어 집니다. 0을 담은 수량 필드는 채워진 것이고, 공백 셋을 담은 비고 상자는 아닙니다. XFA 공백 텍스트 값이 저장을 거쳐도 그 공백들을 온전히 지켜 주더라도 말입니다. 두 함수를 함께 쓰면 선택적 품목 줄의 평범한 가드가 됩니다. if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif은 채워지지 않은 줄을 비워 두고 열 합계를 입력된 것으로 한정합니다. 빈 수량을 0으로 치는 Delphi 포트는 폼이 아무것도 인쇄하지 않는 곳에 0.00 줄 합계를 인쇄합니다

FormCalc는 빈 필드에 무엇을 반환하는가

Null입니다. 그리고 null은 calculate 스크립트가 부르는 대부분의 함수를 살아 관통합니다. FormCalc에서 빈 string은 실제 값이고 null은 그 부재이며, string 함수들은 둘을 구분합니다:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim, Space는 인자가 null이면 null을 반환합니다
  • Left, Right, At, Replace는 처음 둘의 인자를 검사하고, Stuff는 처음 셋을, Substr은 주어진 모든 인자를 검사합니다
  • 어떤 함수에든 넘겨진 빈 string은 텍스트로 처리됩니다. Upper("")는 ""이지 null이 아닙니다
  • 스크립트는 null literal이나 Null()로 null을 명시적으로 만들 수 있습니다

Delphi string에는 null이 없고, 손으로 쓴 포트가 가장 멀리 표류하는 지점이 바로 여기입니다. Concat은 목록 바깥에 있습니다. null 인자를 건너뛰므로 채워지지 않은 prefix에 대한 Concat(Prefix, Code)는 포트가 ''에서 만드는 것과 같은 텍스트를 내놓습니다. Len은 그렇지 않습니다. Len(Prefix)는 null이고 그에 묶인 숫자 필드는 빈 채로 남지만, Length('')는 그곳에 0을 놓습니다. 집계 함수들은 건너뛰기 규칙을 따릅니다. Sum, Avg, Count, Min, Max는 빈 항목을 무시하므로 10, 빈 줄, 20에 대한 Avg는 15이고 Count는 2입니다. 빈 줄을 0으로 읽는 포트는 평균 10을 보고하죠. 아무것도 입력되지 않은 열은 Sum에 값을 아예 주지 않으므로 총합 필드는 빈 채로 남습니다

HotPDF와 함께하는 Delphi FormCalc의 null 전파 지도: string 함수는 null을 반환하고, 집계 함수는 빈 항목을 건너뛰며, HasValue는 공백 텍스트를 미입력으로 칩니다
null은 Len과 집계 함수를 관통해 계속 움직이는 반면 Concat과 Sum은 이를 건너뛰므로, 포트는 null을 빈 string으로 뭉개 버리는 대신 필드를 Variant로 모델링해야 합니다
uses
  Variants;

// FormCalc식 Avg: 빈 항목은 건너뛰며 0으로 세지 않습니다
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은 그것을 빈 string으로 바꿔 포트가 보기도 전에 차이를 지워 버립니다

폼이 자기 스크립트를 실행하게 두기

가장 안전한 포트는 종종 포트 자체를 만들지 않는 것입니다. THotPDF.FlattenLoadedXFA는 폼을 배치하면서 각 필드의 calculate 스크립트를 평가하고 필드들을 AcroForm 필드로 재건하며, 위의 반올림, 나머지, null 규칙을 적용합니다. 같은 호출이 XFA를 AcroForm으로 flatten하기의 나머지도 처리합니다. 레이아웃부터 widget 맵핑까지죠. 평가할 수 없는 수식 — 풀리지 않은 참조, 0으로 나누기, 파스 오류 — 는 전체로서 실패합니다. 반쯤 계산된 무엇도 필드에 닿지 않습니다. flatten된 파일을 다시 읽어 필드 값을 포트의 출력과 비교하면 막연한 불일치가 필드 이름 목록으로 바뀝니다:

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 = 필드가 읽기 전용이 됩니다
    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;

합계를 믿기 전에 경고를 읽으세요. 목록은 변환이 맵핑하지 못한 모든 요소를 이름으로 말해 주므로, calculated 필드를 이름으로 부르는 항목을 찾으세요. 그다음에는 위 규칙에 맞춰 만든 샘플을 포트에 주세요. 둘째 소수 자리에서 .5에 걸리는 줄 금액, Mod를 통과하는 20자리 계좌 번호, fractional 자릿수를 지닌 Round, 그리고 비워 둔 선택적 줄 하나. 절차가 인쇄하는 모든 줄은 포트가 틀리게 치는 규칙입니다. AcroForm format과 calculate 스크립트로 계산하는 폼은 JavaScript 숫자 규칙을 따릅니다. 거기서 Math.round(-2.5)는 -2로, 같은 질문에 대한 세 번째 답이죠

서비스가 필요로 하는 수치가 폼이 이미 인쇄하는 것이라면 폼에서 가져오세요. HotPDF Delphi PDF component로 flatten하고 결과를 다시 읽어 필드를 읽으면 됩니다. 위의 헬퍼 함수들은 폼이 결코 계산하지 않는 숫자에만 제 몫을 합니다