Vestavěné funkce Firebird 3.0 (SDF, tj. Server Defined Functions)

Níže uvedené vestavěné funkce (kromě DECODE) se používají pouze tehdy, pokud neexistuje

UDF deklarovaná se stejným názvem.

Tato volba mezi UDF a systémovou funkcí se rozhoduje při kompilaci

příkazu a nemění se, pokud je příkaz uložen (trigger / SP).

Autoři:

Adriano dos Santos Fernandes <[email protected]>

Oleg Loa <[email protected]>

Alexey Karyakin <[email protected]>

Claudio Valderrama C. <cvalde at usa.net>

---

ABS

---

Funkce:

Vrací absolutní hodnotu čísla.

Formát:

ABS( <number> )

Příklad:

select abs(amount) from transactions;

----

ACOS

----

Funkce:

Vrací arkuskosinus čísla.

Formát:

ACOS( <number> )

Poznámky:

Argument funkce ACOS musí být v rozsahu -1 až 1 a vrací hodnotu v

rozsahu 0 až PI.

Příklad:

select acos(x) from y;

---–

ACOSH

---–

Funkce:

Vrací hyperbolický arkuskosinus čísla (vyjádřený v radiánech).

Formát:

ACOSH( <number> )

Příklad:

select acosh(x) from y;

---——-

ASCII_CHAR

---——-

Funkce:

Vrací znak ASCII se zadaným kódem.

Formát:

ASCII\_CHAR( <number> )

Poznámky:

Argument funkce ASCII\_CHAR musí být v rozsahu 0 až 255 a vrací hodnotu

se znakovou sadou NONE.

Příklad:

select ascii\_char(x) from y;

---——

ASCII_VAL

---——

Funkce:

Vrací kód ASCII prvního znaku zadaného řetězce.

Formát:

ASCII\_VAL( <string> )

Poznámky:

1) Vrací 0, pokud je řetězec prázdný.

2) Vyhodí chybu, pokud je první znak vícebajtový.

Příklad:

select ascii\_val(x) from y;

----

ASIN

----

Funkce:

Vrací arkussinus čísla.

Formát:

ASIN( <number> )

Poznámky:

Argument funkce ASIN musí být v rozsahu -1 až 1 a vrací hodnotu v

rozsahu -PI / 2 až PI / 2.

Příklad:

select asin(x) from y;

---–

ASINH

---–

Funkce:

Vrací hyperbolický arkussinus čísla (vyjádřený v radiánech).

Formát:

ASINH( <number> )

Příklad:

select asinh(x) from y;

----

ATAN

----

Funkce:

Vrací arkustangens čísla.

Formát:

ATAN( <number> )

Poznámky:

Vrací hodnotu v rozsahu -PI / 2 až PI / 2.

Příklad:

select atan(x) from y;

---–

ATAN2

---–

Funkce:

Vrací arkustangens prvního čísla / druhého čísla.

Formát:

ATAN( <number>, <number> )

Poznámky:

Vrací hodnotu v rozsahu -PI až PI.

Příklad:

select atan2(x, y) from z;

---–

ATANH

---–

Funkce:

Vrací hyperbolický arkustangens čísla (vyjádřený v radiánech).

Formát:

ATANH( <number> )

Příklad:

select atanh(x) from y;

---—-

BIN_AND

---—-

Funkce:

Vrací výsledek binární operace AND provedené na všech argumentech.

Formát:

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

Příklad:

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

---—-

BIN_NOT

---—-

Funkce:

Vrací výsledek bitové operace NOT provedené na jejím argumentu.

Formát:

BIN\_NOT( <number> )

Příklad:

select bin\_not(flags) from x;

---—

BIN_OR

---—

Funkce:

Vrací výsledek binární operace OR provedené na všech argumentech.

Formát:

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

Příklad:

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

---—-

BIN_SHL

---—-

Funkce:

Vrací výsledek binární operace posunu vlevo provedené na argumentech (první << druhý).

Formát:

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

Příklad:

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

---—-

BIN_SHR

---—-

Funkce:

Vrací výsledek binární operace posunu vpravo provedené na argumentech (první >> druhý).

Formát:

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

Příklad:

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

---—-

BIN_XOR

---—-

Funkce:

Vrací výsledek binární operace XOR provedené na všech argumentech.

Formát:

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

Příklad:

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

---———–

CEIL | CEILING

---———–

Funkce:

Vrací hodnotu představující nejmenší celé číslo, které je větší

nebo rovno vstupnímu argumentu.

Formát:

{ CEIL \| CEILING }( <number> )

Příklad:

1) select ceil(val) from x;

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

---———

CHAR_TO_UUID

---———

Funkce:

Převádí znakovou reprezentaci UUID typu CHAR(32) v ASCII

(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) na reprezentaci CHAR(16) OCTETS

(optimalizovanou pro ukládání).

Formát:

CHAR\_TO\_UUID( <string> )

Důležité (pro big-endian servery):

Bylo zjištěno, že před Firebird 2.5.2 fungují CHAR\_TO\_UUID a UUID\_TO\_CHAR

nesprávně na big-endian serverech. Na těchto strojích se bajty/znaky prohazují a dostávají se na

nesprávné pozice při převodu. Tato chyba byla opravena ve verzi 2.5.2 a 3.0, což ale znamená, že tyto

funkce nyní vracejí jiné hodnoty (pro stejný vstupní parametr) než dříve.

Příklad:

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

Viz také: GEN_UUID a UUID_TO_CHAR

---

COS

---

Funkce:

Vrací kosinus úhlu (vyjádřeného v radiánech).

Formát:

COS( <number> )

Poznámky:

Úhel je zadán v radiánech a vrací hodnotu v rozsahu -1 až 1.

Příklad:

select cos(x) from y;

----

COSH

----

Funkce:

Vrací hyperbolický kosinus úhlu (vyjádřeného v radiánech).

Formát:

COSH( <number> )

Příklad:

select cosh(x) from y;

---

COT

---

Funkce:

Vrací 1 / tan(argument).

Formát:

COT( <number> )

Příklad:

select cot(x) from y;

---—-

DATEADD

---—-

Funkce:

Vrací hodnotu date/time/timestamp zvětšenou (nebo zmenšenou, je-li záporná)

o zadané množství času.

Formát:

DATEADD( <number> <timestamp\_part> TO <date\_time> )

DATEADD( <timestamp\_part>, <number>, <date\_time> )

timestamp\_part ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

Poznámky:

1) WEEKDAY a YEARDAY nelze použít. Nemá to smysl.

2) YEAR, MONTH a DAY nelze použít s časovými hodnotami.

3) Všechny hodnoty timestamp\_part lze použít s hodnotami timestamp.

4) Při použití hour, minute, second a millisecond pro DATEADD a data by přičítané nebo

    odečítané množství mělo odpovídat alespoň jednomu dni, aby mělo efekt (tj. přičtení 23 hodin k datu

    jej nezvětší).

Příklad:

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

    from rdb$database;

---—–

DATEDIFF

---—–

Funkce:

Vrací přesnou číselnou hodnotu představující množství času od první

hodnoty date/time/timestamp k druhé.

Formát:

DATEDIFF( <timestamp\_part> FROM <date\_time> TO <date\_time> )

DATEDIFF( <timestamp\_part>, <date\_time>, <date\_time> )

timestamp\_part ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

Poznámky:

1) Vrací kladnou hodnotu, pokud je druhá hodnota větší než první,

   zápornou, pokud je první větší, nebo nulu, pokud jsou stejné.

2) Porovnání hodnot date s časovými hodnotami je neplatné.

3) WEEKDAY a YEARDAY nelze použít. Nemá to smysl.

4) YEAR, MONTH a DAY nelze použít s časovými hodnotami.

5) Všechny hodnoty timestamp\_part lze použít s hodnotami timestamp.

Příklad:

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

    from rdb$database;

---—

DECODE

---—

Funkce:

DECODE je zkratka pro výraz CASE ... WHEN ... ELSE.

Formát:

DECODE( <expression>, <search>, <result> \[ , <search>, <result> ... \] \[, <default> \]

Příklad:

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

---

EXP

---

Funkce:

Vrací exponenciálu e na argument.

Formát:

EXP( <number> )

Příklad:

select exp(x) from y;

---–

FLOOR

---–

Funkce:

Vrací hodnotu představující největší celé číslo, které je menší

nebo rovno vstupnímu argumentu.

Formát:

FLOOR( <number> )

Příklad:

1) select floor(val) from x;

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

---—–

GEN_UUID

---—–

Funkce:

Vrací univerzální jedinečné číslo typu CHAR(16) OCTETS.

Formát:

GEN\_UUID()

Důležité:

Před Firebird 2.5.2 vracela GEN\_UUID zcela náhodné řetězce. To není v souladu

s RFC-4122 (specifikace UUID).

To bylo opraveno ve Firebird 2.5.2 a 3.0. Nyní GEN\_UUID vrací řetězec UUID verze 4

v souladu se specifikací, kde jsou některé bity rezervované a ostatní náhodné. Formát řetězce

UUID v souladu se specifikací je XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, kde 4 je pevně daná (verze) a Y je 8, 9, A nebo B.

Příklad:

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

Viz také: CHAR_TO_UUID a UUID_TO_CHAR

----

HASH

----

Funkce:

Vrací HASH řetězce.

Formát:

HASH( <string> )

Příklad:

select hash(x) from y;

----

LEFT

----

Funkce:

Vrací podřetězec zadané délky, který se nachází na začátku řetězce.

Formát:

LEFT( <string>, <number> )

Příklad:

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

    from people

    where name like '% FERNANDES';

–

Funkce:

Vrací přirozený logaritmus čísla.

Formát:

LN( <number> )

Příklad:

select ln(x) from y;

---

LOG

---

Funkce:

LOG(x, y) vrací logaritmus o základu x z y.

Formát:

LOG( <number>, <number> )

Příklad:

select log(x, 10) from y;

---–

LOG10

---–

Funkce:

Vrací logaritmus o základu deset z čísla.

Formát:

LOG10( <number> )

Příklad:

select log10(x) from y;

----

LPAD

----

Funkce:

LPAD(string1, length, string2) připojuje string2 na začátek

string1, dokud se délka výsledného řetězce nerovná length.

Formát:

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

Poznámky:

1) Pokud je druhý řetězec vynechán, výchozí hodnotou je jedna mezera.

2) Druhý řetězec je zkrácen, když by výsledný řetězec

   byl delší než length.

3) První řetězec je zkrácen, pokud je jeho délka větší než parametr

   length.

Příklad:

select lpad(x, 10) from y;

---—–

MAXVALUE

---—–

Funkce:

Vrací maximální hodnotu ze seznamu hodnot.

Formát:

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

Příklad:

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

---—–

MINVALUE

---—–

Funkce:

Vrací minimální hodnotu ze seznamu hodnot.

Formát:

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

Příklad:

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

---

MOD

---

Funkce:

MOD(X, Y) vrací zbytek po dělení X číslem Y.

Formát:

MOD( <number>, <number> )

Příklad:

select mod(x, 10) from y;

---—-

OVERLAY

---—-

Funkce:

OVERLAY( <string1> PLACING <string2> FROM <start> \[ FOR <length> \] ) vrací

string1 s nahrazením podřetězce FROM start FOR length řetězcem string2.

Formát:

OVERLAY( <string> PLACING <string> FROM <number> \[ FOR <number> \] )

Poznámky:

1) Pokud není zadáno <length>, předpokládá se CHAR\_LENGTH( <string2> ).

2) Funkce OVERLAY je ekvivalentní:

       SUBSTRING(<string1> FROM 1 FOR <start> - 1) \|\|

       <string2> \|\|

       SUBSTRING(<string1> FROM <start> + <length>)

–

Funkce:

Vrací konstantu PI (3.1459...).

Formát:

PI()

Příklad:

val = PI();

---—–

POSITION

---—–

Funkce:

Vrací pozici prvního řetězce uvnitř druhého řetězce počínaje

offset (nebo od začátku, pokud je vynechán). Pokud není nalezen, vrací 0.

Formát:

POSITION( <string> IN <string> )

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

Příklad:

select rdb$relation\_name

    from rdb$relations

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

---–

POWER

---–

Funkce:

POWER(X, Y) vrací X umocněné na Y.

Formát:

POWER( <number>, <number> )

Příklad:

select power(x, 10) from y;

----

RAND

----

Funkce:

Vrací náhodné číslo mezi 0 a 1.

Formát:

RAND()

Příklad:

select \* from x order by rand();

---—-

REPLACE

---—-

Funkce:

REPLACE(searched, find, replacement) nahradí všechny výskyty "find"

v "searched" řetězcem "replacement".

Formát:

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

Příklad:

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

---—-

REVERSE

---—-

Funkce:

Vrací řetězec v obráceném pořadí.

Formát:

REVERSE( <value> )

Poznámky:

REVERSE je užitečná funkce pro indexování řetězců zprava doleva.

Příklad:

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

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

---–

RIGHT

---–

Funkce:

RIGHT(string, length)

Vrací podřetězec zadané délky, který se nachází na konci řetězce.

Formát:

RIGHT( <string>, <number> )

Příklad:

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

    from rdb$relations

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

---–

ROUND

---–

Funkce:

ROUND(number, scale)

Vrací číslo zaokrouhlené na zadaný počet desetinných míst.

Formát:

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

Poznámky:

Pokud je scale (druhý parametr) záporný, zaokrouhluje se celá část

hodnoty. Např.: ROUND(123.456, -1) vrací 120.000.

Příklady:

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

----

RPAD

----

Funkce:

RPAD(string1, length, string2) připojuje string2 na konec

string1, dokud se délka výsledného řetězce nerovná length.

Formát:

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

Poznámky:

1) Pokud je druhý řetězec vynechán, výchozí hodnotou je jedna mezera.

2) Druhý řetězec je zkrácen, když by výsledný řetězec

   byl delší než length.

3) První řetězec je zkrácen, pokud je jeho délka větší než parametr

   length.

Příklad:

select rpad(x, 10) from y;

----

SIGN

----

Funkce:

Vrací 1, 0 nebo -1 podle toho, zda je vstupní hodnota kladná, nulová nebo

záporná.

Formát:

SIGN( <number> )

Příklad:

select sign(x) from y;

---

SIN

---

Funkce:

Vrací sinus úhlu (vyjádřeného v radiánech).

Formát:

SIN( <number> )

Poznámky:

Argument funkce SIN musí být zadán v radiánech.

Příklad:

select sin(x) from y;

----

SINH

----

Funkce:

Vrací hyperbolický sinus úhlu (vyjádřeného v radiánech).

Formát:

SINH( <number> )

Příklad:

select sinh(x) from y;

----

SQRT

----

Funkce:

Vrací druhou odmocninu čísla.

Formát:

SQRT( <number> )

Příklad:

select sqrt(x) from y;

---

TAN

---

Funkce:

Vrací tangens úhlu (vyjádřeného v radiánech).

Formát:

TAN( <number> )

Poznámky:

Argument funkce TAN musí být zadán v radiánech.

Příklad:

select tan(x) from y;

----

TANH

----

Funkce:

Vrací hyperbolický tangens úhlu (vyjádřeného v radiánech).

Formát:

TANH( <number> )

Příklad:

select tanh(x) from y;

---–

TRUNC

---–

Funkce:

TRUNC(number, scale)

Vrací celočíselnou část (do zadaného počtu desetinných míst) čísla.

Formát:

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

Poznámky:

Pokud je scale (druhý parametr) záporný, celočíselná část

hodnoty se zkrátí. Např.: TRUNC(123.456, -1) vrací 120.000.

Příklad:

1) select trunc(x) from y;

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

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

---———

UUID_TO_CHAR

---———

Funkce:

Převádí CHAR(16) OCTETS UUID (které vrací GEN\_UUID) na

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

Formát:

UUID\_TO\_CHAR( <string> )

Důležité (pro big-endian servery):

Bylo zjištěno, že před Firebird 2.5.2 fungují CHAR\_TO\_UUID a UUID\_TO\_CHAR

na big-endian serverech nesprávně. Na těchto strojích se bajty/znaky při převodu

prohazují a dostávají se na špatné pozice. Tato chyba byla opravena ve verzích 2.5.2 a 3.0,

což ale znamená, že tyto funkce nyní vrací jiné hodnoty (pro stejný vstupní parametr) než dříve.

Příklad:

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

Viz také: GEN_UUID a CHAR_TO_UUID