Funzioni integrate di Firebird 3.0 (SDF, ovvero Server Defined Functions)

Le funzioni incorporate di seguito (tranne DECODE) vengono utilizzate solo se non esiste una

UDF dichiarata con lo stesso nome.

Questa scelta tra UDF e funzione di sistema viene decisa durante la compilazione

dell’istruzione e non viene modificata se l’istruzione viene memorizzata (trigger / SP).

Autori:

Adriano dos Santos Fernandes <[email protected]>

Oleg Loa <[email protected]>

Alexey Karyakin <[email protected]>

Claudio Valderrama C. <cvalde at usa.net>

---

ABS

---

Funzione:

Restituisce il valore assoluto di un numero.

Formato:

ABS( <numero> )

Esempio:

select abs(amount) from transactions;

----

ACOS

----

Funzione:

Restituisce l'arcocoseno di un numero.

Formato:

ACOS( <numero> )

Note:

L'argomento di ACOS deve essere compreso tra -1 e 1 e restituisce un valore

compreso tra 0 e PI.

Esempio:

select acos(x) from y;

---–

ACOSH

---–

Funzione:

Restituisce l'arcocoseno iperbolico di un numero (espresso in radianti).

Formato:

ACOSH( <numero> )

Esempio:

select acosh(x) from y;

---——-

ASCII_CHAR

---——-

Funzione:

Restituisce il carattere ASCII con il codice specificato.

Formato:

ASCII\_CHAR( <numero> )

Note:

L'argomento di ASCII\_CHAR deve essere compreso tra 0 e 255 e restituisce un valore

con set di caratteri NONE.

Esempio:

select ascii\_char(x) from y;

---——

ASCII_VAL

---——

Funzione:

Restituisce il codice ASCII del primo carattere della stringa specificata.

Formato:

ASCII\_VAL( <stringa> )

Note:

1) Restituisce 0 se la stringa è vuota.

2) Genera un errore se il primo carattere è multibyte.

Esempio:

select ascii\_val(x) from y;

----

ASIN

----

Funzione:

Restituisce l'arcoseno di un numero.

Formato:

ASIN( <numero> )

Note:

L'argomento di ASIN deve essere compreso tra -1 e 1 e restituisce un valore

compreso tra -PI / 2 e PI / 2.

Esempio:

select asin(x) from y;

---–

ASINH

---–

Funzione:

Restituisce l'arcoseno iperbolico di un numero (espresso in radianti).

Formato:

ASINH( <numero> )

Esempio:

select asinh(x) from y;

----

ATAN

----

Funzione:

Restituisce l'arcotangente di un numero.

Formato:

ATAN( <numero> )

Note:

Restituisce un valore compreso tra -PI / 2 e PI / 2.

Esempio:

select atan(x) from y;

---–

ATAN2

---–

Funzione:

Restituisce l'arcotangente del primo numero / secondo numero.

Formato:

ATAN( <numero>, <numero> )

Note:

Restituisce un valore compreso tra -PI e PI.

Esempio:

select atan2(x, y) from z;

---–

ATANH

---–

Funzione:

Restituisce l'arcotangente iperbolica di un numero (espresso in radianti).

Formato:

ATANH( <numero> )

Esempio:

select atanh(x) from y;

---—-

BIN_AND

---—-

Funzione:

Restituisce il risultato di un'operazione AND binaria eseguita su tutti gli argomenti.

Formato:

BIN\_AND( <numero>, <numero> \[, <numero> ...\] )

Esempio:

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

---—-

BIN_NOT

---—-

Funzione:

Restituisce il risultato di un'operazione NOT bit a bit eseguita sul suo argomento.

Formato:

BIN\_NOT( <numero> )

Esempio:

select bin\_not(flags) from x;

---—

BIN_OR

---—

Funzione:

Restituisce il risultato di un'operazione OR binaria eseguita su tutti gli argomenti.

Formato:

BIN\_OR( <numero>, <numero> \[, <numero> ...\] )

Esempio:

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

---—-

BIN_SHL

---—-

Funzione:

Restituisce il risultato di un'operazione di scorrimento a sinistra binario eseguita sugli argomenti (primo << secondo).

Formato:

BIN\_SHL( <numero>, <numero> )

Esempio:

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

---—-

BIN_SHR

---—-

Funzione:

Restituisce il risultato di un'operazione di scorrimento a destra binario eseguita sugli argomenti (primo >> secondo).

Formato:

BIN\_SHR( <numero>, <numero> )

Esempio:

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

---—-

BIN_XOR

---—-

Funzione:

Restituisce il risultato di un'operazione XOR binaria eseguita su tutti gli argomenti.

Formato:

BIN\_XOR( <numero>, <numero> \[, <numero> ...\] )

Esempio:

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

---———–

CEIL | CEILING

---———–

Funzione:

Restituisce un valore che rappresenta il più piccolo intero maggiore

o uguale all'argomento di input.

Formato:

{ CEIL \| CEILING }( <numero> )

Esempio:

1) select ceil(val) from x;

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

---———

CHAR_TO_UUID

---———

Funzione:

Converte la rappresentazione ASCII CHAR(32) di un UUID

(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) nella rappresentazione CHAR(16) OCTETS

(ottimizzata per l'archiviazione).

Formato:

CHAR\_TO\_UUID( <stringa> )

Importante (per server big-endian):

È stato scoperto che prima di Firebird 2.5.2, CHAR\_TO\_UUID e UUID\_TO\_CHAR funzionavano

in modo errato sui server big-endian. In queste macchine, byte/caratteri vengono scambiati e finiscono in

posizioni sbagliate durante la conversione. Questo bug è stato corretto in 2.5.2 e 3.0, ma ciò significa che queste

funzioni ora restituiscono valori diversi (per lo stesso parametro di input) rispetto a prima.

Esempio:

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

Vedi anche: GEN_UUID e UUID_TO_CHAR

---

COS

---

Funzione:

Restituisce il coseno di un angolo (espresso in radianti).

Formato:

COS( <numero> )

Note:

L'angolo è specificato in radianti e restituisce un valore compreso tra -1 e 1.

Esempio:

select cos(x) from y;

----

COSH

----

Funzione:

Restituisce il coseno iperbolico di un angolo (espresso in radianti).

Formato:

COSH( <numero> )

Esempio:

select cosh(x) from y;

---

COT

---

Funzione:

Restituisce 1 / tan(argomento).

Formato:

COT( <numero> )

Esempio:

select cot(x) from y;

---—-

DATEADD

---—-

Funzione:

Restituisce un valore data/ora/timestamp incrementato (o decrementato, se negativo)

della quantità di tempo specificata.

Formato:

DATEADD( <numero> <parte\_timestamp> TO <data\_ora> )

DATEADD( <parte\_timestamp>, <numero>, <data\_ora> )

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

Note:

1) WEEKDAY e YEARDAY non possono essere utilizzati. Non ha senso.

2) YEAR, MONTH e DAY non possono essere utilizzati con valori di tipo time.

3) Tutti i valori di parte\_timestamp possono essere utilizzati con valori timestamp.

4) Quando si utilizzano ora, minuti, secondi e millisecondi con DATEADD e date, la quantità aggiunta o

    sottratta deve corrispondere almeno a un giorno per produrre un effetto (cioè aggiungere 23 ore a una data

    non la incrementa).

Esempio:

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

    from rdb$database;

---—–

DATEDIFF

---—–

Funzione:

Restituisce un valore numerico esatto che rappresenta la quantità di tempo dal primo

valore data/ora/timestamp al secondo.

Formato:

DATEDIFF( <parte\_timestamp> FROM <data\_ora> TO <data\_ora> )

DATEDIFF( <parte\_timestamp>, <data\_ora>, <data\_ora> )

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

Note:

1) Restituisce un valore positivo se il secondo valore è maggiore del primo,

   negativo quando il primo è maggiore o zero quando sono uguali.

2) Il confronto di date con valori di tipo time non è valido.

3) WEEKDAY e YEARDAY non possono essere utilizzati. Non ha senso.

4) YEAR, MONTH e DAY non possono essere utilizzati con valori di tipo time.

5) Tutti i valori di parte\_timestamp possono essere utilizzati con valori timestamp.

Esempio:

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

    from rdb$database;

---—

DECODE

---—

Funzione:

DECODE è una scorciatoia per l'espressione CASE ... WHEN ... ELSE.

Formato:

DECODE( <espressione>, <ricerca>, <risultato> \[ , <ricerca>, <risultato> ... \] \[, <predefinito> \]

Esempio:

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

---

EXP

---

Funzione:

Restituisce l'esponenziale e dell'argomento.

Formato:

EXP( <numero> )

Esempio:

select exp(x) from y;

---–

FLOOR

---–

Funzione:

Restituisce un valore che rappresenta il più grande intero minore

o uguale all'argomento di input.

Formato:

FLOOR( <numero> )

Esempio:

1) select floor(val) from x;

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

---—–

GEN_UUID

---—–

Funzione:

Restituisce un numero universale univoco di tipo CHAR(16) OCTETS.

Formato:

GEN\_UUID()

Importante:

Prima di Firebird 2.5.2, GEN\_UUID restituiva stringhe completamente casuali. Questo non è conforme

alla RFC-4122 (specifica UUID).

Questo è stato corretto in Firebird 2.5.2 e 3.0. Ora GEN\_UUID restituisce una stringa UUID versione 4 conforme,

dove alcuni bit sono riservati e gli altri sono casuali. Il formato stringa di un UUID conforme

è XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, dove 4 è fisso (versione) e Y è 8, 9, A o B.

Esempio:

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

Vedi anche: CHAR_TO_UUID e UUID_TO_CHAR

----

HASH

----

Funzione:

Restituisce un HASH di una stringa.

Formato:

HASH( <stringa> )

Esempio:

select hash(x) from y;

----

LEFT

----

Funzione:

Restituisce la sottostringa di una lunghezza specificata che appare all'inizio di una stringa.

Formato:

LEFT( <stringa>, <numero> )

Esempio:

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

    from people

    where name like '% FERNANDES';

–

Funzione:

Restituisce il logaritmo naturale di un numero.

Formato:

LN( <numero> )

Esempio:

select ln(x) from y;

---

LOG

---

Funzione:

LOG(x, y) restituisce il logaritmo in base x di y.

Formato:

LOG( <numero>, <numero> )

Esempio:

select log(x, 10) from y;

---–

LOG10

---–

Funzione:

Restituisce il logaritmo in base dieci di un numero.

Formato:

LOG10( <numero> )

Esempio:

select log10(x) from y;

----

LPAD

----

Funzione:

LPAD(stringa1, lunghezza, stringa2) aggiunge stringa2 all'inizio di

stringa1 finché la lunghezza della stringa risultante diventa uguale a lunghezza.

Formato:

LPAD( <stringa>, <numero> \[, <stringa> \] )

Note:

1) Se la seconda stringa viene omessa, il valore predefinito è uno spazio.

2) La seconda stringa viene troncata quando la stringa risultante

   diventa più lunga di lunghezza.

3) La prima stringa viene troncata se la sua lunghezza è maggiore del parametro

   lunghezza.

Esempio:

select lpad(x, 10) from y;

---—–

MAXVALUE

---—–

Funzione:

Restituisce il valore massimo di un elenco di valori.

Formato:

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

Esempio:

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

---—–

MINVALUE

---—–

Funzione:

Restituisce il valore minimo di un elenco di valori.

Formato:

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

Esempio:

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

---

MOD

---

Funzione:

MOD(X, Y) restituisce la parte restante della divisione di X per Y.

Formato:

MOD( <numero>, <numero> )

Esempio:

select mod(x, 10) from y;

---—-

OVERLAY

---—-

Funzione:

OVERLAY( <stringa1> PLACING <stringa2> FROM <inizio> \[ FOR <lunghezza> \] ) restituisce

stringa1 sostituendo la sottostringa FROM inizio FOR lunghezza con stringa2.

Formato:

OVERLAY( <stringa> PLACING <stringa> FROM <numero> \[ FOR <numero> \] )

Note:

1) Se <lunghezza> non è specificato, viene implicato CHAR\_LENGTH( <stringa2> ).

2) La funzione OVERLAY è equivalente a:

       SUBSTRING(<stringa1> FROM 1 FOR <inizio> - 1) \|\|

       <stringa2> \|\|

       SUBSTRING(<stringa1> FROM <inizio> + <lunghezza>)

–

Funzione:

Restituisce la costante PI (3.1459...).

Formato:

PI()

Esempio:

val = PI();

---—–

POSITION

---—–

Funzione:

Restituisce la posizione della prima stringa all'interno della seconda stringa a partire da

un offset (o dall’inizio quando omesso). Quando non viene trovato, restituisce 0.

Formato:

POSITION( <stringa> IN <stringa> )

POSITION( <stringa>, <stringa> \[, <numero> \] )

Esempio:

select rdb$relation\_name

    from rdb$relations

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

---–

POWER

---–

Funzione:

POWER(X, Y) restituisce X elevato alla potenza di Y.

Formato:

POWER( <numero>, <numero> )

Esempio:

select power(x, 10) from y;

----

RAND

----

Funzione:

Restituisce un numero casuale compreso tra 0 e 1.

Formato:

RAND()

Esempio:

select \* from x order by rand();

---—-

REPLACE

---—-

Funzione:

REPLACE(ricercata, trova, sostituzione) sostituisce tutte le occorrenze di "trova"

in "ricercata" con "sostituzione".

Formato:

REPLACE( <stringa>, <stringa>, <stringa> )

Esempio:

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

---—-

REVERSE

---—-

Funzione:

Restituisce una stringa in ordine inverso.

Formato:

REVERSE( <valore> )

Note:

REVERSE è una funzione utile per indicizzare stringhe da destra a sinistra.

Esempio:

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

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

---–

RIGHT

---–

Funzione:

RIGHT(stringa, lunghezza)

Restituisce la sottostringa di una lunghezza specificata che appare alla fine di una stringa.

Formato:

RIGHT( <stringa>, <numero> )

Esempio:

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

    from rdb$relations

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

---–

ROUND

---–

Funzione:

ROUND(numero, scala)

Restituisce un numero arrotondato alla scala specificata.

Formato:

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

Note:

Se la scala (secondo parametro) è negativa, viene arrotondata la parte intera

del valore. Es: ROUND(123.456, -1) restituisce 120.000.

Esempi:

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

----

RPAD

----

Funzione:

RPAD(stringa1, lunghezza, stringa2) aggiunge stringa2 alla fine di

stringa1 finché la lunghezza della stringa risultante diventa uguale a lunghezza.

Formato:

RPAD( <stringa>, <numero> \[, <stringa> \] )

Note:

1) Se la seconda stringa è omessa, il valore predefinito è uno spazio.

2) La seconda stringa viene troncata quando la stringa risultante

   diventerebbe più lunga di lunghezza.

3) La prima stringa viene troncata se la sua lunghezza è maggiore del parametro

   lunghezza.

Esempio:

select rpad(x, 10) from y;

----

SIGN

----

Funzione:

Restituisce 1, 0 o -1 a seconda che il valore di input sia positivo, zero o

negativo, rispettivamente.

Formato:

SIGN( <numero> )

Esempio:

select sign(x) from y;

---

SIN

---

Funzione:

Restituisce il seno di un angolo (espresso in radianti).

Formato:

SIN( <numero> )

Note:

L'argomento di SIN deve essere specificato in radianti.

Esempio:

select sin(x) from y;

----

SINH

----

Funzione:

Restituisce il seno iperbolico di un angolo (espresso in radianti).

Formato:

SINH( <numero> )

Esempio:

select sinh(x) from y;

----

SQRT

----

Funzione:

Restituisce la radice quadrata di un numero.

Formato:

SQRT( <numero> )

Esempio:

select sqrt(x) from y;

---

TAN

---

Funzione:

Restituisce la tangente di un angolo (espresso in radianti).

Formato:

TAN( <numero> )

Note:

L'argomento di TAN deve essere specificato in radianti.

Esempio:

select tan(x) from y;

----

TANH

----

Funzione:

Restituisce la tangente iperbolica di un angolo (espresso in radianti).

Formato:

TANH( <numero> )

Esempio:

select tanh(x) from y;

---–

TRUNC

---–

Funzione:

TRUNC(numero, scala)

Restituisce la parte intera (fino alla scala specificata) di un numero.

Formato:

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

Note:

Se la scala (secondo parametro) è negativa, la parte intera di

il valore viene troncata. Es: TRUNC(123.456, -1) restituisce 120.000.

Esempio:

1) select trunc(x) from y;

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

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

---———

UUID_TO_CHAR

---———

Funzione:

Converte un UUID CHAR(16) OCTETS (restituito da GEN\_UUID) nella

rappresentazione ASCII CHAR(32) (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).

Formato:

UUID\_TO\_CHAR( <stringa> )

Importante (per server big-endian):

È stato scoperto che prima di Firebird 2.5.2, CHAR\_TO\_UUID e UUID\_TO\_CHAR funzionano

in modo errato sui server big-endian. In queste macchine, byte/caratteri vengono scambiati e vanno in

posizioni errate durante la conversione. Questo bug è stato corretto in 2.5.2 e 3.0, ma ciò significa che queste

funzioni ora restituiscono valori diversi (per lo stesso parametro di input) rispetto a prima.

Esempio:

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

Vedi anche: GEN_UUID e CHAR_TO_UUID