Funções integradas do Firebird 3.0 (SDF, também conhecidas como Funções Definidas pelo Servidor)

As funções internas abaixo (exceto DECODE) são usadas somente se não houver

UDF declarada com o mesmo nome.

Essa escolha entre UDF e função do sistema é decidida ao compilar a

instrução e não é alterada se a instrução for armazenada (gatilho / SP).

Autores:

Adriano dos Santos Fernandes <[email protected]>

Oleg Loa <[email protected]>

Alexey Karyakin <[email protected]>

Claudio Valderrama C. <cvalde at usa.net>

---

ABS

---

Função:

Retorna o valor absoluto de um número.

Formato:

ABS( <número> )

Exemplo:

select abs(amount) from transactions;

----

ACOS

----

Função:

Retorna o arco cosseno de um número.

Formato:

ACOS( <número> )

Observações:

O argumento para ACOS deve estar no intervalo de -1 a 1 e retorna um valor no

intervalo de 0 a PI.

Exemplo:

select acos(x) from y;

---–

ACOSH

---–

Função:

Retorna o arco cosseno hiperbólico de um número (expresso em radianos).

Formato:

ACOSH( <número> )

Exemplo:

select acosh(x) from y;

---——-

ASCII_CHAR

---——-

Função:

Retorna o caractere ASCII com o código especificado.

Formato:

ASCII\_CHAR( <número> )

Observações:

O argumento para ASCII\_CHAR deve estar no intervalo de 0 a 255 e retorna um valor

com conjunto de caracteres NONE.

Exemplo:

select ascii\_char(x) from y;

---——

ASCII_VAL

---——

Função:

Retorna o código ASCII do primeiro caractere da string especificada.

Formato:

ASCII\_VAL( <string> )

Observações:

1) Retorna 0 se a string estiver vazia.

2) Lança erro se o primeiro caractere for multibyte.

Exemplo:

select ascii\_val(x) from y;

----

ASIN

----

Função:

Retorna o arco seno de um número.

Formato:

ASIN( <número> )

Observações:

O argumento para ASIN deve estar no intervalo de -1 a 1 e retorna um valor no

intervalo de -PI / 2 a PI / 2.

Exemplo:

select asin(x) from y;

---–

ASINH

---–

Função:

Retorna o arco seno hiperbólico de um número (expresso em radianos).

Formato:

ASINH( <número> )

Exemplo:

select asinh(x) from y;

----

ATAN

----

Função:

Retorna o arco tangente de um número.

Formato:

ATAN( <número> )

Observações:

Retorna um valor no intervalo de -PI / 2 a PI / 2.

Exemplo:

select atan(x) from y;

---–

ATAN2

---–

Função:

Retorna o arco tangente do primeiro número / o segundo número.

Formato:

ATAN( <número>, <número> )

Observações:

Retorna um valor no intervalo de -PI a PI.

Exemplo:

select atan2(x, y) from z;

---–

ATANH

---–

Função:

Retorna o arco tangente hiperbólico de um número (expresso em radianos).

Formato:

ATANH( <número> )

Exemplo:

select atanh(x) from y;

---—-

BIN_AND

---—-

Função:

Retorna o resultado de uma operação binária AND executada em todos os argumentos.

Formato:

BIN\_AND( <número>, <número> \[, <número> ...\] )

Exemplo:

select bin\_and(flags, 1) from x;

---—-

BIN_NOT

---—-

Função:

Retorna o resultado de uma operação bit a bit NOT executada em seu argumento.

Formato:

BIN\_NOT( <número> )

Exemplo:

select bin\_not(flags) from x;

---—

BIN_OR

---—

Função:

Retorna o resultado de uma operação binária OR executada em todos os argumentos.

Formato:

BIN\_OR( <número>, <número> \[, <número> ...\] )

Exemplo:

select bin\_or(flags1, flags2) from x;

---—-

BIN_SHL

---—-

Função:

Retorna o resultado de uma operação binária de deslocamento à esquerda executada nos argumentos (primeiro << segundo).

Formato:

BIN\_SHL( <número>, <número> )

Exemplo:

select bin\_shl(flags1, 1) from x;

---—-

BIN_SHR

---—-

Função:

Retorna o resultado de uma operação binária de deslocamento à direita executada nos argumentos (primeiro >> segundo).

Formato:

BIN\_SHR( <número>, <número> )

Exemplo:

select bin\_shr(flags1, 1) from x;

---—-

BIN_XOR

---—-

Função:

Retorna o resultado de uma operação binária XOR executada em todos os argumentos.

Formato:

BIN\_XOR( <número>, <número> \[, <número> ...\] )

Exemplo:

select bin\_xor(flags1, flags2) from x;

---———–

CEIL | CEILING

---———–

Função:

Retorna um valor representando o menor inteiro que é maior

ou igual ao argumento de entrada.

Formato:

{ CEIL \| CEILING }( <número> )

Exemplo:

1) select ceil(val) from x;

2) select ceil(2.1), ceil(-2.1) from rdb$database;  -- retorna 3, -2

---———

CHAR_TO_UUID

---———

Função:

Converte a representação ASCII CHAR(32) de um UUID

(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) para a representação CHAR(16) OCTETS

(otimizada para armazenamento).

Formato:

CHAR\_TO\_UUID( <string> )

Importante (para servidores big-endian):

Foi descoberto que antes do Firebird 2.5.2, CHAR\_TO\_UUID e UUID\_TO\_CHAR funcionam

incorretamente em servidores big-endian. Nessas máquinas, bytes/caracteres são trocados e vão para

posições erradas ao converter. Esse bug foi corrigido no 2.5.2 e 3.0, mas isso significa que essas

funções agora retornam valores diferentes (para o mesmo parâmetro de entrada) do que antes.

Exemplo:

select char\_to\_uuid('93519227-8D50-4E47-81AA-8F6678C096A1') from rdb$database;

Veja também: GEN_UUID e UUID_TO_CHAR

---

COS

---

Função:

Retorna o cosseno de um ângulo (expresso em radianos).

Formato:

COS( <número> )

Observações:

O ângulo é especificado em radianos e retorna um valor no intervalo de -1 a 1.

Exemplo:

select cos(x) from y;

----

COSH

----

Função:

Retorna o cosseno hiperbólico de um ângulo (expresso em radianos).

Formato:

COSH( <número> )

Exemplo:

select cosh(x) from y;

---

COT

---

Função:

Retorna 1 / tan(argumento).

Formato:

COT( <número> )

Exemplo:

select cot(x) from y;

---—-

DATEADD

---—-

Função:

Retorna um valor de data/hora/timestamp aumentado (ou diminuído, quando negativo)

pela quantidade de tempo especificada.

Formato:

DATEADD( <número> <parte\_do\_timestamp> TO <data\_hora> )

DATEADD( <parte\_do\_timestamp>, <número>, <data\_hora> )

parte\_do\_timestamp ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

Observações:

1) WEEKDAY e YEARDAY não podem ser usados. Não faz sentido.

2) YEAR, MONTH e DAY não podem ser usados com valores de hora.

3) Todos os valores de parte\_do\_timestamp podem ser usados com valores de timestamp.

4) Ao usar hora, minuto, segundo e milissegundo para DATEADD e datas, a quantidade adicionada ou

    subtraída deve considerar pelo menos um dia para produzir efeito (ou seja, adicionar 23 horas a uma data

    não a incrementa).

Exemplo:

select dateadd(-1 day to current\_date) as yesterday

    from rdb$database;

---—–

DATEDIFF

---—–

Função:

Retorna um valor numérico exato representando a quantidade de tempo do primeiro

valor de data/hora/timestamp para o segundo.

Formato:

DATEDIFF( <parte\_do\_timestamp> FROM <data\_hora> TO <data\_hora> )

DATEDIFF( <parte\_do\_timestamp>, <data\_hora>, <data\_hora> )

parte\_do\_timestamp ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

Observações:

1) Retorna valor positivo se o segundo valor for maior que o primeiro,

   negativo quando o primeiro for maior ou zero quando forem iguais.

2) A comparação de data com valores de hora é inválida.

3) WEEKDAY e YEARDAY não podem ser usados. Não faz sentido.

4) YEAR, MONTH e DAY não podem ser usados com valores de hora.

5) Todos os valores de parte\_do\_timestamp podem ser usados com valores de timestamp.

Exemplo:

select datediff(week from cast('yesterday' as timestamp) - 7 to current\_timestamp)

    from rdb$database;

---—

DECODE

---—

Função:

DECODE é um atalho para a expressão CASE ... WHEN ... ELSE.

Formato:

DECODE( <expressão>, <pesquisa>, <resultado> \[ , <pesquisa>, <resultado> ... \] \[, <padrão> \]

Exemplo:

select decode(state, 0, 'deleted', 1, 'active', 'unknown') from things;

---

EXP

---

Função:

Retorna o exponencial e para o argumento.

Formato:

EXP( <número> )

Exemplo:

select exp(x) from y;

---–

FLOOR

---–

Função:

Retorna um valor representando o maior inteiro que é menor

ou igual ao argumento de entrada.

Formato:

FLOOR( <número> )

Exemplo:

1) select floor(val) from x;

2) select floor(2.1), floor(-2.1) from rdb$database;  -- retorna 2, -3

---—–

GEN_UUID

---—–

Função:

Retorna um número único universal no tipo CHAR(16) OCTETS.

Formato:

GEN\_UUID()

Importante:

Antes do Firebird 2.5.2, GEN\_UUID retornava strings completamente aleatórias. Isso não está em conformidade

com o RFC-4122 (especificação de UUID).

Isso foi corrigido no Firebird 2.5.2 e 3.0. Agora GEN\_UUID retorna uma string UUID versão 4 em conformidade,

onde alguns bits são reservados e os outros são aleatórios. O formato de string de um UUID em conformidade

é XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, onde 4 é fixo (versão) e Y é 8, 9, A ou B.

Exemplo:

insert into records (id) value (gen\_uuid());

Veja também: CHAR_TO_UUID e UUID_TO_CHAR

----

HASH

----

Função:

Retorna um HASH de uma string.

Formato:

HASH( <string> )

Exemplo:

select hash(x) from y;

----

LEFT

----

Função:

Retorna a substring de um comprimento especificado que aparece no início de uma string.

Formato:

LEFT( <string>, <número> )

Exemplo:

select left(name, char\_length(name) - 10)

    from people

    where name like '% FERNANDES';

–

Função:

Retorna o logaritmo natural de um número.

Formato:

LN( <número> )

Exemplo:

select ln(x) from y;

---

LOG

---

Função:

LOG(x, y) retorna o logaritmo na base x de y.

Formato:

LOG( <número>, <número> )

Exemplo:

select log(x, 10) from y;

---–

LOG10

---–

Função:

Retorna o logaritmo na base dez de um número.

Formato:

LOG10( <número> )

Exemplo:

select log10(x) from y;

----

LPAD

----

Função:

LPAD(string1, comprimento, string2) anexa string2 ao início de

string1 até que o comprimento da string resultante se torne igual ao comprimento.

Formato:

LPAD( <string>, <número> \[, <string> \] )

Observações:

1) Se a segunda string for omitida, o valor padrão é um espaço.

2) A segunda string é truncada quando a string resultante

   se tornar maior que o comprimento.

3) A primeira string é truncada se seu comprimento for maior que o parâmetro

   de comprimento.

Exemplo:

select lpad(x, 10) from y;

---—–

MAXVALUE

---—–

Função:

Retorna o valor máximo de uma lista de valores.

Formato:

MAXVALUE( <valor> \[, <valor> ...\] )

Exemplo:

select maxvalue(v1, v2, 10) from x;

---—–

MINVALUE

---—–

Função:

Retorna o valor mínimo de uma lista de valores.

Formato:

MINVALUE( <valor> \[, <valor> ...\] )

Exemplo:

select minvalue(v1, v2, 10) from x;

---

MOD

---

Função:

MOD(X, Y) retorna a parte restante da divisão de X por Y.

Formato:

MOD( <número>, <número> )

Exemplo:

select mod(x, 10) from y;

---—-

OVERLAY

---—-

Função:

OVERLAY( <string1> PLACING <string2> FROM <início> \[ FOR <comprimento> \] ) retorna

string1 substituindo a substring FROM início FOR comprimento por string2.

Formato:

OVERLAY( <string> PLACING <string> FROM <número> \[ FOR <número> \] )

Observações:

1) Se <comprimento> não for especificado, CHAR\_LENGTH( <string2> ) é implícito.

2) A função OVERLAY é equivalente a:

       SUBSTRING(<string1> FROM 1 FOR <início> - 1) \|\|

       <string2> \|\|

       SUBSTRING(<string1> FROM <início> + <comprimento>)

–

Função:

Retorna a constante PI (3.1459...).

Formato:

PI()

Exemplo:

val = PI();

---—–

POSITION

---—–

Função:

Retorna a posição da primeira string dentro da segunda string começando em

um deslocamento (ou desde o início quando omitido). Quando não encontrado, retorna 0.

Formato:

POSITION( <string> IN <string> )

POSITION( <string>, <string> \[, <number> \] )

Exemplo:

select rdb$relation\_name

    from rdb$relations

    where position('RDB$' IN rdb$relation\_name) = 1;

---–

POWER

---–

Função:

POWER(X, Y) retorna X elevado à potência de Y.

Formato:

POWER( <number>, <number> )

Exemplo:

select power(x, 10) from y;

----

RAND

----

Função:

Retorna um número aleatório entre 0 e 1.

Formato:

RAND()

Exemplo:

select \* from x order by rand();

---—-

REPLACE

---—-

Função:

REPLACE(procurado, encontrar, substituição) substitui todas as ocorrências de "encontrar"

em "procurado" por "substituição".

Formato:

REPLACE( <string>, <string>, <string> )

Exemplo:

select replace(x, ' ', ',') from y;

---—-

REVERSE

---—-

Função:

Retorna uma string em ordem inversa.

Formato:

REVERSE( <valor> )

Notas:

REVERSE é uma função útil para indexar strings da direita para a esquerda.

Exemplo:

create index people\_email on people computed by (reverse(email));

select \* from people where reverse(email) starting with reverse('.br');

---–

RIGHT

---–

Função:

RIGHT(string, comprimento)

Retorna a substring de um comprimento especificado que aparece no final de uma string.

Formato:

RIGHT( <string>, <number> )

Exemplo:

select right(rdb$relation\_name, char\_length(rdb$relation\_name) - 4)

    from rdb$relations

    where rdb$relation\_name like 'RDB$%';

---–

ROUND

---–

Função:

ROUND(número, escala)

Retorna um número arredondado para a escala especificada.

Formato:

ROUND( <number> \[, <number> \] )

Notas:

Se a escala (segundo parâmetro) for negativa, a parte inteira do

valor é arredondada. Ex: ROUND(123.456, -1) retorna 120.000.

Exemplos:

select round(salary \* 1.1, 0) from people;

----

RPAD

----

Função:

RPAD(string1, comprimento, string2) anexa string2 ao final de

string1 até que o comprimento da string resultante se torne igual ao comprimento.

Formato:

RPAD( <string>, <number> \[, <string> \] )

Notas:

1) Se a segunda string for omitida, o valor padrão é um espaço.

2) A segunda string é truncada quando a string resultante

   se tornar maior que o comprimento.

3) A primeira string é truncada se seu comprimento for maior que o parâmetro

   de comprimento.

Exemplo:

select rpad(x, 10) from y;

----

SIGN

----

Função:

Retorna 1, 0 ou -1 dependendo se o valor de entrada é positivo, zero ou

negativo, respectivamente.

Formato:

SIGN( <number> )

Exemplo:

select sign(x) from y;

---

SIN

---

Função:

Retorna o seno de um ângulo (expresso em radianos).

Formato:

SIN( <number> )

Notas:

O argumento para SIN deve ser especificado em radianos.

Exemplo:

select sin(x) from y;

----

SINH

----

Função:

Retorna o seno hiperbólico de um ângulo (expresso em radianos).

Formato:

SINH( <number> )

Exemplo:

select sinh(x) from y;

----

SQRT

----

Função:

Retorna a raiz quadrada de um número.

Formato:

SQRT( <number> )

Exemplo:

select sqrt(x) from y;

---

TAN

---

Função:

Retorna a tangente de um ângulo (expresso em radianos).

Formato:

TAN( <number> )

Notas:

O argumento para TAN deve ser especificado em radianos.

Exemplo:

select tan(x) from y;

----

TANH

----

Função:

Retorna a tangente hiperbólica de um ângulo (expresso em radianos).

Formato:

TANH( <number> )

Exemplo:

select tanh(x) from y;

---–

TRUNC

---–

Função:

TRUNC(número, escala)

Retorna a parte inteira (até a escala especificada) de um número.

Formato:

TRUNC( <number> \[, <number> \] )

Notas:

Se a escala (segundo parâmetro) for negativa, a parte inteira do

valor é truncada. Ex: TRUNC(123.456, -1) retorna 120.000.

Exemplo:

1) select trunc(x) from y;

2) select trunc(-2.8), trunc(2.8) from rdb$database;  -- retorna -2, 2

3) select trunc(987.65, 1), trunc(987.65, -1) from rdb$database;  -- retorna 987.60, 980.00

---———

UUID_TO_CHAR

---———

Função:

Converte um UUID CHAR(16) OCTETS (que é retornado por GEN\_UUID) para a

representação ASCII CHAR(32) (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

Formato:

UUID\_TO\_CHAR( <string> )

Importante (para servidores big-endian):

Foi descoberto que antes do Firebird 2.5.2, CHAR\_TO\_UUID e UUID\_TO\_CHAR funcionam

incorretamente em servidores big-endian. Nessas máquinas, bytes/caracteres são trocados e vão

para posições erradas ao converter. Esse bug foi corrigido no 2.5.2 e 3.0, mas isso significa que

essas funções agora retornam valores diferentes (para o mesmo parâmetro de entrada) do que antes.

Exemplo:

select uuid\_to\_char(gen\_uuid()) from rdb$database;

Veja também: GEN_UUID e CHAR_TO_UUID