Встроенные функции 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 можно использовать со значениями timestamp.
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 можно использовать со значениями timestamp.
Пример:
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