Wbudowane funkcje Firebird 3.0 (SDF, czyli Server Defined Functions)
Funkcje wbudowane poniżej (z wyjątkiem DECODE) są używane tylko wtedy, gdy nie ma
UDF zadeklarowanej o tej samej nazwie.
Wybór między UDF a funkcją systemową jest podejmowany podczas kompilacji
instrukcji i nie zmienia się, jeśli instrukcja jest przechowywana (wyzwalacz / procedura składowana).
Autorzy:
Adriano dos Santos Fernandes <[email protected]>
Oleg Loa <[email protected]>
Alexey Karyakin <[email protected]>
Claudio Valderrama C. <cvalde at usa.net>
---
ABS
---
Funkcja:
Zwraca wartość bezwzględną liczby.
Format:
ABS( <number> )
Przykład:
select abs(amount) from transactions;
----
ACOS
----
Funkcja:
Zwraca arcus cosinus liczby.
Format:
ACOS( <number> )
Uwagi:
Argument funkcji ACOS musi mieścić się w zakresie od -1 do 1, a zwracana wartość
mieści się w zakresie od 0 do PI.
Przykład:
select acos(x) from y;
---–
ACOSH
---–
Funkcja:
Zwraca arcus cosinus hiperboliczny liczby (wyrażony w radianach).
Format:
ACOSH( <number> )
Przykład:
select acosh(x) from y;
---——-
ASCII_CHAR
---——-
Funkcja:
Zwraca znak ASCII o podanym kodzie.
Format:
ASCII\_CHAR( <number> )
Uwagi:
Argument funkcji ASCII\_CHAR musi mieścić się w zakresie od 0 do 255, a zwracana wartość
ma zestaw znaków NONE.
Przykład:
select ascii\_char(x) from y;
---——
ASCII_VAL
---——
Funkcja:
Zwraca kod ASCII pierwszego znaku podanego ciągu.
Format:
ASCII\_VAL( <string> )
Uwagi:
1) Zwraca 0, jeśli ciąg jest pusty.
2) Zgłasza błąd, jeśli pierwszy znak jest wielobajtowy.
Przykład:
select ascii\_val(x) from y;
----
ASIN
----
Funkcja:
Zwraca arcus sinus liczby.
Format:
ASIN( <number> )
Uwagi:
Argument funkcji ASIN musi mieścić się w zakresie od -1 do 1, a zwracana wartość
mieści się w zakresie od -PI / 2 do PI / 2.
Przykład:
select asin(x) from y;
---–
ASINH
---–
Funkcja:
Zwraca arcus sinus hiperboliczny liczby (wyrażony w radianach).
Format:
ASINH( <number> )
Przykład:
select asinh(x) from y;
----
ATAN
----
Funkcja:
Zwraca arcus tangens liczby.
Format:
ATAN( <number> )
Uwagi:
Zwraca wartość w zakresie od -PI / 2 do PI / 2.
Przykład:
select atan(x) from y;
---–
ATAN2
---–
Funkcja:
Zwraca arcus tangens pierwszej liczby / drugiej liczby.
Format:
ATAN( <number>, <number> )
Uwagi:
Zwraca wartość w zakresie od -PI do PI.
Przykład:
select atan2(x, y) from z;
---–
ATANH
---–
Funkcja:
Zwraca arcus tangens hiperboliczny liczby (wyrażony w radianach).
Format:
ATANH( <number> )
Przykład:
select atanh(x) from y;
---—-
BIN_AND
---—-
Funkcja:
Zwraca wynik operacji binarnej AND wykonanej na wszystkich argumentach.
Format:
BIN\_AND( <number>, <number> \[, <number> ...\] )
Przykład:
select bin\_and(flags, 1) from x;
---—-
BIN_NOT
---—-
Funkcja:
Zwraca wynik operacji bitowej NOT wykonanej na jej argumencie.
Format:
BIN\_NOT( <number> )
Przykład:
select bin\_not(flags) from x;
---—
BIN_OR
---—
Funkcja:
Zwraca wynik operacji binarnej OR wykonanej na wszystkich argumentach.
Format:
BIN\_OR( <number>, <number> \[, <number> ...\] )
Przykład:
select bin\_or(flags1, flags2) from x;
---—-
BIN_SHL
---—-
Funkcja:
Zwraca wynik operacji binarnego przesunięcia w lewo wykonanej na argumentach (pierwszy << drugi).
Format:
BIN\_SHL( <number>, <number> )
Przykład:
select bin\_shl(flags1, 1) from x;
---—-
BIN_SHR
---—-
Funkcja:
Zwraca wynik operacji binarnego przesunięcia w prawo wykonanej na argumentach (pierwszy >> drugi).
Format:
BIN\_SHR( <number>, <number> )
Przykład:
select bin\_shr(flags1, 1) from x;
---—-
BIN_XOR
---—-
Funkcja:
Zwraca wynik operacji binarnej XOR wykonanej na wszystkich argumentach.
Format:
BIN\_XOR( <number>, <number> \[, <number> ...\] )
Przykład:
select bin\_xor(flags1, flags2) from x;
---———–
CEIL | CEILING
---———–
Funkcja:
Zwraca wartość reprezentującą najmniejszą liczbę całkowitą większą
lub równą argumentowi wejściowemu.
Format:
{ CEIL \| CEILING }( <number> )
Przykład:
1) select ceil(val) from x;
2) select ceil(2.1), ceil(-2.1) from rdb$database; -- zwraca 3, -2
---———
CHAR_TO_UUID
---———
Funkcja:
Konwertuje reprezentację ASCII CHAR(32) identyfikatora UUID
(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) na reprezentację CHAR(16) OCTETS
(zoptymalizowaną do przechowywania).
Format:
CHAR\_TO\_UUID( <string> )
Ważne (dla serwerów big-endian):
Odkryto, że przed Firebird 2.5.2 funkcje CHAR\_TO\_UUID i UUID\_TO\_CHAR działają
niepoprawnie na serwerach big-endian. Na tych maszynach bajty/znaki są zamieniane i trafiają
w niewłaściwe pozycje podczas konwersji. Ten błąd został naprawiony w wersjach 2.5.2 i 3.0, ale oznacza to, że
funkcje te zwracają teraz inne wartości (dla tego samego parametru wejściowego) niż wcześniej.
Przykład:
select char\_to\_uuid('93519227-8D50-4E47-81AA-8F6678C096A1') from rdb$database;
Zobacz także: GEN_UUID i UUID_TO_CHAR
---
COS
---
Funkcja:
Zwraca cosinus kąta (wyrażonego w radianach).
Format:
COS( <number> )
Uwagi:
Kąt jest podawany w radianach, a zwracana wartość mieści się w zakresie od -1 do 1.
Przykład:
select cos(x) from y;
----
COSH
----
Funkcja:
Zwraca cosinus hiperboliczny kąta (wyrażonego w radianach).
Format:
COSH( <number> )
Przykład:
select cosh(x) from y;
---
COT
---
Funkcja:
Zwraca 1 / tan(argument).
Format:
COT( <number> )
Przykład:
select cot(x) from y;
---—-
DATEADD
---—-
Funkcja:
Zwraca wartość typu date/time/timestamp zwiększoną (lub zmniejszoną, gdy wartość jest ujemna)
o określoną ilość czasu.
Format:
DATEADD( <number> <timestamp\_part> TO <date\_time> )
DATEADD( <timestamp\_part>, <number>, <date\_time> )
timestamp\_part ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }
Uwagi:
1) WEEKDAY i YEARDAY nie mogą być używane. Nie ma to sensu.
2) YEAR, MONTH i DAY nie mogą być używane z wartościami czasu.
3) Wszystkie wartości timestamp\_part mogą być używane z wartościami timestamp.
4) W przypadku używania hour, minute, second i millisecond z funkcją DATEADD oraz datami, dodawana lub
odejmowana ilość powinna obejmować co najmniej jeden dzień, aby przynieść efekt (tzn. dodanie 23 godzin do daty
nie zwiększa jej).
Przykład:
select dateadd(-1 day to current\_date) as yesterday
from rdb$database;
---—–
DATEDIFF
---—–
Funkcja:
Zwraca dokładną wartość numeryczną reprezentującą ilość czasu od pierwszej
wartości date/time/timestamp do drugiej.
Format:
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 }
Uwagi:
1) Zwraca wartość dodatnią, jeśli druga wartość jest większa od pierwszej,
ujemną, gdy pierwsza jest większa, lub zero, gdy są równe.
2) Porównywanie wartości typu date z wartościami czasu jest nieprawidłowe.
3) WEEKDAY i YEARDAY nie mogą być używane. Nie ma to sensu.
4) YEAR, MONTH i DAY nie mogą być używane z wartościami czasu.
5) Wszystkie wartości timestamp\_part mogą być używane z wartościami timestamp.
Przykład:
select datediff(week from cast('yesterday' as timestamp) - 7 to current\_timestamp)
from rdb$database;
---—
DECODE
---—
Funkcja:
DECODE to skrót do wyrażenia CASE ... WHEN ... ELSE.
Format:
DECODE( <expression>, <search>, <result> \[ , <search>, <result> ... \] \[, <default> \]
Przykład:
select decode(state, 0, 'deleted', 1, 'active', 'unknown') from things;
---
EXP
---
Funkcja:
Zwraca wartość funkcji wykładniczej e do potęgi argumentu.
Format:
EXP( <number> )
Przykład:
select exp(x) from y;
---–
FLOOR
---–
Funkcja:
Zwraca wartość reprezentującą największą liczbę całkowitą mniejszą
lub równą argumentowi wejściowemu.
Format:
FLOOR( <number> )
Przykład:
1) select floor(val) from x;
2) select floor(2.1), floor(-2.1) from rdb$database; -- zwraca 2, -3
---—–
GEN_UUID
---—–
Funkcja:
Zwraca uniwersalny unikalny numer w typie CHAR(16) OCTETS.
Format:
GEN\_UUID()
Ważne:
Przed Firebird 2.5.2 funkcja GEN\_UUID zwracała całkowicie losowe ciągi. Nie jest to zgodne
z RFC-4122 (specyfikacją UUID).
Zostało to naprawione w Firebird 2.5.2 i 3.0. Teraz GEN\_UUID zwraca zgodny ciąg UUID w wersji 4,
w którym niektóre bity są zarezerwowane, a pozostałe losowe. Format ciągu zgodnego
UUID to XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, gdzie 4 jest stałe (wersja), a Y to 8, 9, A lub B.
Przykład:
insert into records (id) value (gen\_uuid());
Zobacz także: CHAR_TO_UUID i UUID_TO_CHAR
----
HASH
----
Funkcja:
Zwraca HASH ciągu.
Format:
HASH( <string> )
Przykład:
select hash(x) from y;
----
LEFT
----
Funkcja:
Zwraca podciąg o określonej długości, który pojawia się na początku ciągu.
Format:
LEFT( <string>, <number> )
Przykład:
select left(name, char\_length(name) - 10)
from people
where name like '% FERNANDES';
–
LN
–
Funkcja:
Zwraca logarytm naturalny liczby.
Format:
LN( <number> )
Przykład:
select ln(x) from y;
---
LOG
---
Funkcja:
LOG(x, y) zwraca logarytm o podstawie x z y.
Format:
LOG( <number>, <number> )
Przykład:
select log(x, 10) from y;
---–
LOG10
---–
Funkcja:
Zwraca logarytm dziesiętny liczby.
Format:
LOG10( <number> )
Przykład:
select log10(x) from y;
----
LPAD
----
Funkcja:
LPAD(string1, length, string2) dołącza string2 na początku
string1, aż długość ciągu wynikowego zrówna się z length.
Format:
LPAD( <string>, <number> \[, <string> \] )
Uwagi:
1) Jeśli drugi ciąg zostanie pominięty, wartością domyślną jest jedna spacja.
2) Drugi ciąg jest obcinany, gdy ciąg wynikowy
stałby się dłuższy niż length.
3) Pierwszy ciąg jest obcinany, jeśli jego długość jest większa niż parametr
length.
Przykład:
select lpad(x, 10) from y;
---—–
MAXVALUE
---—–
Funkcja:
Zwraca maksymalną wartość z listy wartości.
Format:
MAXVALUE( <value> \[, <value> ...\] )
Przykład:
select maxvalue(v1, v2, 10) from x;
---—–
MINVALUE
---—–
Funkcja:
Zwraca minimalną wartość z listy wartości.
Format:
MINVALUE( <value> \[, <value> ...\] )
Przykład:
select minvalue(v1, v2, 10) from x;
---
MOD
---
Funkcja:
MOD(X, Y) zwraca resztę z dzielenia X przez Y.
Format:
MOD( <number>, <number> )
Przykład:
select mod(x, 10) from y;
---—-
OVERLAY
---—-
Funkcja:
OVERLAY( <string1> PLACING <string2> FROM <start> \[ FOR <length> \] ) zwraca
string1, zastępując podciąg FROM start FOR length ciągiem string2.
Format:
OVERLAY( <string> PLACING <string> FROM <number> \[ FOR <number> \] )
Uwagi:
1) Jeśli <length> nie jest określone, przyjmuje się CHAR\_LENGTH( <string2> ).
2) Funkcja OVERLAY jest równoważna:
SUBSTRING(<string1> FROM 1 FOR <start> - 1) \|\|
<string2> \|\|
SUBSTRING(<string1> FROM <start> + <length>)
–
PI
–
Funkcja:
Zwraca stałą PI (3.1459...).
Format:
PI()
Przykład:
val = PI();
---—–
POSITION
---—–
Funkcja:
Zwraca pozycję pierwszego ciągu wewnątrz drugiego ciągu, począwszy od
przesunięcie (lub od początku, gdy pominięte). Gdy nie znaleziono, zwraca 0.
Format:
POSITION( <string> IN <string> )
POSITION( <string>, <string> \[, <number>\] )
Przykład:
select rdb$relation\_name
from rdb$relations
where position('RDB$' IN rdb$relation\_name) = 1;
---–
POWER
---–
Funkcja:
POWER(X, Y) zwraca X podniesione do potęgi Y.
Format:
POWER( <number>, <number> )
Przykład:
select power(x, 10) from y;
----
RAND
----
Funkcja:
Zwraca losową liczbę z zakresu od 0 do 1.
Format:
RAND()
Przykład:
select \* from x order by rand();
---—-
REPLACE
---—-
Funkcja:
REPLACE(searched, find, replacement) zastępuje wszystkie wystąpienia "find"
w "searched" przez "replacement".
Format:
REPLACE( <string>, <string>, <string> )
Przykład:
select replace(x, ' ', ',') from y;
---—-
REVERSE
---—-
Funkcja:
Zwraca ciąg znaków w odwrotnej kolejności.
Format:
REVERSE( <value> )
Uwagi:
REVERSE to użyteczna funkcja do indeksowania ciągów znaków od prawej do lewej.
Przykład:
create index people\_email on people computed by (reverse(email));
select \* from people where reverse(email) starting with reverse('.br');
---–
RIGHT
---–
Funkcja:
RIGHT(string, length)
Zwraca podciąg o określonej długości, który znajduje się na końcu ciągu znaków.
Format:
RIGHT( <string>, <number> )
Przykład:
select right(rdb$relation\_name, char\_length(rdb$relation\_name) - 4)
from rdb$relations
where rdb$relation\_name like 'RDB$%';
---–
ROUND
---–
Funkcja:
ROUND(number, scale)
Zwraca liczbę zaokrągloną do określonej skali.
Format:
ROUND( <number> \[, <number> \] )
Uwagi:
Jeśli skala (drugi parametr) jest ujemna, zaokrąglana jest część całkowita
wartości. Np.: ROUND(123.456, -1) zwraca 120.000.
Przykłady:
select round(salary \* 1.1, 0) from people;
----
RPAD
----
Funkcja:
RPAD(string1, length, string2) dołącza string2 na końcu
string1, aż długość wynikowego ciągu znaków zrówna się z length.
Format:
RPAD( <string>, <number> \[, <string> \] )
Uwagi:
1) Jeśli drugi ciąg znaków zostanie pominięty, domyślną wartością jest jedna spacja.
2) Drugi ciąg znaków jest obcinany, gdy wynikowy ciąg znaków
stanie się dłuższy niż length.
3) Pierwszy ciąg znaków jest obcinany, jeśli jego długość jest większa niż parametr
length.
Przykład:
select rpad(x, 10) from y;
----
SIGN
----
Funkcja:
Zwraca 1, 0 lub -1 w zależności od tego, czy wartość wejściowa jest odpowiednio dodatnia, zerowa
czy ujemna.
Format:
SIGN( <number> )
Przykład:
select sign(x) from y;
---
SIN
---
Funkcja:
Zwraca sinus kąta (wyrażonego w radianach).
Format:
SIN( <number> )
Uwagi:
Argument funkcji SIN musi być podany w radianach.
Przykład:
select sin(x) from y;
----
SINH
----
Funkcja:
Zwraca sinus hiperboliczny kąta (wyrażonego w radianach).
Format:
SINH( <number> )
Przykład:
select sinh(x) from y;
----
SQRT
----
Funkcja:
Zwraca pierwiastek kwadratowy liczby.
Format:
SQRT( <number> )
Przykład:
select sqrt(x) from y;
---
TAN
---
Funkcja:
Zwraca tangens kąta (wyrażonego w radianach).
Format:
TAN( <number> )
Uwagi:
Argument funkcji TAN musi być podany w radianach.
Przykład:
select tan(x) from y;
----
TANH
----
Funkcja:
Zwraca tangens hiperboliczny kąta (wyrażonego w radianach).
Format:
TANH( <number> )
Przykład:
select tanh(x) from y;
---–
TRUNC
---–
Funkcja:
TRUNC(number, scale)
Zwraca część całkowitą (do określonej skali) liczby.
Format:
TRUNC( <number> \[, <number> \] )
Uwagi:
Jeśli skala (drugi parametr) jest ujemna, część całkowita
wartości jest obcinana. Np.: TRUNC(123.456, -1) zwraca 120.000.
Przykład:
1) select trunc(x) from y;
2) select trunc(-2.8), trunc(2.8) from rdb$database; -- zwraca -2, 2
3) select trunc(987.65, 1), trunc(987.65, -1) from rdb$database; -- zwraca 987.60, 980.00
---———
UUID_TO_CHAR
---———
Funkcja:
Konwertuje UUID typu CHAR(16) OCTETS (zwracany przez GEN\_UUID) na
reprezentację ASCII typu CHAR(32) (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).
Format:
UUID\_TO\_CHAR( <string> )
Ważne (dla serwerów big-endian):
Odkryto, że przed Firebird 2.5.2 funkcje CHAR\_TO\_UUID i UUID\_TO\_CHAR działają
niepoprawnie na serwerach big-endian. Na tych maszynach bajty/znaki są zamieniane i trafiają
w niewłaściwe pozycje podczas konwersji. Ten błąd został naprawiony w wersjach 2.5.2 i 3.0, ale oznacza to, że
funkcje te zwracają teraz inne wartości (dla tego samego parametru wejściowego) niż wcześniej.
Przykład:
select uuid\_to\_char(gen\_uuid()) from rdb$database;
Zobacz także: GEN_UUID i CHAR_TO_UUID