Artículo técnico

Round, Mod y null de FormCalc no son Round ni mod de Delphi

Un formulario de factura calcula un recargo con Round(Subtotal * 0.025, 2), y un servicio Delphi que verifica los totales discrepa del PDF aplanado en las líneas de medio centavo. FormCalc redondea los medios lejos de cero y devuelve un Double, mientras System.Round redondea al par, así que la verificación confiable es dejar que HotPDF aplane el formulario XFA y corra sus scripts FormCalc

Medios lejos de cero, y el resultado se queda Double

El System.Round de Delphi sigue el modo de redondeo de la FPU, y el modo por default redondea los medios al par: Round(2.5) es 2, Round(3.5) es 4 y Round(-2.5) es -2. El redondeo de banquero sirve para estadística. Para un formulario que siempre ha mostrado 3 es un pésimo ajuste. El Round de FormCalc lleva los medios lejos de cero, así que 2.5 se vuelve 3 y -2.5 se vuelve -3. El tipo de retorno también difiere. System.Round devuelve un Int64, razón por la que el idiom conocido Round(X * 100) / 100 se desborda en cuanto X * 100 sale del rango de Int64, mientras que el Round(X, 2) de FormCalc recibe un Double y devuelve otro

Matriz de redondeo para formularios XFA de Delphi con HotPDF: el Round de FormCalc lleva el 2.5 a 3 lejos de cero mientras System.Round da 2
FormCalc lleva los empates de medio lejos de cero y devuelve un Double, así que 2.5 se vuelve 3 donde System.Round responde 2

Los valores grandes necesitan una regla más. Un Double tiene 52 bits de fracción explícitos, así que una magnitud de 252 (4,503,599,627,370,496) o más ya no tiene parte fraccionaria que redondear. HotPDF escala el valor absoluto por 10places, y cuando el valor escalado alcanza 252 devuelve la entrada sin cambios, multiplicar más solo inventaría dígitos o se desbordaría. El almacenamiento binario pone el otro límite, y ese aplica a cualquier evaluador basado en Double, FormCalc incluido. El literal 2.675 se guarda como 2.67499999999999982236431605997495353221893310546875. Redondeado a dos lugares da 2.67. FormCalc no tiene un tipo de dinero exacto en decimal, así que un formulario y un port solo pueden coincidir en el valor binario que ambos cargan

uses
  Math;

// Round estilo FormCalc para un port Delphi: medios lejos de cero,
// conteo de lugares truncado hacia cero y limitado a 0..12, el resultado se queda 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);                         // no quedan dígitos fraccionarios que redondear
  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 lugares cuentan como 2)
// FormCalcRound(1234.5, -2)     = 1235     (un conteo negativo significa 0 lugares)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) se desborda de Int64)

¿Cuántos lugares decimales acepta el Round de FormCalc?

Lugares enteros de 0 a 12. HotPDF trunca el segundo argumento hacia cero y luego lo limita a ese rango, así que Round(X, 2.7) redondea a dos lugares, Round(X, 15) a doce, y tanto Round(X, -2) como Round(X, -0.5) a un número entero. La regla es la misma dondequiera que HotPDF evalúe FormCalc, así que un total calculado durante el aplanado y uno calculado mientras se llena el formulario salen idénticos. Los hábitos de hoja de cálculo jalan hacia el otro lado. El ROUND(1234.5, -2) de Excel da 1200 porque Excel lee un conteo negativo como dígitos a la izquierda del punto decimal; FormCalc da 1235. Los helpers de Delphi voltean la convención otra vez: Math.RoundTo y SimpleRoundTo toman una potencia de diez, así que RoundTo(X, -2) significa dos decimales y RoundTo(1234.567, 2) es 1200. Un port que copia el segundo argumento del script directo a RoundTo imprime centenas donde el formulario muestra centavos. Conserve el conteo de lugares tal como lo define FormCalc y páselo por un helper como FormCalcRound, que además mantiene bien la regla de empates

¿Por qué a - b * Int(a / b) devuelve el residuo equivocado?

Porque el cociente deja de ser exacto mucho antes que el dividendo. Tome Mod(1E20, 7). El dividendo es representable sin error, 1020 es 220 × 520, y 520 cabe en 53 bits, y el residuo verdadero es 2. El cociente, cerca de 1.43 × 1019, no: los Doubles en ese rango están separados 2,048 entre sí, así que Int(a / b) está mal antes de que la multiplicación siquiera empiece, y a - b * q devuelve lo que dejen los errores de redondeo. El operador mod de Delphi funciona solo sobre enteros, y Trunc no puede sostener un cociente más allá del rango de Int64. Pruebe System.Math.FMod antes de apoyarse en él aquí. Una implementación que deriva el residuo del cociente hereda el mismo error, y comparar FMod(1E20, 7) con el 2 esperado resuelve la pregunta en una línea

La división larga binaria jamás forma el cociente. Duplique el divisor hasta que pase la mitad del dividendo, luego regrese bajando, restando el divisor escalado donde quepa. Cada divisor escalado es el original por una potencia de dos, así que no arrastra error de redondeo. Cada resta se lleva un número entre la mitad y todo el residuo actual, el caso en el que, por el lema de Sterbenz, la resta IEEE 754 no involucra redondeo. El resultado es exacto. Después aplica la regla de signo de FormCalc: el residuo toma el signo del dividendo, así que Mod(-7, 3) es -1 y Mod(7, -3) es 1. Un dividendo de magnitud menor que el divisor regresa sin cambios, y un divisor cero no produce número alguno

Mod de FormCalc en Delphi con HotPDF: la fórmula del cociente falla en 1E20 mientras la división larga binaria duplica el divisor y resta con exactitud
el cociente cerca de 1.43E19 ya está parado sobre una retícula Double gruesa, mientras la división larga binaria llega al residuo exacto sin formar un cociente
// Residuo de punto flotante exacto, con el signo del dividendo, sin cociente
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;                   // el múltiplo potencia de dos más grande
  while Step > Divisor do
  begin
    if Result >= Step then
      Result := Result - Step;          // exacto: 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 trunca su índice, HasValue ignora los espacios

Choose(n, item1, item2, …) convierte su primer argumento a número y lo trunca, así que Choose(2.7, "a", "b", "c") devuelve "b" y no levanta error de tipo. Un índice abajo de 1 o más allá del último elemento devuelve una cadena vacía, y un índice null devuelve null. HasValue es la forma de función que los autores usan para probar campos opcionales: responde 0 para null y para texto hecho solo de espacios en blanco Unicode. El número 0 sí cuenta. Un campo de cantidad con 0 ya fue llenado; una caja de comentarios con tres espacios no, aunque los valores de texto con espacios en blanco de XFA mantengan esos espacios intactos tras un guardado. Entre las dos funciones dan el guardia de siempre para partidas opcionales, if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif, que deja vacía una línea sin llenar y mantiene el total de columna limitado a lo capturado. Un port Delphi que trata una cantidad vacía como 0 imprime un total de línea 0.00 donde el formulario no imprime nada

¿Qué devuelve FormCalc para un campo vacío?

Null, y el null sobrevive a la mayoría de las funciones que un script calculate llama. En FormCalc una cadena vacía es un valor real y null es su ausencia, y las funciones de cadena mantienen a los dos separados:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim y Space devuelven null cuando su argumento es null
  • Left, Right, At y Replace revisan sus primeros dos argumentos, Stuff sus primeros tres, y Substr cada argumento suministrado
  • Una cadena vacía pasada a cualquiera de ellas se procesa como texto: Upper("") es "", no null
  • Los scripts pueden producir null explícitamente con el literal null o con Null()

Los strings de Delphi no tienen null, y ahí es donde los ports escritos a mano más se descarrian. Concat está fuera de la lista: se salta los argumentos null, así que Concat(Prefix, Code) sobre un prefijo sin llenar produce el mismo texto que un port construye desde ''. Len no. Len(Prefix) es null y un campo numérico atado a él se queda en blanco, mientras Length('') pone un 0 ahí. Los agregados siguen la regla de saltar: Sum, Avg, Count, Min y Max ignoran las entradas vacías, así que un Avg sobre 10, una línea vacía y 20 es 15 y el Count es 2. Un port que lee la línea vacía como 0 reporta un promedio de 10. Una columna donde no se capturó nada no le da a Sum valor alguno, lo que mantiene vacío el campo del gran total

Mapa de propagación de null para FormCalc en Delphi con HotPDF: las funciones de cadena devuelven null, los agregados se saltan las entradas vacías, y HasValue trata el texto de espacios como sin llenar
el null sigue moviéndose a través de Len y los agregados mientras Concat y Sum lo saltan, así que un port debe modelar los campos como Variant en lugar de colapsar el null a una cadena vacía
uses
  Variants;

// Avg estilo FormCalc: las entradas vacías se saltan, no cuentan como cero
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     leer la entrada vacía como 0 da 10
// FormCalcAvg([Null, Null])   = Null   el campo del promedio se queda en blanco

Modele los campos como Variant en el port y mantenga Null aparte de ''. Los valores sacados de un dataset necesitan el mismo cuidado: TField.Value devuelve Null para una columna NULL, mientras TField.AsString la convierte en cadena vacía y borra la diferencia antes de que el port la vea

Deje que el formulario corra sus propios scripts

El port más seguro a menudo es ningún port. THotPDF.FlattenLoadedXFA evalúa el script calculate de cada campo mientras acomoda el formulario y reconstruye los campos como campos AcroForm, aplicando las reglas de redondeo, residuo y null de arriba. La misma llamada maneja el resto del aplanado de XFA a AcroForm, del layout al mapeo de widgets. Una fórmula que no se puede evaluar, una referencia sin resolver, una división entre cero, un error de parseo, falla como un todo. Nada a medio calcular llega al campo. Recargar el archivo aplanado y comparar los valores de sus campos con la salida del port convierte una discrepancia vaga en una lista de nombres de campos:

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;      // '' contra '0.00' es una discrepancia real
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 = los campos se vuelven de solo lectura
    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;

Lea los warnings antes de fiarse de cualquier total; la lista nombra cada elemento que la conversión no pudo mapear, así que busque entradas que nombren un campo calculado. Luego dele al port una muestra construida para las reglas de arriba: montos de línea que caen en .5 en el segundo decimal, un número de cuenta de 20 dígitos pasado por Mod, un Round con conteo de lugares fraccionario, y una línea opcional dejada vacía. Cada línea que el procedimiento imprime es una regla que el port hace mal. Los formularios que calculan con scripts format y calculate de AcroForm siguen las reglas de números de JavaScript, Math.round(-2.5) es -2 ahí, una tercera respuesta a la misma pregunta

Si la cifra que su servicio necesita es una que el formulario ya imprime, tómela del formulario: aplánelo con el componente PDF HotPDF para Delphi, recargue el resultado y lea el campo. Las funciones helper de arriba se ganan su lugar solo para los números que el formulario jamás calcula