Вбудовані функції Firebird 3.0 (SDF, тобто Server Defined Functions)
Наведені нижче вбудовані функції (крім DECODE) використовуються лише за відсутності
UDF, оголошеної з тим самим ім’ям.
Цей вибір між UDF і системною функцією визначається під час компіляції
інструкції та не змінюється, якщо інструкція збережена (тригер / SP).
Автори:
Adriano dos Santos Fernandes <[email protected]>
Oleg Loa <[email protected]>
Alexey Karyakin <[email protected]>
Claudio Valderrama C. <cvalde at usa.net>
---
ABS
---
Функція:
Повертає абсолютне значення числа.
Формат:
ABS( <number> )
Приклад:
select abs(amount) from transactions;
----
ACOS
----
Функція:
Повертає арккосинус числа.
Формат:
ACOS( <number> )
Примітки:
Аргумент ACOS має бути в діапазоні від -1 до 1, а функція повертає значення в
діапазоні від 0 до PI.
Приклад:
select acos(x) from y;
---–
ACOSH
---–
Функція:
Повертає гіперболічний арккосинус числа (виражений у радіанах).
Формат:
ACOSH( <number> )
Приклад:
select acosh(x) from y;
---——-
ASCII_CHAR
---——-
Функція:
Повертає ASCII-символ із заданим кодом.
Формат:
ASCII\_CHAR( <number> )
Примітки:
Аргумент ASCII\_CHAR має бути в діапазоні від 0 до 255, а функція повертає значення
з набором символів NONE.
Приклад:
select ascii\_char(x) from y;
---——
ASCII_VAL
---——
Функція:
Повертає ASCII-код першого символу вказаного рядка.
Формат:
ASCII\_VAL( <string> )
Примітки:
1) Повертає 0, якщо рядок порожній.
2) Викидає помилку, якщо перший символ є багатобайтовим.
Приклад:
select ascii\_val(x) from y;
----
ASIN
----
Функція:
Повертає арксинус числа.
Формат:
ASIN( <number> )
Примітки:
Аргумент ASIN має бути в діапазоні від -1 до 1, а функція повертає значення в
діапазоні від -PI / 2 до PI / 2.
Приклад:
select asin(x) from y;
---–
ASINH
---–
Функція:
Повертає гіперболічний арксинус числа (виражений у радіанах).
Формат:
ASINH( <number> )
Приклад:
select asinh(x) from y;
----
ATAN
----
Функція:
Повертає арктангенс числа.
Формат:
ATAN( <number> )
Примітки:
Повертає значення в діапазоні від -PI / 2 до PI / 2.
Приклад:
select atan(x) from y;
---–
ATAN2
---–
Функція:
Повертає арктангенс першого числа / другого числа.
Формат:
ATAN( <number>, <number> )
Примітки:
Повертає значення в діапазоні від -PI до PI.
Приклад:
select atan2(x, y) from z;
---–
ATANH
---–
Функція:
Повертає гіперболічний арктангенс числа (виражений у радіанах).
Формат:
ATANH( <number> )
Приклад:
select atanh(x) from y;
---—-
BIN_AND
---—-
Функція:
Повертає результат побітової операції AND, виконаної над усіма аргументами.
Формат:
BIN\_AND( <number>, <number> \[, <number> ...\] )
Приклад:
select bin\_and(flags, 1) from x;
---—-
BIN_NOT
---—-
Функція:
Повертає результат побітової операції NOT, виконаної над її аргументом.
Формат:
BIN\_NOT( <number> )
Приклад:
select bin\_not(flags) from x;
---—
BIN_OR
---—
Функція:
Повертає результат побітової операції OR, виконаної над усіма аргументами.
Формат:
BIN\_OR( <number>, <number> \[, <number> ...\] )
Приклад:
select bin\_or(flags1, flags2) from x;
---—-
BIN_SHL
---—-
Функція:
Повертає результат побітового зсуву вліво, виконаного над аргументами (перший << другий).
Формат:
BIN\_SHL( <number>, <number> )
Приклад:
select bin\_shl(flags1, 1) from x;
---—-
BIN_SHR
---—-
Функція:
Повертає результат побітового зсуву вправо, виконаного над аргументами (перший >> другий).
Формат:
BIN\_SHR( <number>, <number> )
Приклад:
select bin\_shr(flags1, 1) from x;
---—-
BIN_XOR
---—-
Функція:
Повертає результат побітової операції XOR, виконаної над усіма аргументами.
Формат:
BIN\_XOR( <number>, <number> \[, <number> ...\] )
Приклад:
select bin\_xor(flags1, flags2) from x;
---———–
CEIL | CEILING
---———–
Функція:
Повертає значення, що представляє найменше ціле число, яке є більшим
або рівним вхідному аргументу.
Формат:
{ CEIL \| CEILING }( <number> )
Приклад:
1) select ceil(val) from x;
2) select ceil(2.1), ceil(-2.1) from rdb$database; -- повертає 3, -2
---———
CHAR_TO_UUID
---———
Функція:
Перетворює ASCII-представлення UUID у вигляді CHAR(32)
(XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) на представлення CHAR(16) OCTETS
(оптимізоване для зберігання).
Формат:
CHAR\_TO\_UUID( <string> )
Важливо (для серверів з порядком байтів big-endian):
Було виявлено, що до Firebird 2.5.2 CHAR\_TO\_UUID і UUID\_TO\_CHAR працюють
неправильно на серверах з порядком байтів big-endian. На цих машинах байти/символи міняються місцями та потрапляють у
неправильні позиції під час перетворення. Цю помилку було виправлено в 2.5.2 і 3.0, але це означає, що ці
функції тепер повертають інші значення (для того самого вхідного параметра), ніж раніше.
Приклад:
select char\_to\_uuid('93519227-8D50-4E47-81AA-8F6678C096A1') from rdb$database;
Див. також: GEN_UUID і UUID_TO_CHAR
---
COS
---
Функція:
Повертає косинус кута (вираженого в радіанах).
Формат:
COS( <number> )
Примітки:
Кут задається в радіанах, а функція повертає значення в діапазоні від -1 до 1.
Приклад:
select cos(x) from y;
----
COSH
----
Функція:
Повертає гіперболічний косинус кута (вираженого в радіанах).
Формат:
COSH( <number> )
Приклад:
select cosh(x) from y;
---
COT
---
Функція:
Повертає 1 / tan(аргумент).
Формат:
COT( <number> )
Приклад:
select cot(x) from y;
---—-
DATEADD
---—-
Функція:
Повертає значення дати/часу/мітки часу, збільшене (або зменшене, якщо від'ємне)
на вказану кількість часу.
Формат:
DATEADD( <number> <timestamp\_part> TO <date\_time> )
DATEADD( <timestamp\_part>, <number>, <date\_time> )
timestamp\_part ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }
Примітки:
1) WEEKDAY і YEARDAY використовувати не можна. Це не має сенсу.
2) YEAR, MONTH і DAY не можна використовувати зі значеннями часу.
3) Усі значення timestamp\_part можна використовувати зі значеннями мітки часу.
4) Під час використання hour, minute, second і millisecond для DATEADD і дат кількість, що додається або
віднімається, має становити щонайменше один день, щоб мати ефект (тобто додавання 23 годин до дати
не збільшує її).
Приклад:
select dateadd(-1 day to current\_date) as yesterday
from rdb$database;
---—–
DATEDIFF
---—–
Функція:
Повертає точне числове значення, що представляє кількість часу від першого
значення дати/часу/мітки часу до другого.
Формат:
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 }
Примітки:
1) Повертає додатне значення, якщо друге значення більше за перше,
від'ємне, якщо перше більше, або нуль, якщо вони рівні.
2) Порівняння дати зі значеннями часу є недопустимим.
3) WEEKDAY і YEARDAY використовувати не можна. Це не має сенсу.
4) YEAR, MONTH і DAY не можна використовувати зі значеннями часу.
5) Усі значення timestamp\_part можна використовувати зі значеннями мітки часу.
Приклад:
select datediff(week from cast('yesterday' as timestamp) - 7 to current\_timestamp)
from rdb$database;
---—
DECODE
---—
Функція:
DECODE — це скорочення для виразу CASE ... WHEN ... ELSE.
Формат:
DECODE( <expression>, <search>, <result> \[ , <search>, <result> ... \] \[, <default> \]
Приклад:
select decode(state, 0, 'deleted', 1, 'active', 'unknown') from things;
EXP
Функція:
Повертає експоненту e у степені аргументу.
Формат:
EXP( <number> )
Приклад:
select exp(x) from y;
---–
FLOOR
---–
Функція:
Повертає значення, що представляє найбільше ціле число, яке є меншим
або рівним вхідному аргументу.
Формат:
FLOOR( <number> )
Приклад:
1) select floor(val) from x;
2) select floor(2.1), floor(-2.1) from rdb$database; -- повертає 2, -3
---—–
GEN_UUID
---—–
Функція:
Повертає універсальний унікальний номер типу CHAR(16) OCTETS.
Формат:
GEN\_UUID()
Важливо:
До Firebird 2.5.2 GEN\_UUID повертала повністю випадкові рядки. Це не відповідає
RFC-4122 (специфікації UUID).
Це було виправлено у Firebird 2.5.2 та 3.0. Тепер GEN\_UUID повертає сумісний рядок
UUID версії 4, де деякі біти зарезервовані, а інші випадкові. Рядковий формат сумісного
UUID — XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX, де 4 фіксована (версія), а Y — 8, 9, A або B.
Приклад:
insert into records (id) value (gen\_uuid());
Див. також: CHAR_TO_UUID та UUID_TO_CHAR
----
HASH
----
Функція:
Повертає HASH рядка.
Формат:
HASH( <string> )
Приклад:
select hash(x) from y;
----
LEFT
----
Функція:
Повертає підрядок заданої довжини, що починається з початку рядка.
Формат:
LEFT( <string>, <number> )
Приклад:
select left(name, char\_length(name) - 10)
from people
where name like '% FERNANDES';
–
LN
–
Функція:
Повертає натуральний логарифм числа.
Формат:
LN( <number> )
Приклад:
select ln(x) from y;
---
LOG
---
Функція:
LOG(x, y) повертає логарифм y за основою x.
Формат:
LOG( <number>, <number> )
Приклад:
select log(x, 10) from y;
---–
LOG10
---–
Функція:
Повертає логарифм числа за основою десять.
Формат:
LOG10( <number> )
Приклад:
select log10(x) from y;
----
LPAD
----
Функція:
LPAD(string1, length, string2) додає string2 на початок
string1, доки довжина результуючого рядка не стане рівною length.
Формат:
LPAD( <string>, <number> \[, <string> \] )
Примітки:
1) Якщо другий рядок не вказано, значенням за замовчуванням є один пробіл.
2) Другий рядок обрізається, коли результуючий рядок
стає довшим за length.
3) Перший рядок обрізається, якщо його довжина перевищує параметр
length.
Приклад:
select lpad(x, 10) from y;
---—–
MAXVALUE
---—–
Функція:
Повертає максимальне значення зі списку значень.
Формат:
MAXVALUE( <value> \[, <value> ...\] )
Приклад:
select maxvalue(v1, v2, 10) from x;
---—–
MINVALUE
---—–
Функція:
Повертає мінімальне значення зі списку значень.
Формат:
MINVALUE( <value> \[, <value> ...\] )
Приклад:
select minvalue(v1, v2, 10) from x;
---
MOD
---
Функція:
MOD(X, Y) повертає остачу від ділення X на Y.
Формат:
MOD( <number>, <number> )
Приклад:
select mod(x, 10) from y;
---—-
OVERLAY
---—-
Функція:
OVERLAY( <string1> PLACING <string2> FROM <start> \[ FOR <length> \] ) повертає
string1, замінюючи підрядок FROM start FOR length на string2.
Формат:
OVERLAY( <string> PLACING <string> FROM <number> \[ FOR <number> \] )
Примітки:
1) Якщо <length> не вказано, мається на увазі CHAR\_LENGTH( <string2> ).
2) Функція OVERLAY еквівалентна:
SUBSTRING(<string1> FROM 1 FOR <start> - 1) \|\|
<string2> \|\|
SUBSTRING(<string1> FROM <start> + <length>)
–
PI
–
Функція:
Повертає константу PI (3.1459...).
Формат:
PI()
Приклад:
val = PI();
---—–
POSITION
---—–
Функція:
Повертає позицію першого рядка всередині другого рядка, починаючи зі
зсуву (або з початку, якщо не вказано). Якщо не знайдено, повертає 0.
Формат:
POSITION( <string> IN <string> )
POSITION( <string>, <string> \[, <number>\] )
Приклад:
select rdb$relation\_name
from rdb$relations
where position('RDB$' IN rdb$relation\_name) = 1;
---–
POWER
---–
Функція:
POWER(X, Y) повертає X у степені Y.
Формат:
POWER( <number>, <number> )
Приклад:
select power(x, 10) from y;
----
RAND
----
Функція:
Повертає випадкове число між 0 та 1.
Формат:
RAND()
Приклад:
select \* from x order by rand();
---—-
REPLACE
---—-
Функція:
REPLACE(searched, find, replacement) замінює всі входження "find"
у "searched" на "replacement".
Формат:
REPLACE( <string>, <string>, <string> )
Приклад:
select replace(x, ' ', ',') from y;
---—-
REVERSE
---—-
Функція:
Повертає рядок у зворотному порядку.
Формат:
REVERSE( <value> )
Примітки:
REVERSE — корисна функція для індексування рядків справа наліво.
Приклад:
create index people\_email on people computed by (reverse(email));
select \* from people where reverse(email) starting with reverse('.br');
---–
RIGHT
---–
Функція:
RIGHT(string, length)
Повертає підрядок заданої довжини, що знаходиться в кінці рядка.
Формат:
RIGHT( <string>, <number> )
Приклад:
select right(rdb$relation\_name, char\_length(rdb$relation\_name) - 4)
from rdb$relations
where rdb$relation\_name like 'RDB$%';
---–
ROUND
---–
Функція:
ROUND(number, scale)
Повертає число, округлене до вказаної точності.
Формат:
ROUND( <number> \[, <number> \] )
Примітки:
Якщо точність (другий параметр) від'ємна, ціла частина
значення округлюється. Напр.: ROUND(123.456, -1) повертає 120.000.
Приклади:
select round(salary \* 1.1, 0) from people;
----
RPAD
----
Функція:
RPAD(string1, length, string2) додає string2 у кінець
string1, доки довжина результуючого рядка не стане рівною length.
Формат:
RPAD( <string>, <number> \[, <string> \] )
Примітки:
1) Якщо другий рядок не вказано, значенням за замовчуванням є один пробіл.
2) Другий рядок обрізається, коли результуючий рядок
стає довшим за length.
3) Перший рядок обрізається, якщо його довжина перевищує параметр
length.
Приклад:
select rpad(x, 10) from y;
----
SIGN
----
Функція:
Повертає 1, 0 або -1 залежно від того, чи вхідне значення є додатним, нульовим
або від'ємним відповідно.
Формат:
SIGN( <number> )
Приклад:
select sign(x) from y;
---
SIN
---
Функція:
Повертає синус кута (вираженого в радіанах).
Формат:
SIN( <number> )
Примітки:
Аргумент SIN має бути вказаний у радіанах.
Приклад:
select sin(x) from y;
----
SINH
----
Функція:
Повертає гіперболічний синус кута (вираженого в радіанах).
Формат:
SINH( <number> )
Приклад:
select sinh(x) from y;
----
SQRT
----
Функція:
Повертає квадратний корінь числа.
Формат:
SQRT( <number> )
Приклад:
select sqrt(x) from y;
---
TAN
---
Функція:
Повертає тангенс кута (вираженого в радіанах).
Формат:
TAN( <number> )
Примітки:
Аргумент TAN має бути вказаний у радіанах.
Приклад:
select tan(x) from y;
----
TANH
----
Функція:
Повертає гіперболічний тангенс кута (вираженого в радіанах).
Формат:
TANH( <number> )
Приклад:
select tanh(x) from y;
---–
TRUNC
---–
Функція:
TRUNC(number, scale)
Повертає цілу частину (до вказаної точності) числа.
Формат:
TRUNC( <number> \[, <number> \] )
Примітки:
Якщо точність (другий параметр) від'ємна, ціла частина
значення відсікається. Напр.: TRUNC(123.456, -1) повертає 120.000.
Приклад:
1) select trunc(x) from y;
-
select trunc(-2.8), trunc(2.8) from rdb$database; – повертає -2, 2
- select trunc(987.65, 1), trunc(987.65, -1) from rdb$database; – повертає 987.60, 980.00
---———
UUID_TO_CHAR
---———
Функція:
Перетворює UUID типу CHAR(16) OCTETS (який повертає GEN\_UUID) у
ASCII-представлення CHAR(32) (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).
Формат:
UUID\_TO\_CHAR( <string> )
Важливо (для серверів із big-endian):
Було виявлено, що до Firebird 2.5.2 CHAR\_TO\_UUID та UUID\_TO\_CHAR працюють
неправильно на серверах із big-endian. На таких машинах байти/символи переставляються місцями й потрапляють
у неправильні позиції під час перетворення. Цю помилку було виправлено в 2.5.2 та 3.0, але це означає, що ці
функції тепер повертають інші значення (для того самого вхідного параметра), ніж раніше.
Приклад:
select uuid\_to\_char(gen\_uuid()) from rdb$database;
Див. також: GEN_UUID та CHAR_TO_UUID