Funções

ParseInput

ParseInput é a função principal da biblioteca. Analisa um texto bruto string de acordo com um tipo de dados declarado e devolve um registo TParseResult contendo os valores analisados, literais SQL e um fragmento de comparação SQL pronto a utilizar.

São fornecidas cinco sobrecargas. A sobrecarga 1 é a forma completa e é segura para threads. As sobrecargas 2–5 são formas de conveniência que utilizam o dialeto global predefinido definido por SetSQLDialect.

Sobrecarga 1 — forma completa (segura para threads)

function ParseInput(
  const Input : *string*;
 ValueType  : TInputType;
 RangeSep   : Char;
        Options    : TParseOptions;
 SqlOperator: TSqlOperator;
 SqlDialect : TSqlDialect): TParseResult;

Todos os parâmetros são fornecidos pelo chamador. O dialeto global predefinido nunca é lido; cada chamada é totalmente independente e segura para utilização a partir de qualquer thread.

Sobrecarga 2

function ParseInput(
  const Input : *string*;
 ValueType  : TInputType;
 Options    : TParseOptions;
 SqlOperator: TSqlOperator): TParseResult;

RangeSep tem como valor predefinido '~'. Utiliza GDefaultDialect.

Sobrecarga 3

function ParseInput(
  const Input    : *string*;
        ValueType: TInputType;
 Options  : TParseOptions): TParseResult;

RangeSep tem como valor predefinido '~', SqlOperator tem como valor predefinido sopEqual. Utiliza GDefaultDialect.

Sobrecarga 4

function ParseInput(
  const Input : *string*;
 ValueType  : TInputType;
 SqlOperator: TSqlOperator): TParseResult;

RangeSep tem como valor predefinido '~', Options tem como valor predefinido []. Utiliza GDefaultDialect.

Sobrecarga 5 — forma mínima

function ParseInput(
  const Input    : *string*;
        ValueType: TInputType): TParseResult;

RangeSep tem como valor predefinido '~', Options tem como valor predefinido [], SqlOperator tem como valor predefinido sopEqual. Utiliza GDefaultDialect.

Parâmetros

Parâmetro Tipo Descrição
Input *string* Texto bruto proveniente do controlo da interface do utilizador. Pode conter espaços, aspas, separadores de lista ou o separador de intervalo.
ValueType TInputType O tipo de dados que a entrada deve representar.
RangeSep Char Carácter que separa os dois limites de um intervalo. Padrão: '~'. Não pode ser ',', ';', '-', '.', '''' (aspas simples) ou ' ' (espaço); qualquer um destes provoca ERR_INVALID_RANGESEP.
Options TParseOptions Conjunto de sinalizadores TParseOption. Valor predefinido: [].
SqlOperator TSqlOperator Operador de comparação para SQLExpression. Padrão: sopEqual.
SqlDialect TSqlDialect Dialeto SQL para formatação de literais (apenas sobrecarga 1).

Valor de retorno

Um registo TParseResult. O ParseInput nunca lança uma exceção em compilações de lançamento; todas as condições de erro são comunicadas através de TParseResult.ErrorCode e TParseResult.ResultType = otInvalid. Consulte Tipos e constantes para obter a referência completa dos campos e Códigos de erro para orientações sobre o tratamento de erros.

Comportamento de NULL e de tokens vazios

Um token vazio dentro de uma lista (por exemplo, 1,,3) produz NULL em SQL para todos os tipos de entrada tipados (itInteger, itDecimal, itFloat, itBoolean, itDate, itTime, itDateTime), e um string vazio entre aspas '' para itString (a menos que opEmptyStringNull esteja definido). Exemplo: a entrada 1,,3 com itInteger produz IN (1, NULL, 3).

Um limite de intervalo vazio produz igualmente NULL. BETWEEN NULL AND x, BETWEEN x AND NULL e BETWEEN NULL AND NULL são sintaticamente válidos em SQL, mas nunca corresponderão a qualquer linha, uma vez que qualquer comparação com NULL resulta em UNKNOWN. Não é gerado qualquer erro; utilize opNotNull para rejeitar tokens vazios se um limite NULL não for aceitável.

Segurança de threads

A sobrecarga 1 é segura para threads; as sobrecargas 2–5 leem a variável global GDefaultDialect e só são seguras quando SetSQLDialect não é chamado em simultâneo. Consulte Segurança de threads para obter a análise completa e os padrões recomendados.

SetSQLDialect

procedure SetSQLDialect(Dialect: TSqlDialect);

Define o dialeto global predefinido utilizado pelas sobrecargas 2–5 de ParseInput. O valor predefinido no arranque da aplicação é sqlElevateDB. Consulte TSqlDialect. Não é seguro para threads: não chame este procedimento enquanto outras threads possam estar a chamar as sobrecargas 2 a 5.

GetSQLDialect

função GetSQLDialect: TSqlDialect;

Devolve o dialeto global predefinido atual. O valor devolvido reflete a última chamada a SetSQLDialect, ou a sqlElevateDB se SetSQLDialect nunca tiver sido chamado. Não é seguro para threads pela mesma razão que SetSQLDialect.

(C) 2026 Easygate, Lda