Artículo técnico

Round, Mod y Null de FormCalc no son Round y mod de Delphi

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

Medios lejos de cero, y el resultado sigue siendo un Double

El System.Round de Delphi sigue el modo de redondeo de la FPU, y el modo por defecto 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 va bien para estadísticas. Es un mal encaje para un formulario que siempre ha mostrado 3. El Round de FormCalc lleva los medios lejos de cero, así que 2.5 se convierte en 3 y -2.5 en -3. El tipo de retorno también difiere. System.Round devuelve un Int64, razón por la que el modismo conocido Round(X * 100) / 100 desborda en cuanto X * 100 sale del rango Int64, mientras que el Round(X, 2) de FormCalc toma un Double y devuelve otro

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

Los valores grandes necesitan una regla más. Un Double tiene 52 bits explícitos de fracción, así que una magnitud de 252 (4.503.599.627.370.496) o más no deja 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 desbordaría. El almacenamiento binario pone el otro límite, y ese se aplica a cualquier evaluador basado en Double, FormCalc incluido. El literal 2.675 se guarda como 2.67499999999999982236431605997495353221893310546875. Redondeado a dos decimales da 2.67. FormCalc no tiene un tipo monetario exacto decimal, así que un formulario y un port solo pueden coincidir en el valor binario que ambos sostienen

uses
  Math;

// Round estilo FormCalc para un port Delphi: medios lejos de cero,
// recuento de decimales truncado hacia cero y retenido en 0..12, el resultado sigue siendo 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 places count as 2)
// FormCalcRound(1234.5, -2)     = 1235     (a negative count means 0 places)
// FormCalcRound(1E18, 2)        = 1E18     (Round(1E18 * 100) overflows Int64)

¿Cuántos decimales acepta el Round de FormCalc?

Decimales enteros de 0 a 12. HotPDF trunca el segundo argumento hacia cero y luego lo retiene en ese rango, así que Round(X, 2.7) redondea a dos decimales, 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 otro calculado mientras se rellena el formulario salen idénticos. Los hábitos de hoja de cálculo tiran para el otro lado. El ROUND(1234.5, -2) de Excel da 1200 porque Excel lee un recuento negativo como dígitos a la izquierda del punto decimal; FormCalc da 1235. Los ayudantes de Delphi invierten la convención una vez más: 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 directamente en RoundTo imprime centenas donde el formulario muestra céntimos. Deja el recuento de decimales como lo define FormCalc y pásalo por un ayudante como FormCalcRound, que además mantiene bien la regla de los medios

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

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

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

FormCalc Mod en Delphi con HotPDF: la fórmula del cociente falla en 1E20 mientras la división larga binaria duplica el divisor y resta exactamente
el cociente cerca de 1.43E19 ya se sienta en una retícula Double gruesa, mientras la división larga binaria alcanza el resto exacto sin formar cociente
// Resto de coma flotante exacto, 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 mayor múltiplo potencia de dos
  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 blancos

Choose(n, item1, item2, …) convierte su primer argumento en número y lo trunca, así que Choose(2.7, "a", "b", "c") devuelve "b" y no levanta ningún error de tipo. Un índice por debajo de 1 o más allá del último elemento devuelve una cadena vacía, y un índice null devuelve null. HasValue es la forma funcional que los autores usan para probar campos opcionales: responde 0 para null y para texto hecho solo de whitespace Unicode. El número 0 todavía cuenta. Un campo de cantidad que guarda 0 está rellenado; una caja de comentarios que guarda tres espacios no, aunque los valores de texto whitespace de XFA conserven esos espacios intactos en un guardado. Juntas, las dos funciones dan la guarda habitual para líneas opcionales, if (HasValue(Qty)) then Round(Qty * Price, 2) else null endif, que deja vacía una línea sin rellenar y mantiene el total de la columna limitado a lo introducido. 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 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 los dos separados:

  • Len, Upper, Lower, Ltrim, Rtrim, Trim y Space devuelven null cuando su argumento es null
  • Left, Right, At y Replace comprueban sus dos primeros argumentos, Stuff sus tres primeros, 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()

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

Mapa de propagación de null para FormCalc en Delphi con HotPDF: las funciones de cadena devuelven null, los agregados saltan las entradas vacías, y HasValue trata el texto de whitespace como sin rellenar
null sigue moviéndose por Len y los agregados mientras Concat y Sum lo saltan, así que un port debe modelar los campos como Variant en vez de colapsar null en 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 de media se queda en blanco

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

Deja que el formulario ejecute 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 maqueta el formulario y reconstruye los campos como campos AcroForm, aplicando las reglas de redondeo, resto y null de arriba. La misma llamada se encarga del resto de la conversión de XFA a AcroForm, de la maquetación al mapeo de widgets. Una fórmula que no se puede evaluar —una referencia sin resolver, una división por 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 campo:

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 pasan a ser 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;

Lee los avisos antes de fiarte de cualquier total; la lista nombra cada elemento que la conversión no pudo mapear, así que busca entradas que nombren un campo calculado. Luego dale al port una muestra construida para las reglas de arriba: importes de línea que caigan en .5 en el segundo decimal, un número de cuenta de 20 dígitos pasado por Mod, un Round con recuento de decimales 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 numéricas de JavaScript —allí Math.round(-2.5) es -2, una tercera respuesta a la misma pregunta

Si la cifra que tu servicio necesita es una que el formulario ya imprime, tómala del formulario: aplánalo con el componente PDF de HotPDF para Delphi, recarga el resultado y lee el campo. Las funciones ayudantes de arriba se ganan el sueldo solo para los números que el formulario nunca calcula