Notação de Fórmulas R1C1 em Delphi com o HotXLS

O HotXLS compila fórmulas escritas na notação de referências R1C1 através do método TXLSCalculator.GetCompiledFormulaR1C1, que suporta formatos como R2C3 (absoluto), R[-1]C[2] (desvio relativo) e RC (a célula corrente), convertendo-os para notação A1 em função da linha e coluna de destino e submetendo o resultado ao compilador padrão A1. Para aplicações em Delphi e C++Builder que escrevem a mesma fórmula lógica ao longo de centenas de linhas, esta rotina elimina falhas associadas à concatenação de strings

Estes erros ocorrem com frequência no preenchimento de colunas via código. Em ciclos que desenham fórmulas A1 concatenando strings como Format('D%d*E%d', [Row, Row]), a única variável é o número da linha. Basta um desvio de índice incorreto, confundir ciclos de índice zero com coordenadas A1 de base 1 ou ignorar uma linha de cabeçalho para deslocar todos os cálculos do intervalo. Nenhuma exceção é gerada e os valores resultantes surgem errados. A fórmula lógica pretendida — "multiplicar as duas células à minha esquerda" — não necessita de números de linhas físicos, sendo exatamente esta a simplificação que a notação R1C1 oferece

O que é a notação R1C1 e quando deve ser utilizada?

A notação R1C1 endereça células por número de linha e coluna (em vez de letras de colunas e números de linhas), representando as coordenadas relativas sob a forma de desvios (offsets) explícitos a partir da célula onde reside a fórmula. O termo R2C3 refere a coordenada absoluta na linha 2, coluna 3 (que em A1 equivale a $C$2). R[-1]C[2] representa uma linha acima e duas colunas à direita da célula da fórmula. O identificador RC aponta para a própria célula. Os desvios entre parênteses retos garantem que a redação R1C1 é constante, independentemente da célula de destino, ao contrário da representação A1 que varia a cada linha

Esta notação revela-se útil sobretudo em cenários de geração de relatórios com modelos (templates), onde a mesma fórmula lógica é aplicada a todas as linhas de um intervalo. Em A1, exige-se construir a string da fórmula para cada linha; em R1C1, o texto da fórmula mantém-se constante. Esta lógica assemelha-se à estrutura interna dos ficheiros de folhas de cálculo: as fórmulas partilhadas (shared formulas) são registadas internamente como desvios geométricos, pelo que concatenar caminhos A1 obriga o analisador a descodificá-los novamente em desvios. O uso de R1C1 simplifica este fluxo. Para interações manuais, a notação A1 continua a ser a escolha intuitiva, mantendo-se como padrão no HotXLS

Como o HotXLS compila fórmulas R1C1?

O HotXLS expõe esta funcionalidade a dois níveis (desde a versão v2.175.0). A chamada TXLSCalculator.GetCompiledFormulaR1C1(UncompiledFormula: String; SheetID, CurRow, CurCol: Integer): TXLSCompiledFormula devolve uma fórmula compilada pronta para execução (equivalente a GetCompiledFormula), contendo dois argumentos extra com o índice da linha e da coluna de destino (base 0). Internamente, TXLSFormula.GetCompiledR1C1 constrói a árvore sintática e o método isolado R1C1ToA1(const AFormula: String; CurRow, CurCol: Integer): String trata a tradução do formato. A lógica consiste em converter o texto R1C1 para A1 com base nas coordenadas da célula host e compilar o resultado no motor padrão (que gere também nomes definidos e referências cruzadas e executa funções personalizadas)

Uma vez que a conversão precede a compilação, o processamento posterior decorre como se a fórmula tivesse sido escrita em A1. A chamada R1C1ToA1('R2C3', 4, 3) devolve '$C$2' independentemente da célula de destino (por possuir coordenadas absolutas). A chamada R1C1ToA1('SUM(R[-3]C[0]:R[-1]C[0])', 4, 3) — que descreve uma fórmula na célula D5 (sendo CurRow = 4 e CurCol = 3 base 0) — devolve 'SUM(D2:D4)', calculando as distâncias a partir de D5. Os intervalos são convertidos convertendo cada extremidade individualmente:

// The formula lives in D5: CurRow = 4, CurCol = 3 (both 0-based)
S := R1C1ToA1('R2C3', 4, 3);
// S = '$C$2'  (linha e coluna absolutas)

S := R1C1ToA1('SUM(R[-3]C[0]:R[-1]C[0])', 4, 3);
// S = 'SUM(D2:D4)'  (desvios calculados a partir de D5)

S := R1C1ToA1('ROUND(R[-1]C[0], 2)', 4, 3);
// S = 'ROUND(D4, 2)'  (o carácter R em ROUND é ignorado)

Preencher uma coluna com uma única fórmula relativa

Compare o modelo A1 (que reconstrói o texto da fórmula a cada iteração) com o formato R1C1 (onde o texto da fórmula é uma constante e apenas variam as coordenadas da célula). Ambas as abordagens são compiladas em TXLSCalculator e executadas por GetValue. O calculador aceita uma rotina de callback (cell provider) para ler valores das células a partir da origem de dados:

// Modelo A1: uma string de fórmula diferente por linha
for Row := 1 to 500 do
begin
  FormulaText := Format('D%d*E%d', [Row + 1, Row + 1]);  // linhas A1 base 1
  Compiled := Calc.GetCompiledFormula(FormulaText, 0);
  // ... avaliar, guardar, libertar ...
end;

const
  AmountFormula = 'RC[-2]*RC[-1]';  // duas células à esquerda, na mesma linha
var
  Calc: TXLSCalculator;
  Compiled: TXLSCompiledFormula;
  Value: Variant;
  Row: Integer;
begin
  Calc := TXLSCalculator.Create(nil, Provider.GetValue);
  try
    for Row := 1 to 500 do
    begin
      Compiled := Calc.GetCompiledFormulaR1C1(AmountFormula, 0, Row, 5);
      try
        if Calc.GetValue(0, Compiled, Row, 5, Value, 1) = lxOk then
          StoreResult(Row, 5, Value);
      finally
        Compiled.Free;
      end;
    end;
  finally
    Calc.Free;
  end;
end;

O ciclo R1C1 não exige operações aritméticas na string da fórmula. O argumento 'RC[-2]*RC[-1]' descreve a multiplicação das duas células à esquerda na mesma linha, tanto na linha 2 quanto na linha 500. Se a tabela recuar uma linha, o texto da fórmula permanece inalterado (apenas os limites do ciclo variam). Enquanto o modelo A1 expõe o código a falhas de desfasamento na linha, a lógica R1C1 elimina essa probabilidade

Que sintaxe R1C1 é suportada pelo conversor?

O conversor R1C1ToA1 interpreta os formatos de v2.175.0: R[n]C[m] para desvios relativos em qualquer direção, RnCm para coordenadas absolutas, desvios negativos com R[-n]C[m], o identificador RC (a própria célula) e intervalos (como R1C1:R3C3 ou R[-1]C:R[1]C). O processamento de linhas e colunas é independente, suportando formatos mistos como R[1]C3 (linha relativa e coluna absoluta), sendo a leitura case-insensitive (como r[-1]c[2]). Coordenadas entre parênteses retos geram referências A1 relativas, e números isolados geram coordenadas absolutas com $

A distinção de tokens evita que as letras R e C (comuns em fórmulas) sejam interpretadas incorretamente. A letra R só inicia uma referência se não for antecedida por outras letras e respeitar a estrutura (linha opcional, C obrigatório, coluna opcional). Por isso, ROUND(R[-1]C[0], 2) converte apenas a referência interna: a letra R em ROUND é seguida por O, falhando a validação e mantendo o nome da função intacto. A mesma lógica protege ROW(), e funções iniciadas por C nunca são tidas como candidatas. Literais e strings de texto são ignorados; contudo, se possuir strings literais estruturadas exatamente como coordenadas R1C1, convém validar o resultado da compilação

Coordenadas e particularidades de ancoragem

Os argumentos CurRow and CurCol em GetCompiledFormulaR1C1 baseiam-se em 0 (conforme a API do calculador), enquanto os números na notação R1C1 baseiam-se em 1 (conforme a visualização do Excel): R2C3 é a linha 2, coluna 3 (ou seja, $C$2 e não $D$3). Se o contador do ciclo for base 0, passe-o diretamente para o argumento; a correção de + 1 é efetuada no conversor

Se a fórmula compilada persistir após o ciclo, note que a omissão de coordenadas (como RC[-1] ou R[2]C) resolve para a própria linha/coluna, gerando coordenadas absolutas (com $) na tradução A1. Isto é transparente na avaliação dos valores, mas influencia o comportamento em inserções ou eliminações de linhas/colunas, conforme analisado no artigo sobre ajuste de referências de fórmulas. Se necessitar que a coordenada se mantenha relativa em alterações estruturais, declare o desvio zero explicitamente (ex: R[0]C[-1] em vez de RC[-1]) para gerar coordenadas A1 relativas

A compilação R1C1 integra o motor de cálculo do HotXLS Delphi Excel Component, a par do compilador A1, grafos de dependências e APIs de avaliação