Funciones integradas de Firebird 3.0 (SDF, también conocidas como Funciones Definidas por el Servidor)

Las funciones incorporadas a continuación (excepto DECODE) se utilizan solo si no hay

una UDF declarada con el mismo nombre.

Esta elección entre UDF o función del sistema se decide al compilar la

sentencia y no cambia si la sentencia se almacena (trigger / SP).

Autores:

Adriano dos Santos Fernandes <[email protected]>

Oleg Loa <[email protected]>

Alexey Karyakin <[email protected]>

Claudio Valderrama C. <cvalde at usa.net>

---

ABS

---

Función:

Devuelve el valor absoluto de un número.

Formato:

ABS( <número> )

Ejemplo:

select abs(amount) from transactions;

----

ACOS

----

Función:

Devuelve el arco coseno de un número.

Formato:

ACOS( <número> )

Notas:

El argumento de ACOS debe estar en el rango de -1 a 1 y devuelve un valor en

el rango de 0 a PI.

Ejemplo:

select acos(x) from y;

---–

ACOSH

---–

Función:

Devuelve el arco coseno hiperbólico de un número (expresado en radianes).

Formato:

ACOSH( <número> )

Ejemplo:

select acosh(x) from y;

---——-

ASCII_CHAR

---——-

Función:

Devuelve el carácter ASCII con el código especificado.

Formato:

ASCII\_CHAR( <número> )

Notas:

El argumento de ASCII\_CHAR debe estar en el rango de 0 a 255 y devuelve un valor

con el conjunto de caracteres NONE.

Ejemplo:

select ascii\_char(x) from y;

---——

ASCII_VAL

---——

Función:

Devuelve el código ASCII del primer carácter de la cadena especificada.

Formato:

ASCII\_VAL( <cadena> )

Notas:

1) Devuelve 0 si la cadena está vacía.

2) Lanza un error si el primer carácter es multibyte.

Ejemplo:

select ascii\_val(x) from y;

----

ASIN

----

Función:

Devuelve el arco seno de un número.

Formato:

ASIN( <número> )

Notas:

El argumento de ASIN debe estar en el rango de -1 a 1 y devuelve un valor en

el rango de -PI / 2 a PI / 2.

Ejemplo:

select asin(x) from y;

---–

ASINH

---–

Función:

Devuelve el arco seno hiperbólico de un número (expresado en radianes).

Formato:

ASINH( <número> )

Ejemplo:

select asinh(x) from y;

----

ATAN

----

Función:

Devuelve el arco tangente de un número.

Formato:

ATAN( <número> )

Notas:

Devuelve un valor en el rango de -PI / 2 a PI / 2.

Ejemplo:

select atan(x) from y;

---–

ATAN2

---–

Función:

Devuelve el arco tangente del primer número / el segundo número.

Formato:

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

Notas:

Devuelve un valor en el rango de -PI a PI.

Ejemplo:

select atan2(x, y) from z;

---–

ATANH

---–

Función:

Devuelve el arco tangente hiperbólico de un número (expresado en radianes).

Formato:

ATANH( <número> )

Ejemplo:

select atanh(x) from y;

---—-

BIN_AND

---—-

Función:

Devuelve el resultado de una operación AND binaria realizada sobre todos los argumentos.

Formato:

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

Ejemplo:

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

---—-

BIN_NOT

---—-

Función:

Devuelve el resultado de una operación NOT bit a bit realizada sobre su argumento.

Formato:

BIN\_NOT( <número> )

Ejemplo:

select bin\_not(flags) from x;

---—

BIN_OR

---—

Función:

Devuelve el resultado de una operación OR binaria realizada sobre todos los argumentos.

Formato:

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

Ejemplo:

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

---—-

BIN_SHL

---—-

Función:

Devuelve el resultado de una operación de desplazamiento binario a la izquierda realizada sobre los argumentos (primero << segundo).

Formato:

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

Ejemplo:

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

---—-

BIN_SHR

---—-

Función:

Devuelve el resultado de una operación de desplazamiento binario a la derecha realizada sobre los argumentos (primero >> segundo).

Formato:

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

Ejemplo:

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

---—-

BIN_XOR

---—-

Función:

Devuelve el resultado de una operación XOR binaria realizada sobre todos los argumentos.

Formato:

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

Ejemplo:

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

---———–

CEIL | CEILING

---———–

Función:

Devuelve un valor que representa el entero más pequeño que es mayor

o igual que el argumento de entrada.

Formato:

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

Ejemplo:

1) select ceil(val) from x;

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

---———

CHAR_TO_UUID

---———

Función:

Convierte la representación ASCII CHAR(32) de un UUID

(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) a la representación CHAR(16) OCTETS

(optimizada para almacenamiento).

Formato:

CHAR\_TO\_UUID( <cadena> )

Importante (para servidores big-endian):

Se ha descubierto que antes de Firebird 2.5.2, CHAR\_TO\_UUID y UUID\_TO\_CHAR funcionan

incorrectamente en servidores big-endian. En estas máquinas, los bytes/caracteres se intercambian y van en

posiciones incorrectas al convertir. Este error se corrigió en 2.5.2 y 3.0, pero eso significa que estas

funciones ahora devuelven valores diferentes (para el mismo parámetro de entrada) que antes.

Ejemplo:

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

Véase también: GEN_UUID y UUID_TO_CHAR

---

COS

---

Función:

Devuelve el coseno de un ángulo (expresado en radianes).

Formato:

COS( <número> )

Notas:

El ángulo se especifica en radianes y devuelve un valor en el rango de -1 a 1.

Ejemplo:

select cos(x) from y;

----

COSH

----

Función:

Devuelve el coseno hiperbólico de un ángulo (expresado en radianes).

Formato:

COSH( <número> )

Ejemplo:

select cosh(x) from y;

---

COT

---

Función:

Devuelve 1 / tan(argumento).

Formato:

COT( <número> )

Ejemplo:

select cot(x) from y;

---—-

DATEADD

---—-

Función:

Devuelve un valor de fecha/hora/marca de tiempo incrementado (o decrementado, cuando es negativo)

por la cantidad de tiempo especificada.

Formato:

DATEADD( <número> <parte\_de\_marca\_de\_tiempo> TO <fecha\_hora> )

DATEADD( <parte\_de\_marca\_de\_tiempo>, <número>, <fecha\_hora> )

parte\_de\_marca\_de\_tiempo ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

Notas:

1) WEEKDAY y YEARDAY no se pueden usar. No tiene sentido.

2) YEAR, MONTH y DAY no se pueden usar con valores de hora.

3) Todos los valores de parte\_de\_marca\_de\_tiempo se pueden usar con valores de marca de tiempo.

4) Al usar hora, minuto, segundo y milisegundo para DATEADD y fechas, la cantidad agregada o

    restada debe representar al menos un día para producir efecto (es decir, agregar 23 horas a una fecha

    no la incrementa).

Ejemplo:

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

    from rdb$database;

---—–

DATEDIFF

---—–

Función:

Devuelve un valor numérico exacto que representa la cantidad de tiempo desde el primer

valor de fecha/hora/marca de tiempo hasta el segundo.

Formato:

DATEDIFF( <parte\_de\_marca\_de\_tiempo> FROM <fecha\_hora> TO <fecha\_hora> )

DATEDIFF( <parte\_de\_marca\_de\_tiempo>, <fecha\_hora>, <fecha\_hora> )

parte\_de\_marca\_de\_tiempo ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

Notas:

1) Devuelve un valor positivo si el segundo valor es mayor que el primero,

   negativo cuando el primero es mayor o cero cuando son iguales.

2) La comparación de fecha con valores de hora no es válida.

3) WEEKDAY y YEARDAY no se pueden usar. No tiene sentido.

4) YEAR, MONTH y DAY no se pueden usar con valores de hora.

5) Todos los valores de parte\_de\_marca\_de\_tiempo se pueden usar con valores de marca de tiempo.

Ejemplo:

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

    from rdb$database;

---—

DECODE

---—

Función:

DECODE es un atajo para la expresión CASE ... WHEN ... ELSE.

Formato:

DECODE( <expresión>, <búsqueda>, <resultado> \[ , <búsqueda>, <resultado> ... \] \[, <predeterminado> \]

Ejemplo:

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

---

EXP

---

Función:

Devuelve el exponencial e elevado al argumento.

Formato:

EXP( <número> )

Ejemplo:

select exp(x) from y;

---–

FLOOR

---–

Función:

Devuelve un valor que representa el entero más grande que es menor

o igual que el argumento de entrada.

Formato:

FLOOR( <número> )

Ejemplo:

1) select floor(val) from x;

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

---—–

GEN_UUID

---—–

Función:

Devuelve un número único universal en tipo CHAR(16) OCTETS.

Formato:

GEN\_UUID()

Importante:

Antes de Firebird 2.5.2, GEN\_UUID devolvía cadenas completamente aleatorias. Esto no cumple

con el RFC-4122 (especificación de UUID).

Esto se corrigió en Firebird 2.5.2 y 3.0. Ahora GEN\_UUID devuelve una cadena UUID versión 4

conforme, donde algunos bits están reservados y los demás son aleatorios. El formato de cadena de un UUID

conforme es XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, donde 4 es fijo (versión) e Y es 8, 9, A o B.

Ejemplo:

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

Véase también: CHAR_TO_UUID y UUID_TO_CHAR

----

HASH

----

Función:

Devuelve un HASH de una cadena.

Formato:

HASH( <cadena> )

Ejemplo:

select hash(x) from y;

----

LEFT

----

Función:

Devuelve la subcadena de una longitud especificada que aparece al inicio de una cadena.

Formato:

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

Ejemplo:

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

    from people

    where name like '% FERNANDES';

–

LN

–

Función:

Devuelve el logaritmo natural de un número.

Formato:

LN( <número> )

Ejemplo:

select ln(x) from y;

---

LOG

---

Función:

LOG(x, y) devuelve el logaritmo en base x de y.

Formato:

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

Ejemplo:

select log(x, 10) from y;

---–

LOG10

---–

Función:

Devuelve el logaritmo en base diez de un número.

Formato:

LOG10( <número> )

Ejemplo:

select log10(x) from y;

----

LPAD

----

Función:

LPAD(cadena1, longitud, cadena2) agrega cadena2 al inicio de

cadena1 hasta que la longitud de la cadena resultante sea igual a longitud.

Formato:

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

Notas:

1) Si la segunda cadena se omite, el valor predeterminado es un espacio.

2) La segunda cadena se trunca cuando la cadena resultante

   se vuelve más grande que longitud.

3) La primera cadena se trunca si su longitud es mayor que el parámetro

   longitud.

Ejemplo:

select lpad(x, 10) from y;

---—–

MAXVALUE

---—–

Función:

Devuelve el valor máximo de una lista de valores.

Formato:

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

Ejemplo:

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

---—–

MINVALUE

---—–

Función:

Devuelve el valor mínimo de una lista de valores.

Formato:

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

Ejemplo:

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

---

MOD

---

Función:

MOD(X, Y) devuelve la parte del resto de la división de X entre Y.

Formato:

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

Ejemplo:

select mod(x, 10) from y;

---—-

OVERLAY

---—-

Función:

OVERLAY( <cadena1> PLACING <cadena2> FROM <inicio> \[ FOR <longitud> \] ) devuelve

cadena1 reemplazando la subcadena DESDE inicio POR longitud con cadena2.

Formato:

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

Notas:

1) Si <longitud> no se especifica, se implica CHAR\_LENGTH( <cadena2> ).

2) La función OVERLAY es equivalente a:

       SUBSTRING(<cadena1> FROM 1 FOR <inicio> - 1) \|\|

       <cadena2> \|\|

       SUBSTRING(<cadena1> FROM <inicio> + <longitud>)

–

PI

–

Función:

Devuelve la constante PI (3.1459...).

Formato:

PI()

Ejemplo:

val = PI();

---—–

POSITION

---—–

Función:

Devuelve la posición de la primera cadena dentro de la segunda cadena comenzando en

un desplazamiento (o desde el principio cuando se omite). Cuando no se encuentra, devuelve 0.

Formato:

POSITION( <cadena> IN <cadena> )

POSITION( <cadena>, <cadena> \[, <número> \] )

Ejemplo:

select rdb$relation\_name

    from rdb$relations

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

---–

POWER

---–

Función:

POWER(X, Y) devuelve X elevado a la potencia de Y.

Formato:

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

Ejemplo:

select power(x, 10) from y;

----

RAND

----

Función:

Devuelve un número aleatorio entre 0 y 1.

Formato:

RAND()

Ejemplo:

select \* from x order by rand();

---—-

REPLACE

---—-

Función:

REPLACE(buscado, encontrar, reemplazo) reemplaza todas las ocurrencias de "encontrar"

en "buscado" por "reemplazo".

Formato:

REPLACE( <cadena>, <cadena>, <cadena> )

Ejemplo:

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

---—-

REVERSE

---—-

Función:

Devuelve una cadena en orden inverso.

Formato:

REVERSE( <valor> )

Notas:

REVERSE es una función útil para indexar cadenas de derecha a izquierda.

Ejemplo:

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

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

---–

RIGHT

---–

Función:

RIGHT(cadena, longitud)

Devuelve la subcadena de una longitud especificada que aparece al final de una cadena.

Formato:

RIGHT( <cadena>, <número> )

Ejemplo:

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

    from rdb$relations

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

---–

ROUND

---–

Función:

ROUND(número, escala)

Devuelve un número redondeado a la escala especificada.

Formato:

ROUND( <número> \[, <número> \] )

Notas:

Si la escala (segundo parámetro) es negativa, la parte entera de

el valor se redondea. Ej.: ROUND(123.456, -1) devuelve 120.000.

Ejemplos:

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

----

RPAD

----

Función:

RPAD(cadena1, longitud, cadena2) agrega cadena2 al final de

cadena1 hasta que la longitud de la cadena resultante sea igual a longitud.

Formato:

RPAD( <cadena>, <número> \[, <cadena> \] )

Notas:

1) Si la segunda cadena se omite, el valor predeterminado es un espacio.

2) La segunda cadena se trunca cuando la cadena resultante

   se vuelve más grande que longitud.

3) La primera cadena se trunca si su longitud es mayor que el parámetro

   de longitud.

Ejemplo:

select rpad(x, 10) from y;

----

SIGN

----

Función:

Devuelve 1, 0 o -1 dependiendo de si el valor de entrada es positivo, cero o

negativo, respectivamente.

Formato:

SIGN( <número> )

Ejemplo:

select sign(x) from y;

---

SIN

---

Función:

Devuelve el seno de un ángulo (expresado en radianes).

Formato:

SIN( <número> )

Notas:

El argumento de SIN debe especificarse en radianes.

Ejemplo:

select sin(x) from y;

----

SINH

----

Función:

Devuelve el seno hiperbólico de un ángulo (expresado en radianes).

Formato:

SINH( <número> )

Ejemplo:

select sinh(x) from y;

----

SQRT

----

Función:

Devuelve la raíz cuadrada de un número.

Formato:

SQRT( <número> )

Ejemplo:

select sqrt(x) from y;

---

TAN

---

Función:

Devuelve la tangente de un ángulo (expresado en radianes).

Formato:

TAN( <número> )

Notas:

El argumento de TAN debe especificarse en radianes.

Ejemplo:

select tan(x) from y;

----

TANH

----

Función:

Devuelve la tangente hiperbólica de un ángulo (expresado en radianes).

Formato:

TANH( <número> )

Ejemplo:

select tanh(x) from y;

---–

TRUNC

---–

Función:

TRUNC(número, escala)

Devuelve la parte entera (hasta la escala especificada) de un número.

Formato:

TRUNC( <número> \[, <número> \] )

Notas:

Si la escala (segundo parámetro) es negativa, la parte entera de

el valor se trunca. Ej.: TRUNC(123.456, -1) devuelve 120.000.

Ejemplo:

1) select trunc(x) from y;

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

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

---———

UUID_TO_CHAR

---———

Función:

Convierte un UUID CHAR(16) OCTETS (que es devuelto por GEN\_UUID) a la

representación ASCII CHAR(32) (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

Formato:

UUID\_TO\_CHAR( <cadena> )

Importante (para servidores big-endian):

Se ha descubierto que antes de Firebird 2.5.2, CHAR\_TO\_UUID y UUID\_TO\_CHAR funcionan

incorrectamente en servidores big-endian. En estas máquinas, los bytes/caracteres se intercambian y van a

posiciones incorrectas al convertir. Este error se corrigió en 2.5.2 y 3.0, pero eso significa que estas

funciones ahora devuelven valores diferentes (para el mismo parámetro de entrada) que antes.

Ejemplo:

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

Ver también: GEN_UUID y CHAR_TO_UUID