Операторы процедурного SQL (PSQL)Агрегатные функции

Примеры `NULLIF`

Example 1. Использование функции NULLIF

SELECT AVG(NULLIF(weight, -1)) FROM cargo;

Этот запрос возвращает среднее значение поля weight по таблице,за исключением строк, где он не указан (равен -1).Если бы не было этой функции простой оператор avg(weight)вернул бы некорректное значение.

См. также:

[fblangref-scalarfuncs-coalesce], CASE.

Другие функции

В этом разделе расположены функции, которые сложно отнести к какой-либо категории.

docnext count = 100

`MAKE_DBKEY()`

Доступно в

DSQL, PSQL

Синтаксис

MAKE_DBKEY (<relation>, recnum [, dpnum [, ppnum]]})

<relation> ::= rel_name | rel_id

Table 1. Параметры функции `MAKE_DBKEY`
Параметр	Описание
rel_name	Имя таблицы.
rel_id	Идентификатор таблицы.Можно найти в `RDB$RELATIONS.RDB$RELATION_ID`.
recnum	Номер записи.Либо абсолютный (если dpnum и ppnum отсутствуют), либо относительный (если dpnum присутствует)
dpnum	Номер страницы данных DP.Либо абсолютный (если ppnum отсутствует), либо относительный (если ppnum присутствует)
ppnum	Номер страницы указателей на данные PP.

Функция MAKE_DBKEY создаёт значение DBKEY, используя имя или идентификатор таблицы, номер записи и, необязательно, логический номер страницы данных и страницы указателя.

Note

Замечания

Если первый аргумент (таблица) является строковым выражением или литералом, то он обрабатывается как имя таблицы, и Firebird ищет соответствующий идентификатор таблицы. Поиск чувствителен к регистру.

В случае строкового литерала идентификатор таблицы оценивается во время подготовки.В случае выражения, идентификатор таблицы оценивается во время выполнения.

Если таблица не может быть найдена, возникает ошибка isc_relnotdef.
Если первый аргумент (таблица) является числовым выражением или литералом, то он обрабатывается как идентификатор таблицы и используется «как есть», без проверки существования таблицы.

Если значение аргумента отрицательно или превышает максимально допустимый идентификатор таблицы (в настоящее время 65535), то возвращается NULL.
Второй аргумент (recnum) представляет собой абсолютный номер записи в отношении (если следующие аргументы — dpnum и ppnum — отсутствуют) или номер записи относительно первой записи, указанной в следующих аргументах.
Третий аргумент (dpnum) — это логический номер страницы данных (DP) в таблице (если следующий аргумент — ppnum — отсутствует) или номер страницы данных относительно первой страницы данных, адресованной заданным ppnum.
Четвёртый аргумент (ppnum) — это логический номер страницы указателя (PP) в таблице.
Все числа начинаются с нуля. Максимально допустимое значение для dpnum и ppnum составляет 2³² (4294967296).

Если указан параметр dpnum, значение recnum может быть отрицательным.

Если dpnum отсутствует и recnum отрицательно, возвращается NULL.

Если указан ppnum, то dpnum может быть отрицательным.

Если ppnum отсутствует и dpnum отрицателен, возвращается NULL.
Если какой-либо из указанных аргументов имеет значение NULL, результат также равен NULL.
Первый аргумент (таблица) описывается как INTEGER, но может быть переопределен приложением как VARCHAR или CHAR.

recnum, dpnum и ppnum описываются как BIGINT (64-разрядное целое число со знаком).

Примеры:

Запрос выбирает запись, используя имя таблицы (имя таблицы в верхнем регистре)
```
select * from rdb$relations where rdb$db_key = make_dbkey('RDB$RELATIONS', 0)
```
Запрос выбирает запись, используя идентификатор таблицы
```
select * from rdb$relations where rdb$db_key = make_dbkey(6, 0)
```
Запрос выбирает все записи, которые физически находятся на первой странице данных в таблице
```
select * from rdb$relations
where rdb$db_key >= make_dbkey(6, 0, 0)
  and rdb$db_key <  make_dbkey(6, 0, 1)
```
Запрос выбирает все записи, которые физически находятся на первой странице данных 6-й страницы указателя в таблице
```
select * from SOMETABLE
where rdb$db_key >= make_dbkey('SOMETABLE', 0, 0, 5)
  and rdb$db_key <  make_dbkey('SOMETABLE', 0, 1, 5)
```

См. также: [fblangref-appx-supp-rdb-dbkey].

`RDB$ERROR()`

Доступно в

PSQL

Синтаксис

RDB$ERROR (<context>)

<context> ::= GDSCODE | SQLCODE | SQLSTATE | EXCEPTION | MESSAGE

Тип возвращаемого результата

Зависит от контекста

Возвращает значение контекста активного исключения.Тип возвращаемого значения зависит от контекста.

Note	Функция `RDB$ERROR` всегда возвращает `NULL` вне блока обработки ошибок `WHEN … DO`.

Доступные контексты в качестве аргумента функции RDB$ERROR:

EXCEPTION: функция возвращает имя исключения, если активно исключение определённое пользователем, или NULL если активно одно из системных исключений.Для контекста EXCEPTION тип возвращаемого значения: VARCHAR(63) CHARACTER SET UTF8.
MESSAGE: функция возвращает интерпретированный текст активного исключения.Для контекста MESSAGE тип возвращаемого значения: VARCHAR(1024) CHARACTER SET UTF8.
GDSCODE: функция возвращает значение контекстной переменной GDSCODE.
SQLCODE: функция возвращает значение контекстной переменной SQLCODE.
SQLSTATE: функция возвращает значение контекстной переменной SQLSTATE.

Example 1. Использование функции RDB$ERROR для сохранения текста ошибки в журнал

...
BEGIN
...
WHEN ANY DO
  EXECUTE PROCEDURE P_LOG_EXCEPTION(RDB$ERROR(MESSAGE));
END
...

См. также:

WHEN … DO,EXCEPTION,GDSCODE,SQLCODE,SQLSTATE.

`RDB$GET_TRANSACTION_CN()`

Доступно в

DSQL, PSQL

Синтаксис

RDB$GET_TRANSACTION_CN (transaction_id)

Table 1. Параметры функции RDB$GET_TRANSACTION_CN
Параметр	Описание
transaction_id	Номер (идентификатор) транзакции

Тип возвращаемого результата:

BIGINT

Возвращает номер подтверждения (Commit Number) для заданной транзакции.

Note

Внутренние механизмы Firebird используют беззнаковое 8-байтное целое для Commit Number и беззнаковое 6-байтное целое для номера транзакции.Поэтому, несмотря на то, что язык SQL не имеет без знаковых целых, а RDB$GET_TRANSACTION_CN возвращает знаковый BIGINT, невозможно увидеть отрицательный номер подтверждения, за исключением нескольких специальных значений, используемых для неподтверждённых транзакций.

Если функция RDB$GET_TRANSACTION_CN возвращает значение больше 1, то это фактический (Commit Number) транзакции,то есть эта транзакция была зафиксирована после запуска базы данных.

В остальных случая функция может возвращать одно из следующих результатов, указывающих статус фиксации транзакции:

`-2`	мёртвые транзакции (отмененные);
`-1`	зависшие транзакции (в состоянии limbo 2PC транзакций);
`0`	активные транзакции;
`1`	для транзакций подтверждённых до старта базы данных или с номером меньше чем OIT (Oldest Interesting Transaction);
`NULL`	если номер транзакции равен `NULL` или больше чем Next Transaction.

Example 1. Использование RDB$GET_TRANSACTION_CN

select rdb$get_transaction_cn(current_transaction) from rdb$database;

select rdb$get_transaction_cn(123) from rdb$database;

Note	За более детальной информацией о Commit Number, обратитесь к Firebird 4.0 Release Notes.

`RDB$ROLE_IN_USE()`

Доступно в

DSQL, PSQL

Синтаксис

RDB$ROLE_IN_USE (role_name)

Table 1. Параметры функции `RDB$ROLE_IN_USE`
Параметр	Описание
role_name	Имя роли использование которой проверяется

Тип возвращаемого результата

BOOLEAN

Функция RDB$ROLE_IN_USE возвращает используется ли роль текущим пользователем.

Note	Данная функция позволяет проверить использование любой роли: указанной явно (при входе в систему или изменённой с помощью оператора SET ROLE) и назначенной неявно (роли назначенные пользователю с использованием предложения DEFAULT).

Example 1. Использование функции RDB$ROLE_IN_USE

-- Проверяем используется ли явно назначенная или
-- неявно полученная роль MANAGER
IF (RDB$ROLE_IN_USE('MANAGER')) THEN
BEGIN
  ...
END

Example 2. Список ролей используемых текущим подключением

SELECT * FROM RDB$ROLES WHERE RDB$ROLE_IN_USE(RDB$ROLE_NAME)

См. также:

GRANT ROLE, SET ROLE, CURRENT_ROLE.

`RDB$SYSTEM_PRIVILEGE()`

Доступно в

DSQL, PSQL

Синтаксис

RDB$SYSTEM_PRIVILEGE (<privilege>)

Table 1. Параметры функции `RDB$SYSTEM_PRIVILEGE`
Параметр	Описание
privilege	Проверяемая системная привилегия

Тип возвращаемого результата

BOOLEAN

Функция RDB$SYSTEM_PRIVILEGE используется системная привилегия текущим соединением.Список системных привилегий см.в CREATE ROLE.

Example 1. Использование функции RDB$SYSTEM_PRIVILEGE

SELECT RDB$SYSTEM_PRIVILEGE(USER_MANAGEMENT) FROM RDB$DATABASE;

См. также:

CREATE ROLE.

Математические функции

`ABS()`

Доступно в

DSQL, PSQL

Синтаксис

ABS (number)

Table 1. Параметры функции `ABS`
Параметр	Описание
number	Выражение числового типа

Тип возвращаемого результата:

тот же что и входной аргумент.

Функция ABS возвращает абсолютное значение (модуль) аргумента.

`COS()`

Доступно в

DSQL, PSQL

Синтаксис

COS (angle)

Table 1. Параметры функции `COS`
Параметр	Описание
angle	Угол, выраженный в радианах.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция COS возвращает косинус угла.Аргумент должен быть задан в радианах.

Любой NOT NULL результат находится в диапазоне [-1, 1].

См. также:

[fblangref-scalarfuncs-acos].

`COSH()`

Доступно в

DSQL, PSQL

Синтаксис

COSH (number)

Table 1. Параметры функции `COSH`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция COSH возвращает гиперболический косинус аргумента.

Любой NOT NULL результат находится в диапазоне [1, +∞].

См. также:

[fblangref-scalarfuncs-acosh].

`COT()`

Доступно в

DSQL, PSQL

Синтаксис

COT (angle)

Table 1. Параметры функции `COT`
Параметр	Описание
angle	Угол, выраженный в радианах.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция COT возвращает котангенс угла.Аргумент должен быть задан в радианах.

См. также:

[fblangref-scalarfuncs-tan].

`EXP()`

Доступно в

DSQL, PSQL

Синтаксис

EXP (number)

Table 1. Параметры функции `EXP`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция EXP возвращает значение натуральной экспоненты, e^number

См. также:

[fblangref-scalarfuncs-ln].

`FLOOR()`

Доступно в

DSQL, PSQL

Синтаксис

FLOOR (number)

Table 1. Параметры функции `FLOOR`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

BIGINT, INT128, DECFLOAT или DOUBLE PRECISION в зависимости от типа аргумента.

Функция FLOOR возвращает целое число, меньшее или равное аргументу.

См. также:

[fblangref-scalarfuncs-ceil], [fblangref-scalarfuncs-trunc].

`LN()`

Доступно в

DSQL, PSQL

Синтаксис

LN (number)

Table 1. Параметры функции `LN`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция LN возвращает натуральный логарифм аргумента.

Note	В случае если передан отрицательный или нулевой аргумент функция вернёт ошибку.

См. также:

[fblangref-scalarfuncs-exp].

`LOG()`

Доступно в

DSQL, PSQL

Синтаксис

LOG (x, y)

Table 1. Параметры функции `LOG`
Параметр	Описание
x	Основание.Выражение числового типа.
y	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция LOG возвращает логарифм y (второй аргумент) по основанию x (первый аргумент).

Особенности использования:

Если один из аргументов меньше или равен 0, то возникает ошибка;
Если оба аргумента равны 1, то результатом функции будет NaN (Not-a-Number — не число);
Если x = 1 и y < 1, то результатом функции будет -INF (-∞);
Если x = 1 и y > 1, то результатом функции будет `INF` (∞).

`LOG10()`

Доступно в

DSQL, PSQL

Синтаксис

LOG10 (number)

Table 1. Параметры функции `LOG10`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция LOG10 возвращает десятичный логарифм аргумента.

Note	Если входной аргумент отрицательный или равен 0, возникает ошибка.

`MOD()`

Доступно в

DSQL, PSQL

Синтаксис

MOD (a, b)

Table 1. Параметры функции `MOD`
Параметр	Описание
a	Выражение числового типа.
b	Выражение числового типа.

Тип возвращаемого результата:

INTEGER, BIGINT или INT128 в зависимости от типов аргументов.

Функция MOD возвращает остаток от целочисленного деления.

Note	Вещественные числа округляются до выполнения деления.Например, результатом “`mod(7.5, 2.5)`” будет 2 (“`mod(8, 3)`”), а не 0.

`PI()`

Доступно в

DSQL, PSQL

Синтаксис

PI ()

Тип возвращаемого результата:

DOUBLE PRECISION

Функция PI возвращает число π.

`ACOS()`

Доступно в

DSQL, PSQL

Синтаксис

ACOS (number)

Table 1. Параметры функции ACOS
Параметр	Описание
number	Выражение числового типа в диапазоне [-1; 1].

Тип возвращаемого результата:

DOUBLE PRECISION

Функция ACOS возвращает арккосинус (в радианах) аргумента.

В случае если аргумент функции вне границы диапазона [-1, 1], то функция вернёт неопределённое значения NaN.

См. также:

[fblangref-scalarfuncs-cos].

`POWER()`

Доступно в

DSQL, PSQL

Синтаксис

POWER (x, y)

Table 1. Параметры функции `POWER`
Параметр	Описание
x	Выражение числового типа.
y	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция POWER возвращает результат возведения числа x в степень y то есть (x^y).

Note	Если x меньше нуля, возникает ошибка.

`RAND()`

Доступно в

DSQL, PSQL

Синтаксис

RAND ()

Тип возвращаемого результата:

DOUBLE PRECISION

Функция RAND возвращает псевдослучайное число в интервале от 0 до 1.

`ROUND()`

Доступно в

DSQL, PSQL

Синтаксис

ROUND (number [, scale])

Table 1. Параметры функции `ROUND`
Параметр	Описание
number	Выражение числового типа.
scale	Масштаб — целое число, определяющее число десятичных разрядов, к которым должен быть проведено округление, т.е. 2 для округления к самому близкому кратному 0.01 числу 1 для округления к самому близкому кратному 0.1 числу 0 для округления к самому близкому целому числу -1 для округления к самому близкому кратному 10 числу -2 для округления к самому близкому кратному 100 числу По умолчанию 0.

Тип возвращаемого результата

масштабируемое целое (INTEGER, BIGINT или INT128) или DECFLOAT, или DOUBLE PRECISION в зависимости от типа number.

Функция ROUND округляет число до ближайшего целого числа.Если дробная часть равна 0.5, то округление до ближайшего большего целого числа для положительных чисел и до ближайшего меньшего для отрицательных чисел.С дополнительным опциональным параметром scale число может быть округлено до одной из степеней числа 10 (десятки, сотни, десятые части, сотые части и т.д.) вместо просто целого числа.

Note	Если используется параметр scale, то результат имеет такой же масштаб, как и первый параметр number.

Примеры `ROUND`

Example 1. Использование функции ROUND

ROUND(123.654, 1) -- Результат: 123.700 (а не 123.7)
ROUND(8341.7, -3) -- Результат: 8000.0 (а не 8000)
ROUND(45.1212, 0) -- Результат: 45.0000 (а не 45)
ROUND(45.1212)    -- Результат: 45

См. также:

[fblangref-scalarfuncs-trunc].

`SIGN()`

Доступно в

DSQL, PSQL

Синтаксис

SIGN (number)

Table 1. Параметры функции `SIGN`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

SMALLINT

Функция SIGN возвращает знак входного параметра.

-1 — число меньше нуля
0 — число равно нулю
1 — число больше нуля

`SIN()`

Доступно в

DSQL, PSQL

Синтаксис

SIN (angle)

Table 1. Параметры функции `SIN`
Параметр	Описание
angle	Угол, выраженный в радианах.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция SIN возвращает синус угла.Аргумент должен быть задан в радианах.

Любой NOT NULL результат находится в диапазоне [-1, 1].

См. также:

[fblangref-scalarfuncs-asin].

`SINH()`

Доступно в

DSQL, PSQL

Синтаксис

SINH (number)

Table 1. Параметры функции `SINH`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция SINH возвращает гиперболический синус аргумента.

См. также:

[fblangref-scalarfuncs-asinh].

`SQRT()`

Доступно в

DSQL, PSQL

Синтаксис

SQRT (number)

Table 1. Параметры функции `SQRT`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция SQRT возвращает квадратный корень аргумента.

`TAN()`

Доступно в

DSQL, PSQL

Синтаксис

TAN (angle)

Table 1. Параметры функции `TAN`
Параметр	Описание
angle	Угол, выраженный в радианах.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция TAN возвращает тангенс угла.Аргумент должен быть задан в радианах.

См. также:

[fblangref-scalarfuncs-atan], [fblangref-scalarfuncs-atan2].

`TANH()`

Доступно в

DSQL, PSQL

Синтаксис

TANH (number)

Table 1. Параметры функции `TANH`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция TANH возвращает гиперболический тангенс аргумента.

Любой NOT NULL результат находится в диапазоне [-1, 1].

См. также:

[fblangref-scalarfuncs-atanh].

`TRUNC()`

Доступно в

DSQL, PSQL

Синтаксис

TRUNC (number [, scale])

Table 1. Параметры функции `TRUNC`
Параметр	Описание
number	Выражение числового типа.
scale	Масштаб — целое число, определяющее число десятичных разрядов, к которым должен быть проведено усечение, т.е. 2 для усечения к самому близкому кратному 0.01 числу 1 для усечения к самому близкому кратному 0.1 числу 0 для усечения к самому близкому целому числу -1 для усечения к самому близкому кратному 10 числу -2 для усечения к самому близкому кратному 100 числу По умолчанию 0.

Тип возвращаемого результата

масштабируемое целое (INTEGER, BIGINT или INT128) или DECFLOAT, или DOUBLE PRECISION в зависимости от типа number.

Функция TRUNC усекает число до ближайшего целого числа.С дополнительным опциональным параметром scale число может быть усечено до одной из степеней числа 10 (десятки, сотни, десятые части, сотые части и т.д.) вместо просто целого числа.

Note	Если используется параметр scale, то результат имеет такой же масштаб, как и первый параметр number.

Important

Функция всегда увеличивает отрицательные числа, поскольку она обрезает дробную часть.

Example 1. Использование функции TRUNC

TRUNC(789.2225, 2)  -- Результат: 789.2200 (а не 789.22)
TRUNC(345.4, -2) 	-- Результат: 300.0 (а не 300)
TRUNC(-163.41, 0)	-- Результат: -163.00 (а не -163)
TRUNC(-163.41)      -- Результат: -163

См. также:

[fblangref-scalarfuncs-round], [fblangref-scalarfuncs-ceil], [fblangref-scalarfuncs-floor].

`ACOSH()`

Доступно в

DSQL, PSQL

Синтаксис

ACOSH (number)

Table 1. Параметры функции `ACOSH`
Параметр	Описание
number	Выражение числового типа в диапазоне [1; +∞].

Тип возвращаемого результата:

DOUBLE PRECISION

Функция ACOSH возвращает гиперболический арккосинус (в радианах) аргумента.

См. также:

[fblangref-scalarfuncs-cosh].

`ASIN()`

Доступно в

DSQL, PSQL

Синтаксис

ASIN (number)

Table 1. Параметры функции `ASIN`
Параметр	Описание
number	Выражение числового типа в диапазоне [-1; 1].

Тип возвращаемого результата:

DOUBLE PRECISION

Функция ASIN возвращает арксинус (в радианах) аргумента.

В случае если аргумент функции вне границы диапазона [-1, 1], то функция вернёт неопределённое значения NaN.

См. также:

[fblangref-scalarfuncs-sin].

`ASINH()`

Доступно в

DSQL, PSQL

Синтаксис

ASIN (number)

Table 1. Параметры функции `ASINH`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция ASINH возвращает гиперболический арксинус (в радианах) аргумента.

См. также:

[fblangref-scalarfuncs-sinh].

`ATAN()`

Доступно в

DSQL, PSQL

Синтаксис

ATAN (number)

Table 1. Параметры функции `ATAN`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция ATAN возвращает арктангенс аргумента.

Функция возвращает угол в радианах в диапазоне [-π/2; π/2].

См. также:

[fblangref-scalarfuncs-atan2], [fblangref-scalarfuncs-tan].

`ATAN2()`

Доступно в

DSQL, PSQL

Синтаксис

ATAN2 (y, x)

Table 1. Параметры функции ATAN2
Параметр	Описание
y	Выражение числового типа.
x	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция ATAN2 возвращает угол как отношение синуса к косинусу, аргументы, у которых задаются этими двумя параметрами, а знаки синуса и косинуса соответствуют знакам параметров.Это позволяет получать результаты по всей окружности, включая углы -π/2 и π/2.

Особенности использования:

Результат — угол в диапазоне [-π, π] радиан;
Если х отрицательный, то при нулевом значении y результат равен π, а при значении 0 равен -π;
Если и y и x равны 0, то результат бессмыслен.

Note

Полностью эквивалентное описание этой функции следующее: ATAN2 (y, x) является углом между положительной осью X и линией от начала координат до точки (x, y). Это также делает очевидным, что значение ATAN2 (0, 0) не определено;
Если x больше, чем 0, ATAN2 (y, x) совпадает с ATAN (y/x);
Если известны и синус, и косинус угла, то ATAN2 (sin, cos) возвращает угол.

См. также:

[fblangref-scalarfuncs-atan], [fblangref-scalarfuncs-sin], [fblangref-scalarfuncs-cos].

`ATANH()`

Доступно в

DSQL, PSQL

Синтаксис

ATANH (number)

Table 1. Параметры функции `ATANH`
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

DOUBLE PRECISION

Функция ATANH возвращает гиперболический арктангенс (в радианах) аргумента.

См. также:

[fblangref-scalarfuncs-tanh].

`CEIL()`, `CEILING()`

Доступно в

DSQL, PSQL

Синтаксис

CEIL[ING] (number)

Table 1. Параметры функции CEIL[ING]
Параметр	Описание
number	Выражение числового типа.

Тип возвращаемого результата:

BIGINT, INT128, DECFLOAT или DOUBLE PRECISION в зависимости от типа аргумента.

Функция CEIL возвращает наименьшее целое число, большее или равное аргументу.

См. также:

[fblangref-scalarfuncs-floor], [fblangref-scalarfuncs-trunc].

Функции для работы со строками

`ASCII_CHAR()`

Доступно в

DSQL, PSQL

Синтаксис

ASCII_CHAR (code)

Table 1. Параметры функции `ASCII_CHAR`
Параметр	Описание
code	Целое число в диапазоне от 0 до 255.

Тип возвращаемого результата:

CHAR(1) CHARACTER SET NONE.

Функция ASCII_CHAR возвращает ASCII символ соответствующий номеру, переданному в качестве аргумента.

См. также:

[fblangref-scalarfuncs-ascii-val].

`LEFT()`

Доступно в

DSQL, PSQL

Синтаксис

LEFT (string, length)

Table 1. Параметры функции `LEFT`
Параметр	Описание
string	Выражение строкового типа.
length	Целое число.Определяет количество возвращаемых символов.

Тип возвращаемого результата:

VARCHAR или BLOB.

Функция LEFT возвращает левую часть строки, количество возвращаемых символов определяется вторым параметром.

Особенности использования:

Функция поддерживает текстовые блоки любой длины и с любыми наборами символов;
Если строковый аргумент BLOB, результатом будет BLOB, в противном случае результатом будет VARCHAR(N), при этом N – будет равно длине строкового параметра;
Если числовой параметр превысит длину текста, результатом будет исходный текст.

Warning

При использовании BLOB в параметрах функции может потребоваться загрузить объект полностью в память.При больших объёмах BLOB могут наблюдаться потери производительности.

Example 1. Использование функции LEFT

SELECT LEFT('ABC', 2) FROM rdb$database;
-- результат AB

См. также:

[fblangref-scalarfuncs-right], [fblangref-scalarfuncs-substring].

`LOWER()`

Доступно в

DSQL, PSQL, ESQL

Синтаксис

LOWER (string)

Table 1. Параметры функции `LOWER`
Параметр	Описание
string	Выражение строкового типа.

Тип возвращаемого результата:

VAR[CHAR] или BLOB

Функция LOWER возвращает входную строку в нижнем регистре.Точный результат зависит от набора символов входной строки.Например, для наборов символов NONE и ASCII только ASCII символы переводятся в нижний регистр; для OCTETS — вся входная строка возвращается без изменений.

Примеры `LOWER`

Example 1. Использование функции LOWER

select Sherifffrom Townswhere lower(Name) = 'cooper''s valley'

См. также:

[fblangref-scalarfuncs-upper].

`LPAD()`

Доступно в

DSQL, PSQL

Синтаксис

LPAD (str, endlen [, padstr])

Table 1. Параметры функции LPAD
Параметр	Описание
str	Выражение строкового типа.
endlen	Длина выходной строки.
padstr	Строка, которой дополняется исходная строка до указанной длины.По умолчанию является пробелом (“`' '`”).

Тип возвращаемого результата:

VARCHAR или BLOB.

Функция LPAD дополняет слева входную строку пробелами или определённой пользователем строкой до заданной длины.

Особенности использования:

Функция поддерживает текстовые блоки любой длины и с любыми наборами символов;
Если входная строка имеет тип BLOB, то результат также будет BLOB, в противном случае результат будет VARCHAR(endlen).
Если аргумент padstr задан, но равен '' (пустой строке), то дополнения строки не происходит! В случае если endlen меньше длины входной строки, то в результате происходит её усечение до длины endlen, даже если параметр padstr равен пустой строке.

Warning

Примеры `LPAD`

Example 1. Использование функции LPAD

LPAD ('Hello', 12)                -- возвращает '       Hello'
LPAD ('Hello', 12, '-')           -- возвращает '-------Hello'
LPAD ('Hello', 12, '')            -- возвращает 'Hello'
LPAD ('Hello', 12, 'abc')         -- возвращает 'abcabcaHello'
LPAD ('Hello', 12, 'abcdefghij')  -- возвращает 'abcdefgHello'
LPAD ('Hello', 2)                 -- возвращает 'He'
LPAD ('Hello', 2, '-')            -- возвращает 'He'
LPAD ('Hello', 2, '')             -- возвращает 'He'

См. также:

[fblangref-scalarfuncs-rpad].

`OCTET_LENGTH()`

Доступно в

DSQL, PSQL

Синтаксис

OCTET_LENGTH (string)

Table 1. Параметры функции `OCTET_LENGTH`
Параметр	Описание
string	Выражение строкового типа.

Тип возвращаемого результата:

BIGINT

Функция OCTET_LENGTH возвращает количество байт занимаемое строкой.

При работе с параметрами типа CHAR функция возвращает значение всей формальной строковой длины.Для того чтобы узнать “логическую” длину строки в байтах, то перед передачей аргумента функции следует применить RIGHT TRIM.

Note	Следует помнить, что не во всех наборах символов количество байт занимаемых строкой равно количеству символов.

Примеры `OCTET_LENGTH`

Example 1. Использование функции OCTET_LENGTH

SELECT OCTET_LENGTH('Hello!')
FROM rdb$database
-- возвратит 6

SELECT OCTET_LENGTH(_iso8859_1 'Grüß di!')
FROM rdb$database
-- возвратит 8: ü и ß занимают не более 1 байта в ISO8859_1

SELECT
  OCTET_LENGTH(CAST(_iso8859_1 'Grüß di!' AS VARCHAR(24) CHARACTER SET utf8))
FROM rdb$database
-- возвратит 10: ü и ß занимают 2 байта в UTF8

SELECT
  OCTET_LENGTH(CAST(_iso8859_1 'Grüß di!' AS CHAR(24) CHARACTER SET utf8))
FROM rdb$database
-- возвратит 26: всего 24 CHAR позиции, и две из них занимают 2 байта

См. также:

[fblangref-scalarfuncs-bit-length], [fblangref-scalarfuncs-char-length].

`OVERLAY()`

Доступно в

DSQL, PSQL

Синтаксис

OVERLAY (string PLACING replacement FROM pos [FOR length])

Table 1. Параметры функции OVERLAY
Параметр	Описание
string	Строка, в которой происходит замена.
replacement	Строка, которой заменяется.
pos	Позиция, с которой происходит замена.
length	Количество символов, которые будут удалены из исходной строки.

Тип возвращаемого результата:

VARCHAR или BLOB

Функция OVERLAY предназначена для замены части строки другой строкой.

По умолчанию число удаляемых из строки символов равняется длине заменяемой строки.Дополнительный четвёртый параметр позволяет пользователю задать своё число символов, которые будут удалены.

Особенности использования:

Функция полностью поддерживает тестовые BLOB с любым набором символов и любой длины;
Если входная строка имеет тип BLOB, то и результат будет иметь тип BLOB. В противном случае тип результата будет VARCHAR(n), где n является суммой длин параметров string и replacement;
Как и во всех строковых функциях SQL параметр pos является определяющим;
Если pos больше длины строки, то replacement помещается сразу после окончания строки;
Если число символов от pos до конца строки меньше, чем длина replacement (или, чем параметр length, если он задан), то строка усекается до значения pos и replacement помещается после него;
При нулевом параметре length (FOR 0) replacement просто вставляется в строку, начиная с позиции pos;
Если любой из параметров имеет значение NULL, то и результат будет NULL;
Если параметры pos и length не являются целым числом, то используется банковское округление (до чётного): 0.5 становится 0, 1.5 становится 2, 2.5 становится 2, 3.5 становится 4 и т.д.

Warning

При использовании BLOB функции может потребоваться загрузить весь объект в память.При больших размерах BLOB это может повлиять на производительность.

Примеры `OVERLAY`

Example 1. Использование функции OVERLAY

OVERLAY ('Goodbye' PLACING 'Hello' FROM 2) -- Результат: 'Ghelloe'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 5) -- Результат: 'GoodHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 8) -- Результат: 'GoodbyeHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 20) -- Результат: 'GoodbyeHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 0) -– Результат: 'GHellooodbye'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 3) -- Результат: 'GHellobye'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 6) -- Результат: 'GHello'
OVERLAY ('Goodbye' PLACING 'Hello' FROM 2 FOR 9) -- Результат: 'Ghello'
OVERLAY ('Goodbye' PLACING '' FROM 4) -- Результат: 'Goodbye'
OVERLAY ('Goodbye' PLACING '' FROM 4 FOR 3) -- Результат: 'Gooe'
OVERLAY ('Goodbye' PLACING '' FROM 4 FOR 20) -- Результат: 'Goo'
OVERLAY ('' PLACING 'Hello' FROM 4) -- Результат: 'Hello'
OVERLAY ('' PLACING 'Hello' FROM 4 FOR 0) -- Результат: 'Hello'
OVERLAY ('' PLACING 'Hello' FROM 4 FOR 20) -- Результат: 'Hello'

См. также:

[fblangref-scalarfuncs-substring], [fblangref-scalarfuncs-replace].

`POSITION()`

Доступно в

DSQL, PSQL

Синтаксис

  POSITION (substr IN string)
| POSITION (substr, string [, startpos])

Table 1. Параметры функции `POSITION`
Параметр	Описание
substr	Подстрока, позиция которой ищется.
string	Строка, в которой ищется позиция.
startpos	Позиция, с которой начинается поиск подстроки.

Тип возвращаемого результата:

INTEGER

Функция POSITION возвращает позицию первого вхождения подстроки в строку.Отсчёт начинается с 1.Третий аргумент (опциональный) задаёт позицию в строке, с которой начинается поиск подстроки, тем самым игнорирую любые вхождения подстроки в строку до этой позиции.Если совпадение не найдено, функция возвращает 0.

Особенности использования:

Опциональный третий параметр поддерживается только вторым вариантом синтаксиса (синтаксис с запятой);
Пустую строку, функция считает подстрокой любой строки. Поэтому при входном параметре substr, равном '' (пустая строка), и при параметре string, отличном от NULL, результатом будет:
- 1, если параметр startpos не задан;
- startpos, если startpos не превышает длину параметра string;
- 0, если startpos больше длины параметра string.

Примеры `POSITION`

Example 1. Использование функции POSITION

POSITION ('be' IN 'To be or not to be')   -- Результат: 4
POSITION ('be', 'To be or not to be')     -- Результат: 4
POSITION ('be', 'To be or not to be', 4)  -- Результат: 4
POSITION ('be', 'To be or not to be', 8)  -- Результат: 17
POSITION ('be', 'To be or not to be', 18) -- Результат: 0
POSITION ('be' in 'Alas, poor Yorick!') -- Результат: 0

См. также:

[fblangref-scalarfuncs-substring].

`REPLACE()`

Доступно в

DSQL, PSQL

Синтаксис

REPLACE (str, find, repl)

Table 1. Параметры функции `REPLACE`
Параметр	Описание
str	Строка, в которой делается замена.
find	Строка, которая ищется.
repl	Строка, на которую происходит замена.

Тип возвращаемого результата:

VARCHAR или BLOB

Функция REPLACE заменяет в строке все вхождения одной строки на другую строку.

Особенности использования:

Функция поддерживает текстовые блоки любой длины и с любыми наборами символов;
Если один из аргументов имеет тип BLOB, то результат будет иметь тип BLOB. В противном случае результат будет иметь тип VARCHAR(N), где N рассчитывается из длин str, find и repl таким образом, что даже максимальное количество замен не будет вызывать переполнения поля.
Если параметр find является пустой строкой, то возвращается str без изменений;
Если параметр repl является пустой строкой, то все вхождения find удаляются из строки str;
Если любой из аргументов равен NULL, то результатом всегда будет NULL, даже если не было произведено ни одной замены.

Warning

Примеры `REPLACE`

Example 1. Использование функции REPLACE

REPLACE ('Billy Wilder', 'il', 'oog')  -- возвращает 'Boogly Woogder'
REPLACE ('Billy Wilder', 'il', '')     -- возвращает 'Bly Wder'
REPLACE ('Billy Wilder', null, 'oog')  -- возвращает NULL
REPLACE ('Billy Wilder', 'il', null)   -- возвращает NULL
REPLACE ('Billy Wilder', 'xyz', null)  -- возвращает NULL (!)
REPLACE ('Billy Wilder', 'xyz', 'abc') -- возвращает 'Billy Wilder'
REPLACE ('Billy Wilder', '', 'abc')    -- возвращает 'Billy Wilder'

См. также:

[fblangref-scalarfuncs-overlay].

`REVERSE()`

Доступно в

DSQL, PSQL

Синтаксис

REVERSE (string)

Table 1. Параметры функции REVERSE
Параметр	Описание
string	Выражение строкового типа.

Тип возвращаемого результата:

VARCHAR

Функция REVERSE возвратит строку перевёрнутую "задом наперёд".

Примеры `REVERSE`

Example 1. Использование функции REVERSE

REVERSE ('spoonful')             -- возвращает 'lufnoops'
REVERSE ('Was it a cat I saw?')  -- возвращает '?was I tac a ti saW'

Tip

Данная функция очень удобна, если вам предстоит обработать (сортировать или группировать) информацию, которая находится в конце строки.Пример такой информации – доменные имена или имена адресов электронной почты.

CREATE INDEX ix_people_email ON people
COMPUTED BY (reverse(email));

SELECT * FROM people
WHERE REVERSE(email) STARTING WITH reverse('.br');

`RIGHT()`

Доступно в

DSQL, PSQL

Синтаксис

RIGHT (string, length)

Table 1. Параметры функции `RIGHT`
Параметр	Описание
string	Выражение строкового типа.
length	Целое число.Определяет количество возвращаемых символов.

Тип возвращаемого результата:

VARCHAR или BLOB

Функция RIGHT возвращает конечную (правую) часть входной строки.Длина возвращаемой подстроки определяется вторым параметром.

Особенности использования:

Функция поддерживает текстовые блоки любой длины и с любыми наборами символов;
Если строковый аргумент BLOB, результатом будет BLOB, в противном случае результатом будет VARCHAR(N), при этом N — будет равно длине строкового параметра;
Если числовой параметр превысит длину текста, результатом будет исходный текст.

Warning

Example 1. Использование функции RIGHT

SELECT RIGHT('ABC', 1) FROM rdb$database;
-- результат C

См. также:

[fblangref-scalarfuncs-left], [fblangref-scalarfuncs-substring].

`RPAD()`

Доступно в

DSQL, PSQL

Синтаксис

RPAD (str, endlen [, padstr])

Table 1. Параметры функции `RPAD`
Параметр	Описание
str	Выражение строкового типа.
endlen	Длина выходной строки.
padstr	Строка, которой дополняется исходная строка до указанной длины.По умолчанию является пробелом (`' '`).

Тип возвращаемого результата:

VARCHAR или BLOB

Функция RPAD дополняет справа входную строку пробелами или определённой пользователем строкой до заданной длины.

Особенности использования:

Функция поддерживает текстовые блоки любой длины и с любыми наборами символов;
Если входная строка имеет тип BLOB, то результат также будет BLOB, в противном случае результат будет VARCHAR(endlen).
Если аргумент padstr задан, но равен '' (пустой строке), то дополнения строки не происходит! В случае если endlen меньше длины входной строки, то в результате происходит её усечение до длины endlen, даже если параметр padstr равен пустой строке.

Warning

Примеры `RPAD`

Example 1. Использование функции RPAD

RPAD ('Hello', 12)                -- возвращает 'Hello       '
RPAD ('Hello', 12, '-')           -- возвращает 'Hello-------'
RPAD ('Hello', 12, '')            -- возвращает 'Hello'
RPAD ('Hello', 12, 'abc')         -- возвращает 'Helloabcabca'
RPAD ('Hello', 12, 'abcdefghij')  -- возвращает 'Helloabcdefg'
RPAD ('Hello', 2)                 -- возвращает 'He'
RPAD ('Hello', 2, '-')            -- возвращает 'He'
RPAD ('Hello', 2, '')             -- возвращает 'He'

См. также:

[fblangref-scalarfuncs-lpad].

`ASCII_VAL()`

Доступно в

DSQL, PSQL

Синтаксис

ASCII_VAL (ch)

Table 1. Параметры функции `ASCII_VAL`
Параметр	Описание
ch	Строка типа данных [VAR]CHAR или текстовый BLOB максимального размера 32767 байт.

Тип возвращаемого результата:

SMALLINT

Функция ASCII_VAL возвращает ASCII код символа, переданного в качестве аргумента.

Особенности использования:

Если строка содержит более одного символа, то возвращается код первого символа строки;
Если строка пустая, возвращается ноль;
Если аргумент NULL, то возвращаемое значение также NULL.

См. также:

[fblangref-scalarfuncs-ascii-char].

`SUBSTRING()`

Доступно в

DSQL, PSQL

Синтаксис

SUBSTRING (<substring-args>)

<substring-args> ::=
    str FROM startpos [FOR length]
  | str SIMILAR <similar_pattern> ESCAPE <escape>

<similar-pattern> ::=
  <similar-pattern-R1>
  <escape>"<similar pattern_R2><escape>"
  <similar pattern-R3>

Table 1. Параметры функции `SUBSTRING`
Параметр	Описание
str	Выражение строкового типа.
startpos	Позиция, с которой начинается извлечение подстроки.Целочисленное выражение.
length	Длина возвращаемой подстроки.Целочисленное выражение.
similar-pattern	Шаблон регулярного выражения SQL, по которому ищется подстрока.
escape	Символ экранирования.

Тип возвращаемого результата:

VARCHAR или BLOB

Функция SUBSTRING возвращает подстроку из строки, начиная с заданной позиции до конца строки или до указанной длины, либо извлекает подстроку с использованием шаблона регулярного выражения SQL.

Если любой из входных параметров имеет значение NULL, то и результат тоже будет иметь значение NULL.

Warning

При использовании BLOB в параметрах функции может потребоваться загрузить объект в память полностью.При больших объёмах BLOB могут наблюдаться потери производительности.

Позиционный `SUBSTRING`

В простой позиционной форме (с FROM) эта функция возвращает подстроку, начинающуюся с позиции символа startpos (позиция первого сивола равна 1). Без аргумента FOR он возвращает все оставшиеся символы в строке.С использованием FOR возвращается length символов или остаток строки, в зависимости от того что короче.

Начиная с Firebird 4.0, startpos может быть меньше 1.Когда startpos меньше 1, подстрока ведет себя так, как если бы строка имела дополнительные позиции 1 - startpos передфактическим первым символом в позиции 1.Значение length считается от этого воображаемого начала строки, поэтому результирующая строка может быть короче указанной length или даже пустой.

Функция полностью поддерживает двоичные и текстовые BLOB любой длины и с любым набором символов.Если параметр str имеет тип BLOB, то и результат будет иметь тип BLOB.Для любых других типов результатом будет тип VARCHAR.

Для входного параметра str, не являющегося BLOB, длина результата функции всегда будет равна длине строки str, независимо от значений параметров startpos и length.

Example 1. Использование функции SUBSTRING

select substring('abcdef' from 1 for 2) from rdb$database;
-- результат: 'ab'

select substring('abcdef' from 2) from rdb$database;
-- результат: 'bcdef'

select substring('abcdef' from 0 for 2) from rdb$database;
-- результат: 'a'
-- не 'ab', потому что в позиции 0 нет "ничего"

select substring('abcdef' from -5 for 2) from rdb$database;
-- результат: ''
-- длина заканчивается до фактического начала строки

`SUBSTRING` по регулярному выражению

Функция SUBSTRING с регулярным выражением (с SIMILAR) возвращает часть строки соответствующей шаблону регулярного выражения SQL.Если соответствия не найдено, то возвращается NULL.

Шаблон SIMILAR формируется из трех шаблонов регулярных выражений SQL: R1, R2 и R3.Полностью шаблон имеет форму R1 || '<escape>"' || R2 || '<escape>"' || R3, где <escape> — это escape-символ, определенный в предложении ESCAPE.R2 — это шаблон, который соответствует подстроке для извлечения и заключен в экранированные двойные кавычки (<escape>", например, “#"” с escape-символом ‘#’). R1 соответствует префиксу строки, а R3 — суффиксу строки.И R1, и R3 необязательны (они могут быть пустыми), но шаблон должен соответствовать всей строке.Другими словами, недостаточно указать шаблон, который находит только подстроку для извлечения.

Tip

Экранированные двойные кавычки вокруг R2 можно сравнить с определением одной группы захвата в более распространенном синтаксисе регулярных выражений, таком как PCRE.То есть полный шаблон эквивалентен R1(R2)R3, который должен соответствовать всей входной строке, а группа захвата — это возвращаемая подстрока.

Возвращаемое значение соответствует части R2 регулярного выражения.Для этого значения истинно выражение

str SIMILAR TO R1 || R2 || R3 ESCAPE <escape>

Note	Если любая часть шаблона из R1, R2 или R3 не является пустой строкой и не имеет формата регулярного выражения SQL, возникает исключение.

Полный формат регулярных выражений SQL описан в Синтаксис регулярных выражений SQL.

Example 2. Использование функции SUBSTRING с регулярными выражениями

SUBSTRING('abcabc' SIMILAR 'a#"bcab#"c' ESCAPE '#')  -- bcab
SUBSTRING('abcabc' SIMILAR 'a#"%#"c' ESCAPE '#')     -- bcab
SUBSTRING('abcabc' SIMILAR '_#"%#"_' ESCAPE '#')     -- bcab
SUBSTRING('abcabc' SIMILAR '#"(abc)*#"' ESCAPE '#')  -- abcabc
SUBSTRING('abcabc' SIMILAR '#"abc#"' ESCAPE '#')     -- <null>

См. также:

[fblangref-scalarfuncs-position], [fblangref-scalarfuncs-left], [fblangref-scalarfuncs-right],[fblangref-scalarfuncs-char-length], [fblangref-commons-predsimilarto].

`TRIM()`

Доступно в

DSQL, PSQL

Синтаксис

TRIM ([<adjust>] str)

<adjust> ::=  {[<where>] [what]} FROM

<where> ::=  BOTH | LEADING | TRAILING

Table 1. Параметры функции `TRIM`
Параметр	Описание
str	Выражение строкового типа.
where	Из какого места необходимо удалить подстроку — `BOTH` \| `LEADING` \| `TRAILING`.По умолчанию `BOTH`.
what	Подстрока, которую надо удалить (неоднократно, если таких вхождений несколько) из входной строки str в её начале и/или конце.По умолчанию является пробелом (`' '`).

Тип возвращаемого результата:

VARCHAR или BLOB

Функция TRIM удаляет начальные и /или концевые пробелы (или текст согласно настройкам) из входной строки.

Note

Особенности использования

Если входной параметр str имеет тип BLOB, то и результат будет иметь тип BLOB. В противном случае результат будет иметь тип VARCHAR(n), где n является длиной параметра str;
Подстрока для удаления, если она, конечно, задана, не должна иметь длину больше, чем 32767 байта. Однако при повторениях подстроки в начале и/или конце входного параметра str общее число удаляемых байтов может быть гораздо больше.

Warning

Примеры `TRIM`

Example 1. Использование функции TRIM

SELECT TRIM (' Waste no space ')
FROM RDB$DATABASE -- Результат: 'Waste no space'

SELECT TRIM (LEADING FROM ' Waste no space ')
FROM RDB$DATABASE -- Результат: 'Waste no space '

SELECT TRIM (LEADING '.' FROM ' Waste no space ')
FROM RDB$DATABASE -- Результат: ' Waste no space '

SELECT TRIM (TRAILING '!' FROM 'Help!!!!')
FROM RDB$DATABASE -- Результат: 'Help'

SELECT TRIM ('la' FROM 'lalala I love you Ella')
FROM RDB$DATABASE -- Результат: ' I love you El'

См. также:

[fblangref-scalarfuncs-overlay], [fblangref-scalarfuncs-replace].

`UNICODE_CHAR()`

Доступно в

DSQL, PSQL

Синтаксис

UNICODE_CHAR (number)

Table 1. Параметры функции `UNICODE_CHAR`
Параметр	Описание
number	Допустимая кодовая точка UTF-32 вне диапазона суррогатов верхней/нижней границы (от 0xD800 до 0xDFFF). В противном случае будет выдана ошибка.

Тип возвращаемого результата:

CHAR CHARACTER SET UTF8

Функция UNICODE_CHAR возвращает UNICODE символ для заданной кодовой точки.

Примеры `UNICODE_CHAR`

Example 1. Использование функции UNICODE_CHAR

select unicode_char(x) from y;

См. также:

[fblangref-scalarfuncs-unicodeval].

`UNICODE_VAL()`

Доступно в

DSQL, PSQL

Синтаксис

UNICODE_VAL (string)

Table 1. Параметры функции `UNICODE_VAL`
Параметр	Описание
string	Строка.

Тип возвращаемого результата:

INTEGER

Функция UNICODE_VAL возвращает UTF-32 кодовую точку для первого символа в строке. Возвращает 0 для пустой строки.

Примеры `UNICODE_VAL`

Example 1. Использование функции UNICODE_VAL

select unicode_val(x) from y;

См. также:

[fblangref-scalarfuncs-unicodechar].

`UPPER()`

Доступно в

DSQL, PSQL

Синтаксис

UPPER (str)

Table 1. Параметры функции `UPPER`
Параметр	Описание
str	Выражение строкового типа.

Тип возвращаемого результата:

[VAR]CHAR или BLOB

Функция UPPER возвращает входную строку в верхнем регистре.Точный результат зависит от набора символов входной строки.Например, для наборов символов NONE и ASCII только ASCII символы переводятся в верхний регистр; для OCTETS — вся входная строка возвращается без изменений.

Примеры `UPPER`

Example 1. Использование функции UPPER

select upper(_iso8859_1 'Débâcle')
from rdb$database
-- returns 'DÉBÂCLE'

select upper(_iso8859_1 'Débâcle' collate fr_fr)
from rdb$database
-- returns 'DEBACLE', following French uppercasing rules

См. также:

[fblangref-scalarfuncs-lower].

`BASE64_DECODE()`

Доступно в

DSQL, PSQL

Синтаксис

BASE64_DECODE (base64_data)

Table 1. Параметры функции `BASE64_DECODE`
Параметр	Описание
base64_data	Данные в кодировке Base64, дополненные знаком `=` до длины кратной 4

Тип возвращаемого результата

BLOB или VARBINARY

BASE64_DECODE декодирует строку с данными закодированными алгоритмом base64и возвращает декодированное значение как VARBINARY или BLOB в зависимости от входного аргумента.

Если длина типа base64_data не кратна 4, то во время подготовки возникает ошибка.Если длина значения base64_data не кратна 4, то во время выполнения возникает ошибка.

Когда входной аргумент не является BLOB, то длина результирующего типа вычисляется какtype_length * 3/4, где type_length — максимальная длина в байтах типа входного аргумента.

Примеры `BASE64_DECODE`

Example 1. Использование BASE64_DECODE

select cast(base64_decode('VGVzdCBiYXNlNjQ=') as varchar(12))
from rdb$database;

CAST

============
Test base64

См. также:

[fblangref-scalarfuncs-base64encode].

`BASE64_ENCODE()`

Доступно в

DSQL, PSQL

Синтаксис

BASE64_ENCODE (binary_data)

Table 1. Параметры функции `BASE64_ENCODE`
Параметр	Описание
binary_data	Двоичные данные для кодирования

Тип возвращаемого результата

VARCHAR CHARACTER SET ASCII или BLOB SUB_TYPE TEXT CHARACTER SET ASCII

Функция BASE64_ENCODE кодирует binary_data с помощью алгоритма base64 ивозвращает закодированное значение как VARCHAR CHARACTER SET ASCII или BLOB SUB_TYPE TEXT CHARACTER SET ASCIIв зависимости от типа входного аргумента.Возвращаемое значение дополняется знаком ‘=’, чтобы его длина была кратна 4.

Когда входной аргумент не является BLOB, длина результирующего типа вычисляется как type_length * 4 / 3 с округлением в большую сторону до числа, кратного четырем, где type_length — максимальная длина входного типа в байтах.

Примеры `BASE64_ENCODE`

Example 1. Использование функции BASE64_ENCODE

select base64_encode('Test base64')
from rdb$database;

BASE64_ENCODE
================
VGVzdCBiYXNlNjQ=

См. также:

[fblangref-scalarfuncs-base64decode], [fblangref-scalarfuncs-hexencode].

`BIT_LENGTH()`

Доступно в

DSQL, PSQL

Синтаксис

BIT_LENGTH (string)

Table 1. Параметры функции `BIT_LENGTH`
Параметр	Описание
string	Выражение строкового типа.

Тип возвращаемого результата:

BIGINT

Функция BIT_LENGTH возвращает длину входной строки в битах.Для многобайтных наборов символов результат может быть в 8 раз больше, чем количество символов в “формальном” числе байт на символ, записанном в RDB$CHARACTER_SETS.

С параметрами типа CHAR эта функция берет во внимание всю формальную строковую длину (например, объявленная длина поля или переменной). Если вы хотите получить “логическую” длину в битах, не считая пробелов, то перед передачей аргумента в BIT_LENGTH надо выполнить над ним операцию RIGHT TRIM.

Примеры `BIT_LENGTH`

Example 1. Использование функции BIT_LENGTH

SELECT BIT_LENGTH ('Hello!') FROM RDB$DATABASE
-- возвращает 48

SELECT BIT_LENGTH (_ISO8859_1 'Grüß Di!')
FROM RDB$DATABASE
-- возвращает 64: каждый, и ü, и ß занимают один байт в ISO8859_1

SELECT BIT_LENGTH (
CAST (_ISO8859_1 'Grüß di!' AS VARCHAR (24)
CHARACTER SET UTF8))
FROM RDB$DATABASE
-- возвращает 80: каждый, и ü, и ß занимают по два байта в UTF8

SELECT BIT_LENGTH (
CAST (_ISO8859_1 'Grüß di!' AS CHAR (24)
CHARACTER SET UTF8))
FROM RDB$DATABASE
-- возвращает 208: размер всех 24 позиций CHAR и два из них 16-битные

См. также:

[fblangref-scalarfuncs-char-length], [fblangref-scalarfuncs-octet-length].

`CHAR_LENGTH()`, `CHARACTER_LENGTH()`

Доступно в

DSQL, PSQL

Синтаксис

  CHAR_LENGTH (string)
| CHARACTER_LENGTH (string)

Table 1. Параметры функции `CHAR_LENGTH`
Параметр	Описание
string	Выражение строкового типа.

Тип возвращаемого результата:

BIGINT

Функция CHAR_LENGTH возвращает длину (в символах) строки, переданной в качестве аргумента.

Note	С параметрами типа `CHAR` эта функция берет во внимание всю формальную строковую длину (например, объявленная длина поля или переменной). Если вы хотите получить “логическую” длину без учёта пробелов, то перед передачей аргумента в `CHAR[ACTER]_LENGTH` надо выполнить над ним операцию RIGHT TRIM.

См. также:

[fblangref-scalarfuncs-bit-length], [fblangref-scalarfuncs-octet-length].

`HASH()`

Доступно в

DSQL, PSQL

Синтаксис

HASH (str [USING <algorithm>])

<algorithm> ::= { CRC32 }

Table 1. Параметры функции `HASH`
Параметр	Описание
str	Выражение строкового типа.

Тип возвращаемого результата:

BIGINT

Функция HASH возвращает некриптографический хэш входной строки.Эта функция полностью поддерживает текстовые BLOB любой длины и с любым набором символов.

Необязательное предложение USING определяет применяемый некриптографический алгоритм хеширования.Когда предложение USING отсутствует, применяется устаревший алгоритм PJW; это идентично его поведению в предыдущихверсиях Firebird.

Поддерживаемые алгоритмы:

не указан: Если алгоритм не указан, то используется 64-битный вариант некриптографическойхэш-функции PJW (также известной как ELF64).Эта функция очень быстра и может использоваться для общих целей (хеш-таблицы и т.д.), но имеет большое количество коллизий.Для более надежного хеширования следует использовать другие хеш-функции, явно указанные в предложении USING, или криптографические хеши с помощью [fblangref-scalarfuncs-crypthash].

Для этого алгоритма хеширования функция возвращает тип BIGINT.
CRC32: Если в предложении USING указан алгоритм CRC32, то Firebird применяет алгоритм CRC32, используя полином 0x04C11DB7.

Для этого алгоритма функция HASH возвращает результат с типом INTEGER.

Примеры `HASH`

Example 1. Вычисление хеша с алгоритмом PJW

SELECT HASH(x) FROM MyTable;
-- результат типа BIGINT

Example 2. Вычисление хеша с алгоритмом CRC32

SELECT HASH(x USING CRC32) FROM MyTable;
-- результат типа INTEGER

См. также:[fblangref-scalarfuncs-crypthash]

`HEX_DECODE()`

Доступно в

DSQL, PSQL

Синтаксис

HEX_DECODE (hex_data)

Table 1. Параметры функции `HEX_DECODE`
Параметр	Описание
hex_data	Данные в шестнадцатеричном представлении.

Тип возвращаемого результата

VARBINARY или BLOB

Функция HEX_DECODE декодирует строку с шестнадцатеричными данными и возвращает декодированное значениекак VARBINARY или BLOB в зависимости от типа входного и размера аргумента.Если длина типа hex_data не кратна 2, во время подготовки возникает ошибка.Если длина значения hex_data не кратна 2, во время выполнения возникает ошибка.

Когда входной аргумент не является BLOB, то длина результирующего типа вычисляется как type_length / 2,где type_length — максимальная длина в байтах типа входного аргумента.

Примеры `HEX_DECODE`

Example 1. Использование функции HEX_DECODE

select cast(hex_decode('48657861646563696D616C') as varchar(12))
from rdb$database;

CAST
============
Hexadecimal

См. также:

[fblangref-scalarfuncs-hexencode], [fblangref-scalarfuncs-base64decode].

`HEX_ENCODE()`

Доступно в

DSQL, PSQL

Синтаксис

HEX_ENCODE (binary_data)

Table 1. Параметры функции `HEX_ENCODE`
Параметр	Описание
binary_data	Двоичные данные для кодирования

Тип возвращаемого результата:

VARCHAR CHARACTER SET ASCII или BLOB SUB_TYPE TEXT CHARACTER SET ASCII

Функция HEX_ENCODE кодирует binary_data шестнадцатеричным числом и возвращает закодированное значениекак VARCHAR CHARACTER SET ASCII или BLOB SUB_TYPE TEXT CHARACTER SET ASCII в зависимости от входного аргумента.

Когда входной аргумент не является BLOB, то длина результирующего типа вычисляется как type_length * 2,где type_length — максимальная длина в байтах типа входного аргумента.

Примеры `HEX_ENCODE`

Example 1. Использование функции HEX_ENCODE

select hex_encode('Hexadecimal')
from rdb$database;

HEX_ENCODE
======================
48657861646563696D616C

См. также:

[fblangref-scalarfuncs-hexdecode], [fblangref-scalarfuncs-base64encode]

Функции для работы с датой и временем

`DATEADD()`

Доступно в

DSQL, PSQL

Синтаксис

DATEADD (<args>)

<args> ::= <amount> <unit> TO <datetime>
         | <unit>, <amount>, <datetime>

<unit> ::=
    YEAR | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND

Table 1. Параметры функции `DATEADD`
Параметр	Описание
amount	Выражение типа `SMALLINT`, `INTEGER`, `BIGINT` или `NUMERIC` (отрицательное вычитается).
unit	Составляющая даты/времени.
datetime	Выражение типа `DATE`, `TIME` или `TIMESTAMP`.

Тип возвращаемого результата

DATE, TIME или TIMESTAMP.

Функция DATEADD позволяет добавить заданное число лет, месяцев, недель, часов, минут, секунд, миллисекунд к заданному значению даты/времени.

Note	С аргументом типа `TIMESTAMP` и `DATE` можно использовать любую составляющую даты/времени <unit>; Для типа данных `TIME` разрешается использовать только `HOUR`, `MINUTE`, `SECOND` и `MILLISECOND`.

Примеры `DATEADD`

Example 1. Использование функции DATEADD

DATEADD (28 DAY TO CURRENT_DATE)
DATEADD (-6 HOUR TO CURRENT_TIME)
DATEADD (MONTH, 9, DATEOFCONCEPTION)
DATEADD (-38 WEEK TO DATEOFBIRTH)
DATEADD (MINUTE, 90, CAST('NOW' AS TIME))
DATEADD (? YEAR TO DATE '11-SEP-1973')

SELECT
  CAST(DATEADD(-1 * EXTRACT(MILLISECOND FROM ts) MILLISECOND TO ts) AS VARCHAR(30)) AS t,
  EXTRACT(MILLISECOND FROM ts) AS ms
FROM (
    SELECT TIMESTAMP'2014-06-09 13:50:17.4971' as ts
    FROM RDB$DATABASE
) a

T                             MS
------------------------------------
2014-06-09 13:50:17.0000	497.1

См. также:

[fblangref-scalarfuncs-datediff],[fblangref-datatypes-datetimeops].

`DATEDIFF()`

Доступно в

DSQL, PSQL

Синтаксис

DATEDIFF (<args>)

<args> ::= <unit> FROM <moment_1> TO <moment_2>
         | <unit>, <moment_1>, <moment_2>

<unit> ::=
    YEAR | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND

Table 1. Параметры функции `DATEDIFF`
Параметр	Описание
unit	Составляющая даты/времени.
monent_1	Выражение типа `DATE`, `TIME` или `TIMESTAMP`.
monent_2	Выражение типа `DATE`, `TIME` или `TIMESTAMP`.

Тип возвращаемого результата:

BIGINT

Функция DATEDIFF возвращает количество лет, месяцев, недель, дней, часов, минут, секунд или миллисекунд между двумя значениями даты/времени.

Особенности использования:

Параметры DATE и TIMESTAMP могут использоваться совместно. Совместное использование типа TIME с типами DATE и TIMESTAMP не разрешается;
С аргументом типа TIMESTAMP и DATE можно использовать любую составляющую даты/времени <unit>;
Для типа данных TIME разрешается использовать только HOUR, MINUTE, SECOND и MILLISECOND.

Note

Функция DATEDIFF не проверяет разницу в более мелких составляющих даты/времени, чем задана в первом аргументе <unit>. В результате получаем:
- DATEDIFF (YEAR, DATE '1-JAN-2009', DATE '31-DEC-2009') вернёт 0, но
- DATEDIFF (YEAR, DATE '31-DEC-2009', DATE '1-JAN-2010') вернёт 1
Однако для более мелких составляющих даты/времени имеем:
- DATEDIFF (DAY, DATE '26-JUN-1908', DATE '11-SEP-1973') вернёт 23818
- DATEDIFF (DAY, DATE '30-NOV-1971', DATE '8-JAN-1972') вернёт 39
Отрицательное значение функции говорит о том, что дата/время в moment_2 меньше, чем в moment_1.

Примеры `DATEDIFF`

Example 1. Использование функции DATEDIFF

DATEDIFF (HOUR FROM CURRENT_TIMESTAMP TO TIMESTAMP '12-JUN-2059 06:00')
DATEDIFF (MINUTE FROM TIME '0:00' TO CURRENT_TIME)
DATEDIFF (MONTH, CURRENT_DATE, DATE '1-1-1900')
DATEDIFF (DAY FROM CURRENT_DATE TO CAST (? AS DATE))

См. также:

[fblangref-scalarfuncs-dateadd],[fblangref-datatypes-datetimeops].

`EXTRACT()`

Доступно в

DSQL, PSQL

Синтаксис

EXTRACT (<part> FROM <datetime>)

<part> ::=
    YEAR | QUARTER | MONTH | WEEK | DAY | WEEKDAY | YEARDAY
  | HOUR | MINUTE | SECOND | MILLISECOND
  | TIMEZONE_HOUR | TIMEZONE_MINUTE

Table 1. Параметры функции `EXTRACT`
Параметр	Описание
part	Составляющая даты/времени.
datetime	Выражение типа `DATE`, `TIME` или `TIMESTAMP`.

Тип возвращаемого результата:

SMALLINT или NUNERIC

Функция EXTRACT извлекает составляющие даты и времени из типов данных DATE, TIME и TIMESTAMP.

Table 2. Типы и диапазоны результатов функции `EXTRACT`
Составляющая даты/времени	Тип	Диапазон	Комментарий
`YEAR`	`SMALLINT`	1–9999	Год
`QUARTER`	`SMALLINT`	1-4	Квартал
`MONTH`	`SMALLINT`	1–12	Месяц
`WEEK`	`SMALLINT`	1–53	Номер недели в году
`DAY`	`SMALLINT`	1–31	День
`WEEKDAY`	`SMALLINT`	0–6	День недели. 0 — Воскресенье
`YEARDAY`	`SMALLINT`	0–365	Номер дня в году. 0 = 1 января
`HOUR`	`SMALLINT`	0–23	Часы
`MINUTE`	`SMALLINT`	0–59	Минуты
`SECOND`	`NUMERIC(9,4)`	0.0000–59.9999	Секунды. Включает в себя миллисекунды
`MILLISECOND`	`NUMERIC(9,1)`	0.0–999.9	Миллисекунды
`TIMEZONE_HOUR`	`SMALLINT`	от -14 до +14	Смещение часов часового пояса
`TIMEZONE_MINUTE`	`SMALLINT`	от -59 до +59	Смещение минут часового пояса

Note	Если составляющая даты/времени не присутствует в аргументе дата/время, например SECOND в аргументе с типом DATE или YEAR в TIME, то функция вызовет ошибку.

Из аргумента с типом данных DATE или TIMESTAMP можно извлекать номер недели.В соответствии со стандартом ISO-8601 неделя начинается с понедельника и всегда включает в себя 7 дней.Первой неделей года является первая неделя, у которой в ней больше дней в новом году (по крайней мере, 4): дни 1-3 могут принадлежать предыдущей неделе (52 или 53) прошлого года.По аналогии дни 1-3 текущего года могут принадлежать 1 неделе следующего года.

Example 1. Использование функции EXTRACT

/* получить по дате номер квартала */
SELECT (EXTRACT(MONTH FROM CURRENT_TIMESTAMP)-1)/3+1
FROM RDB$DATABASE

См. также:

Типы данных для работы с датой и временем.

`FIRST_DAY()`

Доступно в

DSQL, PSQL

Синтаксис

FIRST_DAY(OF <period> FROM date_or_timestamp)

<period> ::= YEAR | QUARTER | MONTH | WEEK

Table 1. Параметры функции `FIRST_DAY`
Параметр	Описание
date_or_timestamp	Выражение типа `DATE` или `TIMESTAMP [WITH

Тип возвращаемого результата

DATE или TIMESTAMP [WITH | WITHOUT] TIME ZONE

Возвращает первый день года, месяца или недели для заданной даты.

Note	Первым днём недели считается воскресенье, как это возвращает функция `EXTRACT` с частью `WEEKDAY`. Когда в качестве аргумента функции передаётся выражение типа `TIMESTAMP`, то возвращаемое значение сохраняет временную часть.

Примеры `FIRST_DAY`

Example 1. Использование функции FIRST_DAY

SELECT FIRST_DAY(OF MONTH FROM current_date) FROM rdb$database;
SELECT FIRST_DAY(OF YEAR FROM current_timestamp) FROM rdb$database;
SELECT FIRST_DAY(OF WEEK FROM date '2017-11-01') FROM rdb$database;

См. также:

[fblangref-scalarfuncs-lastday].

`LAST_DAY()`

Доступно в

DSQL, PSQL

Синтаксис

LAST_DAY(OF <period> FROM date_or_timestamp)

<period> ::=  YEAR | QUARTER | MONTH | WEEK

Table 1. Параметры функции `LAST_DAY`
Параметр	Описание
date_or_timestamp	Выражение типа `DATE` или `TIMESTAMP [WITH

Тип возвращаемого результата

DATE или TIMESTAMP [WITH | WITHOUT] TIME ZONE

Возвращает последний день года, месяца или недели для заданной даты.

Note	Последним днём недели считается суббота, как это возвращает функция `EXTRACT` с частью `WEEKDAY`. Когда в качестве аргумента функции передаётся выражение типа `TIMESTAMP`, то возвращаемое значение сохраняет временную часть.

Примеры `LAST_DAY`

Example 1. Использование функции LAST_DAY

SELECT LAST_DAY(OF MONTH FROM current_date) FROM rdb$database;
SELECT LAST_DAY(OF YEAR FROM current_timestamp) FROM rdb$database;
SELECT LAST_DAY(OF WEEK FROM date '2017-11-01') FROM rdb$database;

См. также:

[fblangref-scalarfuncs-firstday].

Функции для работы с типом BLOB

`BLOB_APPEND()`

Доступно в

DSQL, PSQL

Синтаксис

BLOB_APPEND(<blob> [, <value1>, ... <valueN]>

Table 1. Параметры функции `BLOB_APPEND`
Параметр	Описание
blob	BLOB или NULL.
value	Значение любого типа.

Тип возвращаемого результата

временный не закрытый BLOB с флагом BLB_close_on_read.

Функция BLOB_APPEND предназначена для конкатенации BLOB без созданияпромежуточных BLOB. Обычная операция конкатенации с аргументами типа BLOB всегда создаст столько временных BLOB,сколько раз используется.

Входные аргументы:

Для первого аргумента в зависимости от его значения определено следующее поведение функции:
- NULL: будет создан новый пустой не закрытый BLOB
- постоянный BLOB (из таблицы) или временный уже закрытый BLOB:будет создан новый пустой не закрытый BLOB и содержимоепервого BLOB будет в него добавлено
- временный не закрытый BLOB: он будет использован далее
- другие типы данных преобразуются в строку, будет создан временный не закрытый BLOB с содержимым этой строки
остальные аргументы могут быть любого типа. Для них определено следующее поведение:
- NULL игнорируется
- не BLOB преобразуются в строки (по обычным правилам) и добавляются к содержимомурезультата
- BLOB при необходимости транслитерируются к набору символов первого аргумента и ихсодержимое добавляется к результату

В качестве выходного значения функция BLOB_APPEND возвращает временный не закрытый BLOB с флагом BLB_close_on_read.Это или новый BLOB, или тот же, что был в первом аргументе. Таким образом ряд операций видаblob = BLOB_APPEND(blob, …) приведёт к созданию не более одного BLOB (если не пытаться добавить BLOB к самому себе).Этот BLOB будет автоматически закрыт движком при попытке прочитать его клиентом, записать в таблицу или использовать в других выражениях, требующих чтения содержимого.

Note	Проверка BLOB на значение NULL с помощью оператора `IS [NOT] NULL` не читает его, а следовательно временный BLOBне будет закрыт при таких проверках.

execute block
returns (b blob sub_type text)
as
begin
  -- создаст новый временный не закрытый BLOB
  -- и запишет в него строку из 2-ого аргумента
  b = blob_append(null, 'Hello ');
  -- добавляет во временный BLOB две строки не закрывая его
  b = blob_append(b, 'World', '!');
  -- сравнение BLOB со строкой закроет его, ибо для этого надо прочитать BLOB
  if (b = 'Hello World!') then
  begin
  -- ...
  end
  -- создаст временный закрытый BLOB добавив в него строку
  b = b || 'Close';
  suspend;
end

Tip	Используйте функции `LIST` и `BLOB_APPEND` для конкатенации BLOB. Это позволит сэкономить объём потребляемой памяти,дисковый ввод/вывод, а также предотвратит разрастание базы данных из-за создания множества временных BLOB при использовании операторов конкатенации.

Example 1. Использование функции BLOB_APPEND

Предположим вам надо собрать JSON на стороне сервера. У нас есть PSQL пакет JSON_UTILS с набором функций дляпреобразования элементарных типов данных в JSON нотацию. Тогда сборка JSON с использованием функции BLOB_APPEND будет выглядетьследующим образом:

EXECUTE BLOCK
RETURNS (
    JSON_STR BLOB SUB_TYPE TEXT CHARACTER SET UTF8)
AS
  DECLARE JSON_M BLOB SUB_TYPE TEXT CHARACTER SET UTF8;
BEGIN
  FOR
      SELECT
          HORSE.CODE_HORSE,
          HORSE.NAME,
          HORSE.BIRTHDAY
      FROM HORSE
      WHERE HORSE.CODE_DEPARTURE = 15
      FETCH FIRST 1000 ROW ONLY
      AS CURSOR C
  DO
  BEGIN
    SELECT
      LIST(
          '{' ||
          JSON_UTILS.NUMERIC_PAIR('age', MEASURE.AGE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('height', MEASURE.HEIGHT_HORSE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('length', MEASURE.LENGTH_HORSE) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('chestaround', MEASURE.CHESTAROUND) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('wristaround', MEASURE.WRISTAROUND) ||
          ',' ||
          JSON_UTILS.NUMERIC_PAIR('weight', MEASURE.WEIGHT_HORSE) ||
          '}'
      ) AS JSON_M
    FROM MEASURE
    WHERE MEASURE.CODE_HORSE = :C.CODE_HORSE
    INTO JSON_M;

    JSON_STR = BLOB_APPEND(
      JSON_STR,
      IIF(JSON_STR IS NULL, '[', ',' || ascii_char(13)),
      '{',
      JSON_UTILS.INTEGER_PAIR('code_horse', C.CODE_HORSE),
      ',',
      JSON_UTILS.STRING_PAIR('name', C.NAME),
      ',',
      JSON_UTILS.TIMESTAMP_PAIR('birthday', C.BIRTHDAY),
      ',',
      JSON_UTILS.STRING_VALUE('measures') || ':[', JSON_M, ']',
      '}'
    );
  END
  JSON_STR = BLOB_APPEND(JSON_STR, ']');
  SUSPEND;
END

Аналогичный пример с использованием обычного оператора конкатенации ||работает в 18 раз медленнее, и делает в 1000 раз больше операций записи на диск.

Функции для работы с типом DECFLOAT

`COMPARE_DECFLOAT()`

Доступно в

DSQL, PSQL

Синтаксис

COMPARE_DECFLOAT (decfloat1, decfloat2)

Table 1. Параметры функции `COMPARE_DECFLOAT`
Параметр	Описание
decfloat1, decfloat2	Значения или выражения типа `DECFLOAT` или быть совместимыми с типом `DECFLOAT`.

Тип возвращаемого результата

SMALLINT

Функция COMPARE_DECFLOAT сравнивает два значения типа DECFLOAT, которые могут быть одинаковыми, разными или неупорядоченными.Замыкающие нули учитываются при сравнении.

Функция возвращает:

`0`	Значения равны;
`1`	Первое значение меньше чем второе;
`2`	Первое значение больше чем второе;
`3`	Значения не упорядочены (одно или оба `NaN`/`sNaN`).

В отличие от операторов сравнения (‘<’, ‘=’, ‘>’ и др.) сравнение является точным,т.е. COMPARE_DECFLOAT(2.17, 2.170) вернёт 2, а не 0.

См. также:[fblangref-scalarfuncs-totalorder]

`NORMALIZE_DECFLOAT()`

Доступно в

DSQL, PSQL

Синтаксис

NORMALIZE_DECFLOAT (decfloat_value)

Table 1. Параметры функции `NORMALIZE_DECFLOAT`
Параметр	Описание
decfloat_value	Значение или выражение типа `DECFLOAT` или быть совместимым с типом `DECFLOAT`.

Тип возвращаемого результата

DECFLOAT

Функция NORMALIZE_DECFLOAT возвращает число в нормализованном виде.Это обозначает, что для любого ненулевого значения удаляются завершающие нули с соответствующей коррекцией экспоненты.

Примеры `NORMALIZE_DECFLOAT`

Example 1. Нормализация различных значений типа DECFLOAT

NORMALIZE_DECFLOAT(12.00) -- возвращает 12
NORMALIZE_DECFLOAT(120) -- возвращает 1.2E+2

`QUANTIZE()`

Доступно в

DSQL, PSQL

Синтаксис

QUANTIZE (decfloat_value, exp_value)

Table 1. Параметры функции `QUANTIZE`
Параметр	Описание
decfloat_value	Значение или выражение типа `DECFLOAT` или быть совместимым с типом `DECFLOAT`.
exp_value	Значение или выражение для использования в качестве показателя степени;должно иметь тип `DECFLOAT` или быть совместимым с типом `DECFLOAT`.

Тип возвращаемого результата

DECFLOAT

Функция QUANTIZE возвращает значение первого аргумента масштабированным с использованием второго значения в качестве шаблона.Другими словами функция QUANTIZE возвращает значение DECFLOAT, равное по значению (за исключением любого округления) и знаку decfloat_value, а также экспоненте, равной по значению экспоненте exp_value.Функцию QUANTIZE можно использовать для реализации округления с точностью до нужного знака, например, округление до ближайшего цента с использованием установленного режима округления DECFLOAT.

Тип возвращаемого значения — DECFLOAT(16), если оба аргумента — DECFLOAT(16), в противном случае тип результата — DECFLOAT(34).

Note

Целевой показатель — это показатель, используемый в формате хранения Decimal64 или Decimal128 для DECFLOAT из exp_value.Это не обязательно то же самое, что экспонента, отображаемая в таких инструментах, как isql.Например, значение 1.23E+2 - это коэффициент 123 и показатель степени 0,а значение 1.2 - это коэффициент 12 и показатель степени -1.

Если показатель decfloat_value больше, чем показатель exp_value, коэффициент decfloat_value умножается на степень десяти, и его показатель уменьшается, если показатель меньше, то его коэффициент округляется с использованием текущего режима округления decfloat, и его показатель увеличивается.

Когда невозможно достичь целевого показателя экспоненты, поскольку коэффициент превысит целевую точность (16 или 34 десятичных знака), то либо возникает ошибка “Decfloat float invalid operation”, либо возвращается NaN (в зависимости от текущего конфигурация decfloat traps).

Ограничений на exp_value практически нет.Однако почти во всех случаях использования NaN/sNaN/Infinity будет вызывать исключение(если это не разрешено текущей конфигурацией decfloat traps)

Если одно из значений NULL, то результатом функции будет NULL и т.д.

Example 1. Использование функции QUANTIZE

select v, pic, quantize(v, pic) from examples;

V                       PIC                   QUANTIZE
======================= ===================== ==================
                   3.16                 0.001              3.160
                   3.16                 0.01               3.16
                   3.16                 0.1                3.2
                   3.16                 1                  3
                   3.16                 1E+1               0E+1
                   -0.1                 1                 -0
                      0                 1E+5               0E+5
                    316                 0.1              316.0
                    316                 1                316
                    316                 1E+1             3.2E+2
                    316                 1E+2               3E+2

`TOTALORDER()`

Доступно в

DSQL, PSQL

Синтаксис

TOTALORDER (decfloat1, decfloat2)

Table 1. Параметры функции `TOTALORDER`
Параметр	Описание
decfloat1, decfloat2	Значение или выражение типа `DECFLOAT` или быть совместимым с типом `DECFLOAT`.

Тип возвращаемого результата

SMALLINT

Функция TOTALORDER сравнивает два значения типа DECFLOAT, включая специальные значения.Сравнение является точным. Замыкающие нули учитываются при сравнении.

Функция возвращает:

-1 — если первое значение меньше второго;
0 — если значения равны;
1 — если первое значение больше второго.

Сравнений значений DEFLOAT происходит в следующем порядке:

-nan < -snan < -inf < -0.1 < -0.10 < -0 < 0 < 0.10 < 0.1 < inf < snan < nan

См. также:[fblangref-scalarfuncs-comparedecfloat]

Криптографические функции

В Firebird 4.0 поддерживается только подмножество симметричных алгоритмов шифрования (как блочных так и потоковых), так и RSA.

`CRYPT_HASH()`

Доступно в

DSQL, PSQL

Синтаксис

CRYPT_HASH (value USING <algorithm>)

<algorithm> ::= { MD5 | SHA1 | SHA256 | SHA512 | SHA3_224 | SHA3_256 | SHA3_384 | SHA3_512 }

Table 1. Параметры функции `CRYPT_HASH`
Параметр	Описание
value	Выражение любого типа. Не строковые и не бинарные типы приводятся к строке.
algorithm	Алгоритм хеширования.

Тип возвращаемого результата

VARBINARY

Функция CRYPT_HASH возвращает криптографический хэш входной строки, используя указанный алгоритм.Эта функция полностью поддерживает текстовые BLOB любой длины и с любым набором символов.Предложение USING позволяет указать алгоритм по которому вычисляет хэш.

Note	Алгоритмы `MD5` и `SHA1` не рекомендуются для использования из-за известных серьезных проблем, которые предоставляются только для обратной совместимости.

Примеры NULLIF

Примеры NULLIF

Другие функции

docnext count = 100

MAKE_DBKEY()

RDB$ERROR()

RDB$GET_TRANSACTION_CN()

RDB$ROLE_IN_USE()

RDB$SYSTEM_PRIVILEGE()

Математические функции

ABS()

COS()

COSH()

COT()

EXP()

FLOOR()

LN()

LOG()

LOG10()

MOD()

PI()

ACOS()

POWER()

RAND()

ROUND()

Примеры ROUND

SIGN()

SIN()

SINH()

SQRT()

TAN()

TANH()

TRUNC()

ACOSH()

ASIN()

ASINH()

ATAN()

ATAN2()

ATANH()

CEIL(), CEILING()

Функции для работы со строками

ASCII_CHAR()

LEFT()

LOWER()

Примеры LOWER

LPAD()

Примеры LPAD

OCTET_LENGTH()

Примеры OCTET_LENGTH

OVERLAY()

Примеры OVERLAY

POSITION()

Примеры POSITION

REPLACE()

Примеры REPLACE

REVERSE()

Примеры REVERSE

RIGHT()

RPAD()

Примеры RPAD

ASCII_VAL()

SUBSTRING()

Позиционный SUBSTRING

SUBSTRING по регулярному выражению

TRIM()

Примеры TRIM

UNICODE_CHAR()

Примеры UNICODE_CHAR

UNICODE_VAL()

Примеры UNICODE_VAL

UPPER()

Примеры UPPER

BASE64_DECODE()

Примеры BASE64_DECODE

BASE64_ENCODE()

Примеры BASE64_ENCODE

BIT_LENGTH()

Примеры BIT_LENGTH

CHAR_LENGTH(), CHARACTER_LENGTH()

HASH()

Примеры `NULLIF`

`MAKE_DBKEY()`

`RDB$ERROR()`

`RDB$GET_TRANSACTION_CN()`

`RDB$ROLE_IN_USE()`

`RDB$SYSTEM_PRIVILEGE()`

`ABS()`

`COS()`

`COSH()`

`COT()`

`EXP()`

`FLOOR()`

`LN()`

`LOG()`

`LOG10()`

`MOD()`

`PI()`

`ACOS()`

`POWER()`

`RAND()`

`ROUND()`

Примеры `ROUND`

`SIGN()`

`SIN()`

`SINH()`

`SQRT()`

`TAN()`

`TANH()`

`TRUNC()`

`ACOSH()`

`ASIN()`

`ASINH()`

`ATAN()`

`ATAN2()`

`ATANH()`

`CEIL()`, `CEILING()`

`ASCII_CHAR()`

`LEFT()`

`LOWER()`

Примеры `LOWER`

`LPAD()`

Примеры `LPAD`

`OCTET_LENGTH()`

Примеры `OCTET_LENGTH`

`OVERLAY()`

Примеры `OVERLAY`

`POSITION()`

Примеры `POSITION`

`REPLACE()`

Примеры `REPLACE`

`REVERSE()`

Примеры `REVERSE`

`RIGHT()`

`RPAD()`

Примеры `RPAD`

`ASCII_VAL()`

`SUBSTRING()`

Позиционный `SUBSTRING`

`SUBSTRING` по регулярному выражению

`TRIM()`

Примеры `TRIM`

`UNICODE_CHAR()`

Примеры `UNICODE_CHAR`

`UNICODE_VAL()`

Примеры `UNICODE_VAL`

`UPPER()`

Примеры `UPPER`

`BASE64_DECODE()`

Примеры `BASE64_DECODE`

`BASE64_ENCODE()`

Примеры `BASE64_ENCODE`

`BIT_LENGTH()`

Примеры `BIT_LENGTH`

`CHAR_LENGTH()`, `CHARACTER_LENGTH()`

`HASH()`

Примеры `HASH`

`HEX_DECODE()`

Примеры `HEX_DECODE`

`HEX_ENCODE()`

Примеры `HEX_ENCODE`