Core Functions

[Top]

核心函数

下面显示的核心功能默认可用。日期和时间函数，聚合函数和 JSON 函数分开记录。应用程序可以定义用 C 编写的附加函数，并使用 sqlite3_create_function() API 将其添加到数据库引擎。

• abs(X)

• changes()

• char(X1,X2,...,XN)

• coalesce(X,Y,...)

• glob(X,Y)

• hex(X)

• ifnull(X,Y)

• instr(X,Y)

• last_insert_rowid()

• length(X)

• like(X,Y)

• like(X,Y,Z)

• likelihood(X,Y)

• likely(X)

• load_extension(X)

• load_extension(X,Y)

• lower(X)

• ltrim(X)

• ltrim(X,Y)

• max(X,Y,...)

• min(X,Y,...)

• nullif(X,Y)

• printf(FORMAT,...)

• quote(X)

• random()

• randomblob(N)

• replace(X,Y,Z)

• round(X)

• round(X,Y)

• rtrim(X)

• rtrim(X,Y)

• soundex(X)

• sqlite_compileoption_get(N)

• sqlite_compileoption_used(X)

• sqlite_source_id()

• sqlite_version()

• substr(X,Y)

• substr(X,Y,Z)

• total_changes()

• trim(X)

• trim(X,Y)

• typeof(X)

• unicode(X)

• unlikely(X)

• upper(X)

• zeroblob(N)

abs(X)

abs(X) 函数返回数值参数X的绝对值。如果 X 为 NULL ，则Abs(X) 返回 NULL 。如果 X 是无法转换为数值的字符串或 blob ，则 Abs(X) 将返回0.0。如果 X 是整数 -9223372036854775808 ，则 abs(X) 将抛出整数溢出错误，因为没有等价的正64位二补数值。

changes()

changes() 函数返回最近完成的 INSERT ，DELETE 或 UPDATE 语句更改或插入或删除的数据库行数，不包括低级触发器中的语句。changes() SQL 函数是 sqlite3_changes() C/C ++ 函数的一个包装，因此遵循相同的规则来计算更改。

char(X1,X2,...,XN)

char（X1，X2，...，XN）函数返回一个字符串，它由分别具有整数 X1 至 XN 的 unicode 编码点值的字符组成。

coalesce(X,Y,...)

coalesce() 函数返回其第一个非 NULL 参数的副本，如果所有参数都为 NULL ，则返回 NULL 。Coalesce() 必须至少有2个参数。

glob(X,Y)

glob(X,Y) 函数等价于表达式“ Y GLOB X ”。请注意，相对于中缀 GLOB 运算符，glob() 函数中的 X 和 Y 参数是相反的。如果使用 sqlite3_create_function() 接口用替代实现覆盖 glob(X,Y) 函数，则 GLOB 操作符将调用替代实现。

hex(X)

hex() 函数将其参数解释为 BLOB 并返回一个字符串，该字符串是 blob 内容的大写十六进制呈现。

ifnull(X,Y)

ifnull() 函数返回其第一个非 NULL 参数的副本，如果两个参数都为 NULL ，则返回 NULL 。Ifnull() 必须有2个参数。ifnull() 函数等价于具有两个参数的 coalesce() 。

instr(X,Y)

instr(X,Y) 函数查找字符串 X 中字符串 Y 的第一次出现，并返回前面字符的数目加1，或者如果在 X 中找不到 Y ，则返回0。或者，如果 X 和 Y 都是 BLOB ，则 instr(X,Y) 返回比第一次出现 Y 之前的数字字节多一个，或者如果 Y 不出现在X内的任何地方，则返回0。如果 instr(X,Y) 的两个参数 X 和 Y 非空，并且是不是 BLOB ，则两者都被解释为字符串。如果 instr(X,Y) 中的 X 或 Y 为 NULL ，则结果为 NULL 。

last_insert_rowid()

last_insert_rowid() 函数返回调用函数的数据库连接的最后一行插入的 ROWID 。last_insert_rowid() SQL 函数是 sqlite3_last_insert_rowid() C / C ++ 接口函数的封装。

length(X)

对于字符串值 X ，length(X) 函数返回第一个 NUL 字符之前的 X 中的字符数（不是字节）。由于 SQLite 字符串通常不包含 NUL 字符，因此 length(X) 函数通常会返回字符串 X 中的字符总数。对于 blob 值 X ，length(X) 将返回 blob 中的字节数。如果 X 为 NULL ，则 length(X) 为 NULL 。如果 X 是数字，那么 length(X) 返回 X 的字符串表示的长度。

like(X,Y)

like(X,Y,Z)

like() 函数用于实现“ Y LIKE X ESCAPE Z ”表达式。如果存在可选的 ESCAPE 子句，则使用三个参数调用 like() 函数。否则，它仅用两个参数来调用。请注意，相对于中缀 LIKE 运算符，like() 函数中的 X 和 Y 参数是相反的。sqlite3_create_function() 接口可用于重写 like() 函数，从而更改 LIKE 运算符的操作。覆盖 like() 函数时，重写 like() 函数的两个和三个参数版本可能很重要。否则，可能会调用不同的代码来实现 LIKE 运算符，具体取决于是否指定了 ESCAPE 子句。

likelihood(X,Y)

likelihood(X,Y) 函数返回参数X不变。 likelihood(X,Y) 中的值 Y 必须是介于0.0和1.0之间的浮点常量（包含边界值）。 likelihood(X,Y) 函数是代码生成器优化消除的无操作，以便在运行时（即在调用sqlite3_step()期间）不消耗 CPU 周期。 likelihood(X,Y) 函数的作用是向查询规划器提供一个提示，即参数 X 是一个布尔值，其概率为 Y 。对于可能性来说，unlikely(X) 函数是简短的 likelihood(X,0.0625) 。likely(X) 函数对于可能性是很短的 likelihood(X,0.9375) 。

likely(X)

likely(X) 函数返回参数X不变。likely(X) 函数是代码生成器优化消除的无操作，以便它在运行时不消耗 CPU 周期（也就是在调用sqlite3_step() 时）。likely(X) 函数的目的是向查询规划器提供一个提示，即参数X是一个通常为 true 的布尔值。likely(X) 函数等同于 likely(X) 。另见：unlikely(X) 。

load_extension(X)

load_extension(X,Y)

load_extension(X,Y)函数使用入口点Y将SQLite扩展加载到名为X的共享库文件中。load_extension()的结果始终为NULL。如果省略Y，则使用默认入口点名称。如果扩展未能正确加载或初始化，则load_extension()函数会引发异常。

如果扩展尝试修改或删除SQL函数或整理序列，则load_extension()函数将失败。该扩展可以添加新功能或整理序列，但不能修改或删除现有功能或整理序列，因为这些功能和/或整理序列可能在当前运行的SQL语句的其他地方使用。要加载更改或删除函数或整理序列的扩展，请使用sqlite3_load_extension()C语言API。

出于安全原因，扩展加载默认情况下处于关闭状态，并且必须事先调用sqlite3_enable_load_extension()来启用。

lower(X)

lower(X)函数返回字符串X的副本，并将所有ASCII字符转换为小写字母。默认的内置lower(X)函数仅适用于ASCII字符。要对非ASCII字符进行大小写转换，请加载ICU扩展。

ltrim(X)

ltrim(X,Y)

ltrim(X,Y)函数返回一个通过从X的左侧删除出现在Y中的任何和所有字符形成的字符串。如果省略了Y参数，则ltrim(X)将从X的左侧删除空格。

max(X,Y,...)

多参数max()函数返回带有最大值的参数，或者如果任何参数为NULL，则返回NULL。多参数max()函数从左到右搜索其参数，用于定义整理函数的参数，并使用该整理函数进行所有字符串比较。如果max()的参数都没有定义整理函数，则使用BINARY整理函数。请注意，max()是一个简单的函数，当它有两个或更多个参数时，如果只有一个参数，则它作为一个聚合函数运行。

min(X,Y,...)

多参数min()函数返回具有最小值的参数。多参数min()函数从左到右搜索其参数，用于定义整理函数的参数，并将该整理函数用于所有字符串比较。如果min()的参数都没有定义整理函数，则使用BINARY整理函数。请注意，min()是一个简单的函数，当它有两个或更多个参数时，如果仅给定一个参数，则它作为一个聚合函数运行。

nullif(X,Y)

如果参数不同，nullif(X,Y) 函数将返回其第一个参数，如果参数相同，则返回NULL。nullif(X,Y) 函数从左到右搜索其参数，用于定义整理函数的参数，并将该整理函数用于所有字符串比较。如果nullif()的参数都没有定义一个整理函数，那么就使用BINARY。

printf(FORMAT,...)

printf（FORMAT，...）SQL函数的工作方式与sqlite3_mprintf() C语言函数和标准C库中的printf()函数类似。第一个参数是一个格式字符串，它指定如何使用从后续参数中获取的值来构造输出字符串。如果FORMAT参数缺失或NULL，则结果为NULL。％n格式默默无视，不会消耗参数。％p格式是％X的别名。％z格式可以与％s互换。如果参数列表中的参数太少，则缺少的参数会被假定为NULL值，对于数字格式，它将转换为0或0.0，对于％s则为空字符串。

quote(X)

quote(X)函数返回SQL文本的文本，该文本是适合包含在SQL语句中的参数的值。根据需要，字符串被内部引号中的单引号包围。BLOB被编码为十六进制文字。带有嵌入式NUL字符的字符串不能在SQL中表示为字符串文字，因此返回的字符串文字在第一个NUL之前被截断。

random()

random()函数返回-9223372036854775808和+9223372036854775807之间的伪随机整数。

randomblob(N)

randomblob(N)函数返回包含伪随机字节的N字节blob。如果N小于1，则返回一个1字节的随机数据块。

提示：应用程序可以使用这个函数与hex() and/or lower()一起生成全局唯一标识符，如下所示：

hex(randomblob(16)) lower(hex(randomblob(16)))

replace(X,Y,Z)

replace(X,Y,Z)函数返回一个字符串，它是通过将字符串Z替换为字符串X中出现的每个字符串Y而形成的。BINARY整理序列用于比较。如果Y是一个空字符串，则返回X不变。如果Z最初不是字符串，则在处理之前将其转换为UTF-8字符串。

round(X)

round(X,Y)

round(X,Y)函数返回一个浮点值X，舍入到小数点右侧的Y位数。如果省略Y参数，则假定为0。

rtrim(X)

rtrim(X,Y)

rtrim(X,Y)函数返回一个通过从X右侧删除出现在Y中的所有字符形成的字符串。如果省略了Y参数，则rtrim(X)将删除X右侧的空格。

soundex(X)

soundex(X)函数返回一个字符串，它是字符串X的soundex编码。如果参数为NULL或不包含ASCII字母字符，则返回字符串“？000”。这个函数默认从SQLite中省略。只有在构建SQLite时使用SQLITE_SOUNDEX编译时选项才可用。

sqlite_compileoption_get(N)

sqlite_compileoption_get() SQL函数是sqlite3_compileoption_get() C/C++函数的一个封装。此例程返回用于构建SQLite的第N个编译时选项，如果N超出范围，则返回NULL。另请参阅compile_options杂注。

sqlite_compileoption_used(X)

sqlite_compileoption_used()SQL函数是sqlite3_compileoption_used() C/C++函数的一个包装。当sqlite_compileoption_used(X)的参数X是一个是编译时选项名称的字符串时，此例程返回true(1)或false(0)，具体取决于在构建过程中是否使用了该选项。

sqlite_source_id()

sqlite_source_id()函数返回一个字符串，该字符串标识用于构建SQLite库的源代码的特定版本。sqlite_source_id()返回的字符串是签入源代码的日期和时间，后跟该签入的SHA1哈希值。这个函数是sqlite3_sourceid()C接口的SQL包装器。

sqlite_version()

sqlite_version()函数返回正在运行的SQLite库的版本字符串。这个函数是sqlite3_libversion()C接口的SQL包装器。

substr(X,Y,Z)

substr(X,Y)

substr(X,Y,Z) 函数返回输入字符串X的一个子字符串，该字符串以第Y个字符开头，并且长度为Z个字符。如果省略Z，那么substr(X,Y)将返回从第Y行开始的字符串X的末尾的所有字符。X的最左边的字符是数字1.如果Y是负数，则子字符串的第一个字符通过从右侧而不是从左侧开始计算。如果Z是负数，则返回第Y个字符前面的绝对(Z)字符。如果X是一个字符串，则字符索引将引用实际的UTF-8字符。如果X是一个BLOB，那么索引就是指字节。

total_changes()

total_changes()函数返回自当前数据库连接打开以来由INSERT，UPDATE或DELETE语句引起的行更改次数。这个函数是sqlite3_total_changes()C/C++接口的一个包装。

trim(X)

trim(X,Y)

trim(X,Y)函数返回一个通过从X的两端删除出现在Y中的任何和所有字符形成的字符串。如果省略了Y参数，trim(X)将从X的两端删除空格。

typeof(X)

typeof(X)函数返回一个字符串，该字符串指示表达式X的数据类型：“null”，“integer”，“real”，“text”或“blob”。

unicode(X)

unicode(X)函数返回对应于字符串X的第一个字符的数字unicode代码点。如果unicode(X)的参数不是字符串，则结果是未定义的。

unlikely(X)

unlikely(X)函数返回参数X不变。unlikely(X)函数是代码生成器优化消除的无操作，以便它在运行时不消耗CPU周期（也就是在调用sqlite3_step()时）。unlikely(X)函数的目的是向查询规划器提供一个提示，即参数X是一个通常不是true的布尔值。unlikely(X)函数等价于likelihood(X, 0.0625)。

upper(X)

upper(X) 函数返回一个输入字符串X的副本，其中所有小写ASCII字符都转换为其大写等价物。

zeroblob(N)

zeroblob(N)函数返回一个由N个字节0x00组成的BLOB。SQLite非常有效地管理这些zeroblobs。可以使用Zeroblobs为稍后使用增量BLOB I/O写入的BLOB保留空间。这个SQL函数是使用C/C++接口中的sqlite3_result_zeroblob()例程实现的。