Firebird 3.0 内置函数（SDF，即服务器定义函数）

以下内置函数（DECODE 除外）仅在不存在同名 UDF 时才会使用。

选择 UDF 还是系统函数是在编译语句时决定的，并且即使语句被存储（触发器 / 存储过程）后也不会改变。

作者：

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

---———

函数：

将 UUID 的 CHAR(32) ASCII 表示形式

（XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX）转换为 CHAR(16) OCTETS

表示形式（针对存储进行了优化）。

格式：

CHAR\_TO\_UUID( <string> )

重要说明（针对大端序服务器）：

已发现在 Firebird 2.5.2 之前，CHAR\_TO\_UUID 和 UUID\_TO\_CHAR 在大端序服务器上

工作不正确。在这些机器上，转换时字节/字符会被交换并出现在错误的位置。

此错误已在 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( <string> )

示例：

select hash(x) from y;

LEFT

函数：

返回出现在字符串开头的指定长度的子字符串。

格式：

LEFT( <string>, <number> )

示例：

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

    from people

    where name like '% FERNANDES';

–

函数：

返回数字的自然对数。

格式：

LN( <number> )

示例：

select ln(x) from y;

LOG

函数：

LOG(x, y) 返回以 x 为底 y 的对数。

格式：

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 中从 start 开始、长度为 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 常量 (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) 将 "searched" 中所有出现的 "find"

替换为 "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
1. select trunc(987.65, 1), trunc(987.65, -1) from rdb$database; – 返回 987.60, 980.00

---———

UUID_TO_CHAR

---———

函数：

将 CHAR(16) OCTETS 类型的 UUID（由 GEN\_UUID 返回）转换为

CHAR(32) ASCII 表示形式（XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX）。

格式：

UUID\_TO\_CHAR( <string> )

重要说明（针对大端序服务器）：

已发现在 Firebird 2.5.2 之前，CHAR\_TO\_UUID 和 UUID\_TO\_CHAR 在大端序服务器上

工作不正确。在这些机器上，转换时字节/字符会被交换并处于错误的位置。

此错误已在 2.5.2 和 3.0 中修复，但这意味着这些函数现在（对于相同的输入参数）

返回的值与之前不同。

示例：

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

另请参阅：GEN_UUID 和 CHAR_TO_UUID