Fonctions intégrées de Firebird 3.0 (SDF, également appelées fonctions définies par le serveur)
Les fonctions intégrées ci-dessous (sauf DECODE) ne sont utilisées que s’il n’existe pas de
UDF déclarée avec le même nom.
Ce choix entre UDF et fonction système est décidé lors de la compilation de
l’instruction et n’est pas modifié si l’instruction est stockée (déclencheur / procédure stockée).
Auteurs :
Adriano dos Santos Fernandes <[email protected]>
Oleg Loa <[email protected]>
Alexey Karyakin <[email protected]>
Claudio Valderrama C. <cvalde at usa.net>
---
ABS
---
Fonction :
Renvoie la valeur absolue d'un nombre.
Format :
ABS( <nombre> )
Exemple :
select abs(amount) from transactions;
----
ACOS
----
Fonction :
Renvoie l'arc cosinus d'un nombre.
Format :
ACOS( <nombre> )
Notes :
L'argument de ACOS doit être compris entre -1 et 1 et renvoie une valeur
comprise entre 0 et PI.
Exemple :
select acos(x) from y;
---–
ACOSH
---–
Fonction :
Renvoie l'arc cosinus hyperbolique d'un nombre (exprimé en radians).
Format :
ACOSH( <nombre> )
Exemple :
select acosh(x) from y;
---——-
ASCII_CHAR
---——-
Fonction :
Renvoie le caractère ASCII correspondant au code spécifié.
Format :
ASCII\_CHAR( <nombre> )
Notes :
L'argument de ASCII\_CHAR doit être compris entre 0 et 255 et renvoie une valeur
avec le jeu de caractères NONE.
Exemple :
select ascii\_char(x) from y;
---——
ASCII_VAL
---——
Fonction :
Renvoie le code ASCII du premier caractère de la chaîne spécifiée.
Format :
ASCII\_VAL( <chaîne> )
Notes :
1) Renvoie 0 si la chaîne est vide.
2) Génère une erreur si le premier caractère est multi-octets.
Exemple :
select ascii\_val(x) from y;
----
ASIN
----
Fonction :
Renvoie l'arc sinus d'un nombre.
Format :
ASIN( <nombre> )
Notes :
L'argument de ASIN doit être compris entre -1 et 1 et renvoie une valeur
comprise entre -PI / 2 et PI / 2.
Exemple :
select asin(x) from y;
---–
ASINH
---–
Fonction :
Renvoie l'arc sinus hyperbolique d'un nombre (exprimé en radians).
Format :
ASINH( <nombre> )
Exemple :
select asinh(x) from y;
----
ATAN
----
Fonction :
Renvoie l'arc tangente d'un nombre.
Format :
ATAN( <nombre> )
Notes :
Renvoie une valeur comprise entre -PI / 2 et PI / 2.
Exemple :
select atan(x) from y;
---–
ATAN2
---–
Fonction :
Renvoie l'arc tangente du premier nombre / du deuxième nombre.
Format :
ATAN( <nombre>, <nombre> )
Notes :
Renvoie une valeur comprise entre -PI et PI.
Exemple :
select atan2(x, y) from z;
---–
ATANH
---–
Fonction :
Renvoie l'arc tangente hyperbolique d'un nombre (exprimé en radians).
Format :
ATANH( <nombre> )
Exemple :
select atanh(x) from y;
---—-
BIN_AND
---—-
Fonction :
Renvoie le résultat d'une opération ET binaire effectuée sur tous les arguments.
Format :
BIN\_AND( <nombre>, <nombre> \[, <nombre> ...\] )
Exemple :
select bin\_and(flags, 1) from x;
---—-
BIN_NOT
---—-
Fonction :
Renvoie le résultat d'une opération NON binaire (complément binaire) effectuée sur son argument.
Format :
BIN\_NOT( <nombre> )
Exemple :
select bin\_not(flags) from x;
---—
BIN_OR
---—
Fonction :
Renvoie le résultat d'une opération OU binaire effectuée sur tous les arguments.
Format :
BIN\_OR( <nombre>, <nombre> \[, <nombre> ...\] )
Exemple :
select bin\_or(flags1, flags2) from x;
---—-
BIN_SHL
---—-
Fonction :
Renvoie le résultat d'une opération de décalage binaire à gauche effectuée sur les arguments (premier << deuxième).
Format :
BIN\_SHL( <nombre>, <nombre> )
Exemple :
select bin\_shl(flags1, 1) from x;
---—-
BIN_SHR
---—-
Fonction :
Renvoie le résultat d'une opération de décalage binaire à droite effectuée sur les arguments (premier >> deuxième).
Format :
BIN\_SHR( <nombre>, <nombre> )
Exemple :
select bin\_shr(flags1, 1) from x;
---—-
BIN_XOR
---—-
Fonction :
Renvoie le résultat d'une opération OU exclusif binaire effectuée sur tous les arguments.
Format :
BIN\_XOR( <nombre>, <nombre> \[, <nombre> ...\] )
Exemple :
select bin\_xor(flags1, flags2) from x;
---———–
CEIL | CEILING
---———–
Fonction :
Renvoie une valeur représentant le plus petit entier supérieur
ou égal à l'argument d'entrée.
Format :
{ CEIL \| CEILING }( <nombre> )
Exemple :
1) select ceil(val) from x;
2) select ceil(2.1), ceil(-2.1) from rdb$database; -- renvoie 3, -2
---———
CHAR_TO_UUID
---———
Fonction :
Convertit la représentation ASCII CHAR(32) d'un UUID
(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) en représentation CHAR(16) OCTETS
(optimisée pour le stockage).
Format :
CHAR\_TO\_UUID( <chaîne> )
Important (pour les serveurs big-endian) :
Il a été découvert qu'avant Firebird 2.5.2, CHAR\_TO\_UUID et UUID\_TO\_CHAR fonctionnent
incorrectement sur les serveurs big-endian. Sur ces machines, les octets/caractères sont échangés et
placés dans des positions erronées lors de la conversion. Ce bug a été corrigé dans les versions 2.5.2 et 3.0,
mais cela signifie que ces fonctions renvoient désormais des valeurs différentes (pour le même paramètre d'entrée)
qu'auparavant.
Exemple :
select char\_to\_uuid('93519227-8D50-4E47-81AA-8F6678C096A1') from rdb$database;
Voir aussi : GEN_UUID et UUID_TO_CHAR
---
COS
---
Fonction :
Renvoie le cosinus d'un angle (exprimé en radians).
Format :
COS( <nombre> )
Notes :
L'angle est spécifié en radians et renvoie une valeur comprise entre -1 et 1.
Exemple :
select cos(x) from y;
----
COSH
----
Fonction :
Renvoie le cosinus hyperbolique d'un angle (exprimé en radians).
Format :
COSH( <nombre> )
Exemple :
select cosh(x) from y;
---
COT
---
Fonction :
Renvoie 1 / tan(argument).
Format :
COT( <nombre> )
Exemple :
select cot(x) from y;
---—-
DATEADD
---—-
Fonction :
Renvoie une valeur date/heure/timestamp augmentée (ou diminuée, si négative)
de la quantité de temps spécifiée.
Format :
DATEADD( <nombre> <partie\_timestamp> TO <date\_heure> )
DATEADD( <partie\_timestamp>, <nombre>, <date\_heure> )
partie\_timestamp ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }
Notes :
1) WEEKDAY et YEARDAY ne peuvent pas être utilisés. Cela n'a pas de sens.
2) YEAR, MONTH et DAY ne peuvent pas être utilisés avec des valeurs de type heure.
3) Toutes les valeurs de partie\_timestamp peuvent être utilisées avec des valeurs de type timestamp.
4) Lors de l'utilisation d'heures, de minutes, de secondes et de millisecondes avec DATEADD et des dates,
la quantité ajoutée ou soustraite doit représenter au moins un jour pour avoir un effet
(c'est-à-dire qu'ajouter 23 heures à une date ne l'incrémente pas).
Exemple :
select dateadd(-1 day to current\_date) as yesterday
from rdb$database;
---—–
DATEDIFF
---—–
Fonction :
Renvoie une valeur numérique exacte représentant la quantité de temps entre la première
valeur date/heure/timestamp et la seconde.
Format :
DATEDIFF( <partie\_timestamp> FROM <date\_heure> TO <date\_heure> )
DATEDIFF( <partie\_timestamp>, <date\_heure>, <date\_heure> )
partie\_timestamp ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }
Notes :
1) Renvoie une valeur positive si la deuxième valeur est supérieure à la première,
négative si la première est supérieure, ou zéro si elles sont égales.
2) La comparaison d'une date avec des valeurs de type heure est invalide.
3) WEEKDAY et YEARDAY ne peuvent pas être utilisés. Cela n'a pas de sens.
4) YEAR, MONTH et DAY ne peuvent pas être utilisés avec des valeurs de type heure.
5) Toutes les valeurs de partie\_timestamp peuvent être utilisées avec des valeurs de type timestamp.
Exemple :
select datediff(week from cast('yesterday' as timestamp) - 7 to current\_timestamp)
from rdb$database;
---—
DECODE
---—
Fonction :
DECODE est un raccourci pour l'expression CASE ... WHEN ... ELSE.
Format :
DECODE( <expression>, <recherche>, <résultat> \[ , <recherche>, <résultat> ... \] \[, <défaut> \]
Exemple :
select decode(state, 0, 'deleted', 1, 'active', 'unknown') from things;
---
EXP
---
Fonction :
Renvoie l'exponentielle e appliquée à l'argument.
Format :
EXP( <nombre> )
Exemple :
select exp(x) from y;
---–
FLOOR
---–
Fonction :
Renvoie une valeur représentant le plus grand entier inférieur
ou égal à l'argument d'entrée.
Format :
FLOOR( <nombre> )
Exemple :
1) select floor(val) from x;
2) select floor(2.1), floor(-2.1) from rdb$database; -- renvoie 2, -3
---—–
GEN_UUID
---—–
Fonction :
Renvoie un numéro universel unique de type CHAR(16) OCTETS.
Format :
GEN\_UUID()
Important :
Avant Firebird 2.5.2, GEN\_UUID renvoyait des chaînes complètement aléatoires. Cela n'était pas conforme
à la norme RFC-4122 (spécification UUID).
Cela a été corrigé dans Firebird 2.5.2 et 3.0. Désormais, GEN\_UUID renvoie une chaîne UUID version 4
conforme, où certains bits sont réservés et les autres sont aléatoires. Le format de chaîne d'un UUID
conforme est XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, où 4 est fixe (version) et Y est 8, 9, A ou B.
Exemple :
insert into records (id) value (gen\_uuid());
Voir aussi : CHAR_TO_UUID et UUID_TO_CHAR
----
HASH
----
Fonction :
Renvoie un HASH d'une chaîne.
Format :
HASH( <chaîne> )
Exemple :
select hash(x) from y;
----
LEFT
----
Fonction :
Renvoie la sous-chaîne d'une longueur spécifiée qui apparaît au début d'une chaîne.
Format :
LEFT( <chaîne>, <nombre> )
Exemple :
select left(name, char\_length(name) - 10)
from people
where name like '% FERNANDES';
–
LN
–
Fonction :
Renvoie le logarithme népérien d'un nombre.
Format :
LN( <nombre> )
Exemple :
select ln(x) from y;
---
LOG
---
Fonction :
LOG(x, y) renvoie le logarithme de y en base x.
Format :
LOG( <nombre>, <nombre> )
Exemple :
select log(x, 10) from y;
---–
LOG10
---–
Fonction :
Renvoie le logarithme en base dix d'un nombre.
Format :
LOG10( <nombre> )
Exemple :
select log10(x) from y;
----
LPAD
----
Fonction :
LPAD(chaîne1, longueur, chaîne2) ajoute chaîne2 au début de
chaîne1 jusqu'à ce que la longueur de la chaîne résultante devienne égale à longueur.
Format :
LPAD( <chaîne>, <nombre> \[, <chaîne> \] )
Notes :
1) Si la deuxième chaîne est omise, la valeur par défaut est un espace.
2) La deuxième chaîne est tronquée lorsque la chaîne résultante
deviendrait plus longue que longueur.
3) La première chaîne est tronquée si sa longueur est supérieure au paramètre
longueur.
Exemple :
select lpad(x, 10) from y;
---—–
MAXVALUE
---—–
Fonction :
Renvoie la valeur maximale d'une liste de valeurs.
Format :
MAXVALUE( <valeur> \[, <valeur> ...\] )
Exemple :
select maxvalue(v1, v2, 10) from x;
---—–
MINVALUE
---—–
Fonction :
Renvoie la valeur minimale d'une liste de valeurs.
Format :
MINVALUE( <valeur> \[, <valeur> ...\] )
Exemple :
select minvalue(v1, v2, 10) from x;
---
MOD
---
Fonction :
MOD(X, Y) renvoie le reste de la division de X par Y.
Format :
MOD( <nombre>, <nombre> )
Exemple :
select mod(x, 10) from y;
---—-
OVERLAY
---—-
Fonction :
OVERLAY( <chaîne1> PLACING <chaîne2> FROM <début> \[ FOR <longueur> \] ) renvoie
chaîne1 en remplaçant la sous-chaîne à partir de début sur longueur par chaîne2.
Format :
OVERLAY( <chaîne> PLACING <chaîne> FROM <nombre> \[ FOR <nombre> \] )
Notes :
1) Si <longueur> n'est pas spécifié, CHAR\_LENGTH( <chaîne2> ) est implicite.
2) La fonction OVERLAY est équivalente à :
SUBSTRING(<chaîne1> FROM 1 FOR <début> - 1) \|\|
<chaîne2> \|\|
SUBSTRING(<chaîne1> FROM <début> + <longueur>)
–
PI
–
Fonction :
Renvoie la constante PI (3.1459...).
Format :
PI()
Exemple :
val = PI();
---—–
POSITION
---—–
Fonction :
Renvoie la position de la première chaîne dans la deuxième chaîne en commençant à
un décalage (ou depuis le début si omis). Lorsqu’il n’est pas trouvé, renvoie 0.
Format :
POSITION( <chaîne> DANS <chaîne> )
POSITION( <chaîne>, <chaîne> \[, <nombre> \] )
Exemple :
select rdb$relation\_name
from rdb$relations
where position('RDB$' IN rdb$relation\_name) = 1;
---–
POWER
---–
Fonction :
POWER(X, Y) renvoie X à la puissance Y.
Format :
POWER( <nombre>, <nombre> )
Exemple :
select power(x, 10) from y;
----
RAND
----
Fonction :
Renvoie un nombre aléatoire entre 0 et 1.
Format :
RAND()
Exemple :
select \* from x order by rand();
---—-
REPLACE
---—-
Fonction :
REPLACE(texte, recherche, remplacement) remplace toutes les occurrences de "recherche"
dans "texte" par "remplacement".
Format :
REPLACE( <chaîne>, <chaîne>, <chaîne> )
Exemple :
select replace(x, ' ', ',') from y;
---—-
REVERSE
---—-
Fonction :
Renvoie une chaîne dans l'ordre inverse.
Format :
REVERSE( <valeur> )
Remarques :
REVERSE est une fonction utile pour indexer les chaînes de droite à gauche.
Exemple :
create index people\_email on people computed by (reverse(email));
select \* from people where reverse(email) starting with reverse('.br');
---–
RIGHT
---–
Fonction :
RIGHT(chaîne, longueur)
Renvoie la sous-chaîne d'une longueur spécifiée qui apparaît à la fin d'une chaîne.
Format :
RIGHT( <chaîne>, <nombre> )
Exemple :
select right(rdb$relation\_name, char\_length(rdb$relation\_name) - 4)
from rdb$relations
where rdb$relation\_name like 'RDB$%';
---–
ROUND
---–
Fonction :
ROUND(nombre, échelle)
Renvoie un nombre arrondi à l'échelle spécifiée.
Format :
ROUND( <nombre> \[, <nombre> \] )
Remarques :
Si l'échelle (deuxième paramètre) est négative, la partie entière de
la valeur est arrondie. Ex : ROUND(123.456, -1) renvoie 120.000.
Exemples :
select round(salaire \* 1.1, 0) from personnes;
----
RPAD
----
Fonction :
RPAD(chaîne1, longueur, chaîne2) ajoute chaîne2 à la fin de
chaîne1 jusqu'à ce que la longueur de la chaîne résultante devienne égale à longueur.
Format :
RPAD( <chaîne>, <nombre> \[, <chaîne> \] )
Remarques :
1) Si la deuxième chaîne est omise, la valeur par défaut est un espace.
2) La deuxième chaîne est tronquée lorsque la chaîne résultante
deviendra plus grande que longueur.
3) La première chaîne est tronquée si sa longueur est supérieure au paramètre
longueur.
Exemple :
select rpad(x, 10) from y;
----
SIGN
----
Fonction :
Renvoie 1, 0 ou -1 selon que la valeur d'entrée est positive, nulle ou
négative, respectivement.
Format :
SIGN( <nombre> )
Exemple :
select sign(x) from y;
---
SIN
---
Fonction :
Renvoie le sinus d'un angle (exprimé en radians).
Format :
SIN( <nombre> )
Remarques :
L'argument de SIN doit être spécifié en radians.
Exemple :
select sin(x) from y;
----
SINH
----
Fonction :
Renvoie le sinus hyperbolique d'un angle (exprimé en radians).
Format :
SINH( <nombre> )
Exemple :
select sinh(x) from y;
----
SQRT
----
Fonction :
Renvoie la racine carrée d'un nombre.
Format :
SQRT( <nombre> )
Exemple :
select sqrt(x) from y;
---
TAN
---
Fonction :
Renvoie la tangente d'un angle (exprimé en radians).
Format :
TAN( <nombre> )
Remarques :
L'argument de TAN doit être spécifié en radians.
Exemple :
select tan(x) from y;
----
TANH
----
Fonction :
Renvoie la tangente hyperbolique d'un angle (exprimé en radians).
Format :
TANH( <nombre> )
Exemple :
select tanh(x) from y;
---–
TRUNC
---–
Fonction :
TRUNC(nombre, échelle)
Renvoie la partie entière (jusqu'à l'échelle spécifiée) d'un nombre.
Format :
TRUNC( <nombre> \[, <nombre> \] )
Remarques :
Si l'échelle (deuxième paramètre) est négative, la partie entière de
la valeur est tronquée. Ex : TRUNC(123.456, -1) renvoie 120.000.
Exemple :
1) select trunc(x) from y;
2) select trunc(-2.8), trunc(2.8) from rdb$database; -- renvoie -2, 2
3) select trunc(987.65, 1), trunc(987.65, -1) from rdb$database; -- renvoie 987.60, 980.00
---———
UUID_TO_CHAR
---———
Fonction :
Convertit un UUID CHAR(16) OCTETS (renvoyé par GEN\_UUID) en
représentation ASCII CHAR(32) (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).
Format :
UUID\_TO\_CHAR( <chaîne> )
Important (pour les serveurs big-endian) :
Il a été découvert qu'avant Firebird 2.5.2, CHAR\_TO\_UUID et UUID\_TO\_CHAR fonctionnent
incorrectement sur les serveurs big-endian. Sur ces machines, les octets/caractères sont échangés et vont dans
des positions incorrectes lors de la conversion. Ce bug a été corrigé en 2.5.2 et 3.0, mais cela signifie que ces
fonctions renvoient maintenant des valeurs différentes (pour le même paramètre d'entrée) qu'auparavant.
Exemple :
select uuid\_to\_char(gen\_uuid()) from rdb$database;
Voir aussi : GEN_UUID et CHAR_TO_UUID