566 lines
27 KiB
HTML
566 lines
27 KiB
HTML
<!DOCTYPE html>
|
|
<html><head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
<link href="sqlite.css" rel="stylesheet">
|
|
<title>Built-In Scalar SQL Functions</title>
|
|
<!-- path= -->
|
|
</head>
|
|
<body>
|
|
<div class=nosearch>
|
|
<a href="index.html">
|
|
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
|
|
</a>
|
|
<div><!-- IE hack to prevent disappearing logo --></div>
|
|
<div class="tagline desktoponly">
|
|
Small. Fast. Reliable.<br>Choose any three.
|
|
</div>
|
|
<div class="menu mainmenu">
|
|
<ul>
|
|
<li><a href="index.html">Home</a>
|
|
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
|
|
<li class='wideonly'><a href='about.html'>About</a>
|
|
<li class='desktoponly'><a href="docs.html">Documentation</a>
|
|
<li class='desktoponly'><a href="download.html">Download</a>
|
|
<li class='wideonly'><a href='copyright.html'>License</a>
|
|
<li class='desktoponly'><a href="support.html">Support</a>
|
|
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
|
|
<li class='search' id='search_menubutton'>
|
|
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
|
|
</ul>
|
|
</div>
|
|
<div class="menu submenu" id="submenu">
|
|
<ul>
|
|
<li><a href='about.html'>About</a>
|
|
<li><a href='docs.html'>Documentation</a>
|
|
<li><a href='download.html'>Download</a>
|
|
<li><a href='support.html'>Support</a>
|
|
<li><a href='prosupport.html'>Purchase</a>
|
|
</ul>
|
|
</div>
|
|
<div class="searchmenu" id="searchmenu">
|
|
<form method="GET" action="search">
|
|
<select name="s" id="searchtype">
|
|
<option value="d">Search Documentation</option>
|
|
<option value="c">Search Changelog</option>
|
|
</select>
|
|
<input type="text" name="q" id="searchbox" value="">
|
|
<input type="submit" value="Go">
|
|
</form>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
function toggle_div(nm) {
|
|
var w = document.getElementById(nm);
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
}else{
|
|
w.style.display = "block";
|
|
}
|
|
}
|
|
function toggle_search() {
|
|
var w = document.getElementById("searchmenu");
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
} else {
|
|
w.style.display = "block";
|
|
setTimeout(function(){
|
|
document.getElementById("searchbox").focus()
|
|
}, 30);
|
|
}
|
|
}
|
|
function div_off(nm){document.getElementById(nm).style.display="none";}
|
|
window.onbeforeunload = function(e){div_off("submenu");}
|
|
/* Disable the Search feature if we are not operating from CGI, since */
|
|
/* Search is accomplished using CGI and will not work without it. */
|
|
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
|
|
document.getElementById("search_menubutton").style.display = "none";
|
|
}
|
|
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
|
|
function hideorshow(btn,obj){
|
|
var x = document.getElementById(obj);
|
|
var b = document.getElementById(btn);
|
|
if( x.style.display!='none' ){
|
|
x.style.display = 'none';
|
|
b.innerHTML='show';
|
|
}else{
|
|
x.style.display = '';
|
|
b.innerHTML='hide';
|
|
}
|
|
return false;
|
|
}
|
|
</script>
|
|
</div>
|
|
<div class=fancy>
|
|
<div class=nosearch>
|
|
<div class="fancy_title">
|
|
Built-In Scalar SQL Functions
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
<h1 id="overview"><span>1. </span>Overview</h1>
|
|
|
|
<p>The core functions shown below are available by default.
|
|
<a href="lang_datefunc.html">Date & Time functions</a>,
|
|
<a href="lang_aggfunc.html">aggregate functions</a>,
|
|
<a href="windowfunctions.html#biwinfunc">window functions</a>, and
|
|
<a href="json1.html">JSON functions</a> are documented separately. An
|
|
application may define additional
|
|
functions written in C and added to the database engine using
|
|
the <a href="c3ref/create_function.html">sqlite3_create_function()</a> API.</p>
|
|
|
|
<p>
|
|
<div class='columns' style='columns: 15em auto;'>
|
|
<ul style='padding-top:0;'>
|
|
<li><a href='lang_corefunc.html#abs'>abs(X)</a></li>
|
|
<li><a href='lang_corefunc.html#changes'>changes()</a></li>
|
|
<li><a href='lang_corefunc.html#char'>char(X1,X2,...,XN)</a></li>
|
|
<li><a href='lang_corefunc.html#coalesce'>coalesce(X,Y,...)</a></li>
|
|
<li><a href='lang_corefunc.html#glob'>glob(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#hex'>hex(X)</a></li>
|
|
<li><a href='lang_corefunc.html#ifnull'>ifnull(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#iif'>iif(X,Y,Z)</a></li>
|
|
<li><a href='lang_corefunc.html#instr'>instr(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#last_insert_rowid'>last_insert_rowid()</a></li>
|
|
<li><a href='lang_corefunc.html#length'>length(X)</a></li>
|
|
<li><a href='lang_corefunc.html#like'>like(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#like'>like(X,Y,Z)</a></li>
|
|
<li><a href='lang_corefunc.html#likelihood'>likelihood(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#likely'>likely(X)</a></li>
|
|
<li><a href='lang_corefunc.html#load_extension'>load_extension(X)</a></li>
|
|
<li><a href='lang_corefunc.html#load_extension'>load_extension(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#lower'>lower(X)</a></li>
|
|
<li><a href='lang_corefunc.html#ltrim'>ltrim(X)</a></li>
|
|
<li><a href='lang_corefunc.html#ltrim'>ltrim(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#maxoreunc'>max(X,Y,...)</a></li>
|
|
<li><a href='lang_corefunc.html#minoreunc'>min(X,Y,...)</a></li>
|
|
<li><a href='lang_corefunc.html#nullif'>nullif(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#printf'>printf(FORMAT,...)</a></li>
|
|
<li><a href='lang_corefunc.html#quote'>quote(X)</a></li>
|
|
<li><a href='lang_corefunc.html#random'>random()</a></li>
|
|
<li><a href='lang_corefunc.html#randomblob'>randomblob(N)</a></li>
|
|
<li><a href='lang_corefunc.html#replace'>replace(X,Y,Z)</a></li>
|
|
<li><a href='lang_corefunc.html#round'>round(X)</a></li>
|
|
<li><a href='lang_corefunc.html#round'>round(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#rtrim'>rtrim(X)</a></li>
|
|
<li><a href='lang_corefunc.html#rtrim'>rtrim(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#soundex'>soundex(X)</a></li>
|
|
<li><a href='lang_corefunc.html#sqlite_compileoption_get'>sqlite_compileoption_get(N)</a></li>
|
|
<li><a href='lang_corefunc.html#sqlite_compileoption_used'>sqlite_compileoption_used(X)</a></li>
|
|
<li><a href='lang_corefunc.html#sqlite_offset'>sqlite_offset(X)</a></li>
|
|
<li><a href='lang_corefunc.html#sqlite_source_id'>sqlite_source_id()</a></li>
|
|
<li><a href='lang_corefunc.html#sqlite_version'>sqlite_version()</a></li>
|
|
<li><a href='lang_corefunc.html#substr'>substr(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#substr'>substr(X,Y,Z)</a></li>
|
|
<li><a href='lang_corefunc.html#total_changes'>total_changes()</a></li>
|
|
<li><a href='lang_corefunc.html#trim'>trim(X)</a></li>
|
|
<li><a href='lang_corefunc.html#trim'>trim(X,Y)</a></li>
|
|
<li><a href='lang_corefunc.html#typeof'>typeof(X)</a></li>
|
|
<li><a href='lang_corefunc.html#unicode'>unicode(X)</a></li>
|
|
<li><a href='lang_corefunc.html#unlikely'>unlikely(X)</a></li>
|
|
<li><a href='lang_corefunc.html#upper'>upper(X)</a></li>
|
|
<li><a href='lang_corefunc.html#zeroblob'>zeroblob(N)</a></li>
|
|
</ul>
|
|
</div>
|
|
|
|
|
|
<h1 id="descriptions_of_built_in_scalar_sql_functions"><span>2. </span>Descriptions of built-in scalar SQL functions</h1>
|
|
<dl>
|
|
|
|
<a name="abs"></a>
|
|
<dt><p><b>abs(<i>X</i>)</b></dt><dd><p>
|
|
The abs(X) function returns the absolute value of the numeric
|
|
argument X. Abs(X) returns NULL if X is NULL.
|
|
Abs(X) returns 0.0 if X is a string or blob
|
|
that cannot be converted to a numeric value. If X is the
|
|
integer -9223372036854775808 then abs(X) throws an integer overflow
|
|
error since there is no equivalent positive 64-bit two complement value.
|
|
</dd>
|
|
<a name="changes"></a>
|
|
<dt><p><b>changes()</b></dt><dd><p>
|
|
The changes() function returns the number of database rows that were changed
|
|
or inserted or deleted by the most recently completed INSERT, DELETE,
|
|
or UPDATE statement, exclusive of statements in lower-level triggers.
|
|
The changes() SQL function is a wrapper around the <a href="c3ref/changes.html">sqlite3_changes()</a>
|
|
C/C++ function and hence follows the same rules for counting changes.
|
|
</dd>
|
|
<a name="char"></a>
|
|
<dt><p><b>char(<i>X1</i>,<i>X2</i>,...,<i>XN</i>)</b></dt><dd><p>
|
|
The char(X1,X2,...,XN) function returns a string composed of characters having the
|
|
unicode code point values of integers X1 through XN, respectively.
|
|
</dd>
|
|
<a name="coalesce"></a>
|
|
<dt><p><b>coalesce(<i>X</i>,<i>Y</i>,...)</b></dt><dd><p>
|
|
The coalesce() function returns a copy of its first non-NULL argument, or
|
|
NULL if all arguments are NULL. Coalesce() must have at least
|
|
2 arguments.
|
|
</dd>
|
|
<a name="glob"></a>
|
|
<dt><p><b>glob(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The glob(X,Y) function is equivalent to the
|
|
expression "<b>Y GLOB X</b>".
|
|
Note that the X and Y arguments are reversed in the glob() function
|
|
relative to the infix <a href="lang_expr.html#glob">GLOB</a> operator. Y is the string and X is the
|
|
pattern. So, for example, the following expressions are equivalent:
|
|
<blockquote><pre>
|
|
name GLOB '*helium*'
|
|
glob('*helium*',name)
|
|
</pre></blockquote>
|
|
<p>If the <a href="c3ref/create_function.html">sqlite3_create_function()</a> interface is used to
|
|
override the glob(X,Y) function with an alternative implementation then
|
|
the <a href="lang_expr.html#glob">GLOB</a> operator will invoke the alternative implementation.
|
|
</dd>
|
|
<a name="hex"></a>
|
|
<dt><p><b>hex(<i>X</i>)</b></dt><dd><p>
|
|
The hex() function interprets its argument as a BLOB and returns
|
|
a string which is the upper-case hexadecimal rendering of the content of
|
|
that blob.
|
|
</dd>
|
|
<a name="ifnull"></a>
|
|
<dt><p><b>ifnull(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The ifnull() function returns a copy of its first non-NULL argument, or
|
|
NULL if both arguments are NULL. Ifnull() must have exactly 2 arguments.
|
|
The ifnull() function is equivalent to <a href="lang_corefunc.html#coalesce">coalesce()</a> with two arguments.
|
|
</dd>
|
|
<a name="iif"></a>
|
|
<dt><p><b>iif(<i>X</i>,<i>Y</i>,<i>Z</i>)</b></dt><dd><p>
|
|
The iif(X,Y,Z) function returns the value Y if X is true, and Z otherwise.
|
|
The iif(X,Y,Z) function is logically equivalent to and generates the same
|
|
<a href="opcode.html">bytecode</a> as the <a href="lang_expr.html#case">CASE expression</a> "CASE WHEN X THEN Y ELSE Z END".
|
|
</dd>
|
|
<a name="instr"></a>
|
|
<dt><p><b>instr(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The instr(X,Y) function finds the first occurrence of string Y within
|
|
string X and returns the number of prior characters plus 1, or 0 if
|
|
Y is nowhere found within X.
|
|
Or, if X and Y are both BLOBs, then instr(X,Y) returns one
|
|
more than the number bytes prior to the first occurrence of Y, or 0 if
|
|
Y does not occur anywhere within X.
|
|
If both arguments X and Y to instr(X,Y) are non-NULL and are not BLOBs
|
|
then both are interpreted as strings.
|
|
If either X or Y are NULL in instr(X,Y) then the result is NULL.
|
|
</dd>
|
|
<a name="last_insert_rowid"></a>
|
|
<dt><p><b>last_insert_rowid()</b></dt><dd><p>
|
|
The last_insert_rowid() function returns the <a href="lang_createtable.html#rowid">ROWID</a>
|
|
of the last row insert from the database connection which invoked the
|
|
function.
|
|
The last_insert_rowid() SQL function is a wrapper around the
|
|
<a href="c3ref/last_insert_rowid.html">sqlite3_last_insert_rowid()</a> C/C++ interface function.
|
|
</dd>
|
|
<a name="length"></a>
|
|
<dt><p><b>length(<i>X</i>)</b></dt><dd><p>
|
|
For a string value X, the length(X) function returns the number of
|
|
characters (not bytes) in X prior to the first NUL character.
|
|
Since SQLite strings do not normally contain NUL characters, the length(X)
|
|
function will usually return the total number of characters in the string X.
|
|
For a blob value X, length(X) returns the number of bytes in the blob.
|
|
If X is NULL then length(X) is NULL.
|
|
If X is numeric then length(X) returns the length of a string
|
|
representation of X.
|
|
</dd>
|
|
<a name="like"></a>
|
|
<dt><p><b>like(<i>X</i>,<i>Y</i>)<br />like(<i>X</i>,<i>Y</i>,<i>Z</i>)</b></dt><dd><p>
|
|
The like() function is used to implement the
|
|
"<b>Y LIKE X [ESCAPE Z]</b>" expression.
|
|
If the optional ESCAPE clause is present, then the
|
|
like() function is invoked with three arguments. Otherwise, it is
|
|
invoked with two arguments only. Note that the X and Y parameters are
|
|
reversed in the like() function relative to the infix <a href="lang_expr.html#like">LIKE</a> operator.
|
|
X is the pattern and Y is the string to match against that pattern.
|
|
Hence, the following expressions are equivalent:
|
|
<blockquote><pre>
|
|
name LIKE '%neon%'
|
|
like('%neon%',name)
|
|
</pre></blockquote>
|
|
<p>The <a href="c3ref/create_function.html">sqlite3_create_function()</a> interface can be used to override the
|
|
like() function and thereby change the operation of the
|
|
<a href="lang_expr.html#like">LIKE</a> operator. When overriding the like() function, it may be important
|
|
to override both the two and three argument versions of the like()
|
|
function. Otherwise, different code may be called to implement the
|
|
<a href="lang_expr.html#like">LIKE</a> operator depending on whether or not an ESCAPE clause was
|
|
specified.
|
|
</dd>
|
|
<a name="likelihood"></a>
|
|
<dt><p><b>likelihood(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The likelihood(X,Y) function returns argument X unchanged.
|
|
The value Y in likelihood(X,Y) must be a floating point constant
|
|
between 0.0 and 1.0, inclusive.
|
|
The likelihood(X) function is a no-op that the code generator
|
|
optimizes away so that it consumes no CPU cycles during run-time
|
|
(that is, during calls to <a href="c3ref/step.html">sqlite3_step()</a>).
|
|
The purpose of the likelihood(X,Y) function is to provide a hint
|
|
to the query planner that the argument X is a boolean that is
|
|
true with a probability of approximately Y.
|
|
The <a href="lang_corefunc.html#unlikely">unlikely(X)</a> function is short-hand for likelihood(X,0.0625).
|
|
The <a href="lang_corefunc.html#likely">likely(X)</a> function is short-hand for likelihood(X,0.9375).
|
|
</dd>
|
|
<a name="likely"></a>
|
|
<dt><p><b>likely(<i>X</i>)</b></dt><dd><p>
|
|
The likely(X) function returns the argument X unchanged.
|
|
The likely(X) function is a no-op that the code generator
|
|
optimizes away so that it consumes no CPU cycles at
|
|
run-time (that is, during calls to <a href="c3ref/step.html">sqlite3_step()</a>).
|
|
The purpose of the likely(X) function is to provide a hint
|
|
to the query planner that the argument X is a boolean value
|
|
that is usually true. The likely(X) function is equivalent
|
|
to <a href="lang_corefunc.html#likelihood">likelihood</a>(X,0.9375). See also: <a href="lang_corefunc.html#unlikely">unlikely(X)</a>.
|
|
</dd>
|
|
<a name="load_extension"></a>
|
|
<dt><p><b>load_extension(<i>X</i>)<br />load_extension(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The load_extension(X,Y) function loads <a href="loadext.html">SQLite extensions</a> out of the shared
|
|
library file named X using the entry point Y. The result of load_extension()
|
|
is always a NULL. If Y is omitted then the default entry point name is used.
|
|
The load_extension() function raises an exception if the extension fails to
|
|
load or initialize correctly.
|
|
|
|
<p>The load_extension() function will fail if the extension attempts to
|
|
modify or delete an SQL function or collating sequence. The
|
|
extension can add new functions or collating sequences, but cannot
|
|
modify or delete existing functions or collating sequences because
|
|
those functions and/or collating sequences might be used elsewhere
|
|
in the currently running SQL statement. To load an extension that
|
|
changes or deletes functions or collating sequences, use the
|
|
<a href="c3ref/load_extension.html">sqlite3_load_extension()</a> C-language API.</p>
|
|
|
|
<p>For security reasons, extension loaded is turned off by default and must
|
|
be enabled by a prior call to <a href="c3ref/enable_load_extension.html">sqlite3_enable_load_extension()</a>.</p>
|
|
</dd>
|
|
<a name="lower"></a>
|
|
<dt><p><b>lower(<i>X</i>)</b></dt><dd><p>
|
|
The lower(X) function returns a copy of string X with all ASCII characters
|
|
converted to lower case. The default built-in lower() function works
|
|
for ASCII characters only. To do case conversions on non-ASCII
|
|
characters, load the ICU extension.
|
|
</dd>
|
|
<a name="ltrim"></a>
|
|
<dt><p><b>ltrim(<i>X</i>)<br />ltrim(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The ltrim(X,Y) function returns a string formed by removing any and all
|
|
characters that appear in Y from the left side of X.
|
|
If the Y argument is omitted, ltrim(X) removes spaces from the left side
|
|
of X.
|
|
</dd>
|
|
<a name="maxoreunc"></a>
|
|
<dt><p><b>max(<i>X</i>,<i>Y</i>,...)</b></dt><dd><p>
|
|
The multi-argument max() function returns the argument with the
|
|
maximum value, or return NULL if any argument is NULL.
|
|
The multi-argument max() function searches its arguments from left to right
|
|
for an argument that defines a collating function and uses that collating
|
|
function for all string comparisons. If none of the arguments to max()
|
|
define a collating function, then the BINARY collating function is used.
|
|
Note that <b>max()</b> is a simple function when
|
|
it has 2 or more arguments but operates as an
|
|
<a href="lang_aggfunc.html#maxggunc">aggregate function</a> if given only a single argument.
|
|
</dd>
|
|
<a name="minoreunc"></a>
|
|
<dt><p><b>min(<i>X</i>,<i>Y</i>,...)</b></dt><dd><p>
|
|
The multi-argument min() function returns the argument with the
|
|
minimum value.
|
|
The multi-argument min() function searches its arguments from left to right
|
|
for an argument that defines a collating function and uses that collating
|
|
function for all string comparisons. If none of the arguments to min()
|
|
define a collating function, then the BINARY collating function is used.
|
|
Note that <b>min()</b> is a simple function when
|
|
it has 2 or more arguments but operates as an
|
|
<a href="lang_aggfunc.html#minggunc">aggregate function</a> if given
|
|
only a single argument.
|
|
</dd>
|
|
<a name="nullif"></a>
|
|
<dt><p><b>nullif(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The nullif(X,Y) function returns its first argument if the arguments are
|
|
different and NULL if the arguments are the same. The nullif(X,Y) function
|
|
searches its arguments from left to right for an argument that defines a
|
|
collating function and uses that collating function for all string
|
|
comparisons. If neither argument to nullif() defines a collating function
|
|
then the BINARY is used.
|
|
</dd>
|
|
<a name="printf"></a>
|
|
<dt><p><b>printf(<i>FORMAT</i>,...)</b></dt><dd><p>
|
|
The printf(FORMAT,...) SQL function works like the <a href="c3ref/mprintf.html">sqlite3_mprintf()</a> C-language
|
|
function and the printf() function from the standard C library.
|
|
The first argument is a format string that specifies how to construct the output
|
|
string using values taken from subsequent arguments. If the FORMAT argument is
|
|
missing or NULL then the result is NULL. The %n format is silently ignored and
|
|
does not consume an argument. The %p format is an alias for %X. The %z format
|
|
is interchangeable with %s. If there are too few arguments in the argument list,
|
|
missing arguments are assumed to have a NULL value, which is translated into
|
|
0 or 0.0 for numeric formats or an empty string for %s. See the
|
|
<a href="printf.html">built-in printf()</a> documentation for additional information.
|
|
</dd>
|
|
<a name="quote"></a>
|
|
<dt><p><b>quote(<i>X</i>)</b></dt><dd><p>
|
|
The quote(X) function returns the text of an SQL literal which
|
|
is the value of its argument suitable for inclusion into an SQL statement.
|
|
Strings are surrounded by single-quotes with escapes on interior quotes
|
|
as needed. BLOBs are encoded as hexadecimal literals.
|
|
Strings with embedded NUL characters cannot be represented as string
|
|
literals in SQL and hence the returned string literal is truncated prior
|
|
to the first NUL.
|
|
</dd>
|
|
<a name="random"></a>
|
|
<dt><p><b>random()</b></dt><dd><p>
|
|
The random() function returns a pseudo-random integer
|
|
between -9223372036854775808 and +9223372036854775807.
|
|
</dd>
|
|
<a name="randomblob"></a>
|
|
<dt><p><b>randomblob(<i>N</i>)</b></dt><dd><p>
|
|
The randomblob(N) function return an N-byte blob containing pseudo-random
|
|
bytes. If N is less than 1 then a 1-byte random blob is returned.
|
|
|
|
<p>Hint: applications can generate globally unique identifiers
|
|
using this function together with <a href="lang_corefunc.html#hex">hex()</a> and/or
|
|
<a href="lang_corefunc.html#lower">lower()</a> like this:</p>
|
|
|
|
<blockquote>
|
|
hex(randomblob(16))<br></br>
|
|
lower(hex(randomblob(16)))
|
|
</blockquote>
|
|
</dd>
|
|
<a name="replace"></a>
|
|
<dt><p><b>replace(<i>X</i>,<i>Y</i>,<i>Z</i>)</b></dt><dd><p>
|
|
The replace(X,Y,Z) function returns a string formed by substituting
|
|
string Z for every occurrence of string Y in string X. The <a href="datatype3.html#collation">BINARY</a>
|
|
collating sequence is used for comparisons. If Y is an empty
|
|
string then return X unchanged. If Z is not initially
|
|
a string, it is cast to a UTF-8 string prior to processing.
|
|
</dd>
|
|
<a name="round"></a>
|
|
<dt><p><b>round(<i>X</i>)<br />round(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The round(X,Y) function returns a floating-point
|
|
value X rounded to Y digits to the right of the decimal point.
|
|
If the Y argument is omitted, it is assumed to be 0.
|
|
</dd>
|
|
<a name="rtrim"></a>
|
|
<dt><p><b>rtrim(<i>X</i>)<br />rtrim(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The rtrim(X,Y) function returns a string formed by removing any and all
|
|
characters that appear in Y from the right side of X.
|
|
If the Y argument is omitted, rtrim(X) removes spaces from the right
|
|
side of X.
|
|
</dd>
|
|
<a name="soundex"></a>
|
|
<dt><p><b>soundex(<i>X</i>)</b></dt><dd><p>
|
|
The soundex(X) function returns a string that is the soundex encoding
|
|
of the string X.
|
|
The string "?000" is returned if the argument is NULL or contains
|
|
no ASCII alphabetic characters.
|
|
This function is omitted from SQLite by default.
|
|
It is only available if the <a href="compile.html#soundex">SQLITE_SOUNDEX</a> compile-time option
|
|
is used when SQLite is built.
|
|
</dd>
|
|
<a name="sqlite_compileoption_get"></a>
|
|
<dt><p><b>sqlite_compileoption_get(<i>N</i>)</b></dt><dd><p>
|
|
The sqlite_compileoption_get() SQL function is a wrapper around the
|
|
<a href="c3ref/compileoption_get.html">sqlite3_compileoption_get()</a> C/C++ function.
|
|
This routine returns the N-th compile-time option used to build SQLite
|
|
or NULL if N is out of range. See also the <a href="pragma.html#pragma_compile_options">compile_options pragma</a>.
|
|
</dd>
|
|
<a name="sqlite_compileoption_used"></a>
|
|
<dt><p><b>sqlite_compileoption_used(<i>X</i>)</b></dt><dd><p>
|
|
The sqlite_compileoption_used() SQL function is a wrapper around the
|
|
<a href="c3ref/compileoption_get.html">sqlite3_compileoption_used()</a> C/C++ function.
|
|
When the argument X to sqlite_compileoption_used(X) is a string which
|
|
is the name of a compile-time option, this routine returns true (1) or
|
|
false (0) depending on whether or not that option was used during the
|
|
build.
|
|
</dd>
|
|
<a name="sqlite_offset"></a>
|
|
<dt><p><b>sqlite_offset(<i>X</i>)</b></dt><dd><p>
|
|
The sqlite_offset(X) function returns the byte offset in the database
|
|
file for the beginning of the record from which value would be read.
|
|
If X is not a column in an ordinary table, then sqlite_offset(X) returns
|
|
NULL. The value returned by sqlite_offset(X) might reference either the
|
|
original table or an index, depending on the query. If the value X would
|
|
normally be extracted from an index, the sqlite_offset(X) returns the
|
|
offset to the corresponding index record. If the value X would be
|
|
extracted from the original table, then sqlite_offset(X) returns the offset
|
|
to the table record.
|
|
|
|
<p>The sqlite_offset(X) SQL function is only available if SQLite is built
|
|
using the <a href="compile.html#enable_offset_sql_func">-DSQLITE_ENABLE_OFFSET_SQL_FUNC</a> compile-time option.
|
|
</dd>
|
|
<a name="sqlite_source_id"></a>
|
|
<dt><p><b>sqlite_source_id()</b></dt><dd><p>
|
|
The sqlite_source_id() function returns a string that identifies the
|
|
specific version of the source code that was used to build the SQLite
|
|
library. The string returned by sqlite_source_id() is
|
|
the date and time that the source code was checked in followed by
|
|
the SHA1 hash for that check-in. This function is
|
|
an SQL wrapper around the <a href="c3ref/libversion.html">sqlite3_sourceid()</a> C interface.
|
|
</dd>
|
|
<a name="sqlite_version"></a>
|
|
<dt><p><b>sqlite_version()</b></dt><dd><p>
|
|
The sqlite_version() function returns the version string for the SQLite
|
|
library that is running. This function is an SQL
|
|
wrapper around the <a href="c3ref/libversion.html">sqlite3_libversion()</a> C-interface.
|
|
</dd>
|
|
<a name="substr"></a>
|
|
<dt><p><b>substr(<i>X</i>,<i>Y</i>,<i>Z</i>)<br />substr(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The substr(X,Y,Z) function returns a substring of input string X that begins
|
|
with the Y-th character and which is Z characters long.
|
|
If Z is omitted then substr(X,Y) returns all characters through the end
|
|
of the string X beginning with the Y-th.
|
|
The left-most character of X is number 1. If Y is negative
|
|
then the first character of the substring is found by counting from the
|
|
right rather than the left. If Z is negative then
|
|
the abs(Z) characters preceding the Y-th character are returned.
|
|
If X is a string then characters indices refer to actual UTF-8
|
|
characters. If X is a BLOB then the indices refer to bytes.
|
|
</dd>
|
|
<a name="total_changes"></a>
|
|
<dt><p><b>total_changes()</b></dt><dd><p>
|
|
The total_changes() function returns the number of row changes
|
|
caused by INSERT, UPDATE or DELETE
|
|
statements since the current database connection was opened.
|
|
This function is a wrapper around the <a href="c3ref/total_changes.html">sqlite3_total_changes()</a>
|
|
C/C++ interface.
|
|
</dd>
|
|
<a name="trim"></a>
|
|
<dt><p><b>trim(<i>X</i>)<br />trim(<i>X</i>,<i>Y</i>)</b></dt><dd><p>
|
|
The trim(X,Y) function returns a string formed by removing any and all
|
|
characters that appear in Y from both ends of X.
|
|
If the Y argument is omitted, trim(X) removes spaces from both ends of X.
|
|
</dd>
|
|
<a name="typeof"></a>
|
|
<dt><p><b>typeof(<i>X</i>)</b></dt><dd><p>
|
|
The typeof(X) function returns a string that indicates the <a href="datatype3.html">datatype</a> of
|
|
the expression X: "null", "integer", "real", "text", or "blob".
|
|
</dd>
|
|
<a name="unicode"></a>
|
|
<dt><p><b>unicode(<i>X</i>)</b></dt><dd><p>
|
|
The unicode(X) function returns the numeric unicode code point corresponding to
|
|
the first character of the string X. If the argument to unicode(X) is not a string
|
|
then the result is undefined.
|
|
</dd>
|
|
<a name="unlikely"></a>
|
|
<dt><p><b>unlikely(<i>X</i>)</b></dt><dd><p>
|
|
The unlikely(X) function returns the argument X unchanged.
|
|
The unlikely(X) function is a no-op that the code generator
|
|
optimizes away so that it consumes no CPU cycles at
|
|
run-time (that is, during calls to <a href="c3ref/step.html">sqlite3_step()</a>).
|
|
The purpose of the unlikely(X) function is to provide a hint
|
|
to the query planner that the argument X is a boolean value
|
|
that is usually not true. The unlikely(X) function is equivalent
|
|
to <a href="lang_corefunc.html#likelihood">likelihood</a>(X, 0.0625).
|
|
</dd>
|
|
<a name="upper"></a>
|
|
<dt><p><b>upper(<i>X</i>)</b></dt><dd><p>
|
|
The upper(X) function returns a copy of input string X in which all
|
|
lower-case ASCII characters are converted to their upper-case equivalent.
|
|
</dd>
|
|
<a name="zeroblob"></a>
|
|
<dt><p><b>zeroblob(<i>N</i>)</b></dt><dd><p>
|
|
The zeroblob(N) function returns a BLOB consisting of N bytes of 0x00.
|
|
SQLite manages these zeroblobs very efficiently. Zeroblobs can be used to
|
|
reserve space for a BLOB that is later written using
|
|
<a href="c3ref/blob_open.html">incremental BLOB I/O</a>.
|
|
This SQL function is implemented using the <a href="c3ref/result_blob.html">sqlite3_result_zeroblob()</a>
|
|
routine from the C/C++ interface.
|
|
</dd>
|
|
|
|
</dl>
|
|
|