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) 当对日期使用 DATEADD 的 hour、minute、second 和 millisecond 时，添加或

    减去的量至少应达到一天才能产生效果（即向日期添加 23 小时

    不会使其递增）。

示例：

select dateadd(-1 day to current\_date) as yesterday

    from rdb$database;

---—–

DATEDIFF

---—–

功能：

返回一个精确数值，表示从第一个日期/时间/时间戳值到

第二个值之间的时间量。

格式：

DATEDIFF( <timestamp\_part> FROM <date\_time> TO <date\_time> )

DATEDIFF( <timestamp\_part>, <date\_time>, <date\_time> )

timestamp\_part ::= { YEAR \| MONTH \| DAY \| WEEK \| HOUR \| MINUTE \| SECOND \| MILLISECOND }

说明：

1) 如果第二个值大于第一个值，返回正值；

   如果第一个值大于第二个值，返回负值；如果相等，返回零。

2) 日期与时间值的比较是无效的。

3) 不能使用 WEEKDAY 和 YEARDAY。这没有意义。

4) YEAR、MONTH 和 DAY 不能用于时间值。

5) 所有 timestamp\_part 值均可用于时间戳值。

示例：

select datediff(week from cast('yesterday' as timestamp) - 7 to current\_timestamp)

    from rdb$database;

---—

DECODE

---—

功能：

DECODE 是 CASE ... WHEN ... ELSE 表达式的快捷方式。

格式：

DECODE( <expression>, <search>, <result> \[ , <search>, <result> ... \] \[, <default> \]

示例：

select decode(state, 0, 'deleted', 1, 'active', 'unknown') from things;

EXP

功能：

返回参数的自然指数 e。

格式：

EXP( <number> )

示例：

select exp(x) from y;

FLOOR

功能：

返回一个值，表示小于或等于输入参数的最大整数。

格式：

FLOOR( <number> )

示例：

1) select floor(val) from x;

2) select floor(2.1), floor(-2.1) from rdb$database;  -- 返回 2, -3

GEN_UUID

功能：

返回一个 CHAR(16) OCTETS 类型的通用唯一标识符。

格式：

GEN_UUID()

重要说明：

在 Firebird 2.5.2 之前，GEN_UUID 返回的是完全随机的字符串。这不符合

RFC-4122（UUID 规范）。

此问题已在 Firebird 2.5.2 和 3.0 中修复。现在 GEN_UUID 返回符合规范的 UUID 版本 4

字符串，其中某些位是保留的，其余是随机的。符合规范的

UUID 字符串格式为 XXXXXXXX-XXXX-4XXX-YXXX-XXXXXXXXXXXX，其中 4 是固定的（版本号），Y 为 8、9、A 或 B。

示例：

insert into records (id) value (gen_uuid());

另请参阅：CHAR_TO_UUID 和 UUID_TO_CHAR

HASH

功能：

返回字符串的 HASH 值。

格式：

HASH( <string> )

示例：

select hash(x) from y;

LEFT

功能：

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

格式：

LEFT( <string>, <number> )

示例：

select left(name, char_length(name) - 10)

    from people

    where name like '% FERNANDES';

–

功能：

返回一个数的自然对数。

格式：

LN( <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，将 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 常量（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