Documentation Source Text

Check-in [5608ec77f8]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Updates to expression documentation.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 5608ec77f8c396aeb39106d40c44203cfbce0420
User & Date: drh 2014-08-11 18:36:51
Context
2014-08-11
21:17
Fix requirements marks in the file format document. Improvements to PRAGMA documentation. check-in: e09448dc9d user: drh tags: trunk
18:36
Updates to expression documentation. check-in: 5608ec77f8 user: drh tags: trunk
2014-08-08
21:27
Fix documentation errors and typos. check-in: 066b35fad5 user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to pages/lang.in.

1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
....
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
....
2238
2239
2240
2241
2242
2243
2244
2245

2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259






2260
2261
2262
2263
2264
2265
2266
....
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482

<p>^Parameters that are not assigned values using
[sqlite3_bind_blob() | sqlite3_bind()] are treated
as NULL.  The [sqlite3_bind_parameter_index()] interface can be used
to translate a symbolic parameter name into its equivalent numeric index.</p>

<p>^The maximum parameter number is set at compile-time by
the [SQLITE_MAX_VARIABLE_NUMBER] macro.  ^(An individual [database connections]
D can reduce its maximum parameter number below the compile-time maximum
using the [sqlite3_limit](D, [SQLITE_LIMIT_VARIABLE_NUMBER],...) interface.)^
</p>

<tcl>hd_fragment like LIKE ESCAPE</tcl>
<h3>The LIKE and GLOB operators</h3>
<p>^The LIKE operator does a pattern matching comparison. ^The operand
................................................................................
  <td> ^When casting a BLOB value to INTEGER, the value is first converted to
        TEXT.
       <p>^When casting a TEXT value to INTEGER, the longest possible prefix of
        the value that can be interpreted as an integer number is extracted from
        the TEXT value and the remainder ignored. ^Any leading spaces in the
        TEXT value when converting from TEXT to INTEGER are ignored. ^If there
        is no prefix that can be interpreted as an integer number, the result
        of the conversion is 0.  The CAST operator understands decimal integers
        only &mdash; conversion of [hexadecimal integers] stops at the "x" in the
        "0x" prefix of the hexadecimal integer string and thus result of the 
        CAST is always zero.

      <p>^A cast of a REAL value into an INTEGER results in the integer
      between the REAL value and zero that is closest to the REAL value.
      ^If a REAL is greater than the greatest possible signed
      integer (+9223372036854775807) then the result is the greatest possible
      signed integer and if the REAL is less than the least possible signed
      integer (-9223372036854775808) then the result is the least possible
................................................................................
    <li> the HAVING clause of a SELECT statement,
    <li> the WHEN clause of an SQL trigger, and
    <li> the WHEN clause or clauses of some CASE expressions.
  </ul>

<p>^(To convert the results of an SQL expression to a boolean value, SQLite
first casts the result to a NUMERIC value in the same way as a 
[CAST expression]. A NULL or zero value (integer value 0 or real value 0.0) is

considered to be false. All other values are considered true.)^

<p>^(For example, the values NULL, 0.0, 0, 'english' and '0' are all considered
to be false.)^ ^(Values 1, 1.0, 0.1, -0.1 and '1english' are considered to 
be true.)^

<h3>Functions</h3>
<p>^Both [corefunc|simple] and [aggfunc|aggregate] functions are supported.
(For presentation purposes, simple functions are further subdivided into
[corefunc | core functions] and [datefunc | date-time functions].)
^A simple function can be used in any expression.  ^Simple functions return
a result immediately based on their inputs.  ^Aggregate functions
may only be used in a SELECT statement.  ^Aggregate functions compute
their result across all rows of the result set.</p>







<tcl>
##############################################################################
Section {Core Functions} corefunc {*corefunc}
proc funcdef {syntax keywords desc} {
  hd_puts {<tr>}
  regsub -all {\s+} [string trim $syntax] {<br />} syntax
................................................................................
funcdef {max(X,Y,...)} {*maxCoreFunc *max {max() SQL function}} {
  ^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
  [minAggFunc | aggregate function] if given only a single argument.
}

funcdef {min(X,Y,...)} {*minCoreFunc *min {min() SQL function}} {
  ^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 
  [maxAggFunc | aggregate function] if given
  only a single argument.
}

funcdef {nullif(X,Y)} {} {
  ^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







|







 







|


|







 







|
>
|






|
|
|
|
|
|
<
>
>
>
>
>
>







 







|

|









|

|
|







1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
....
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
....
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259

2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
....
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488

<p>^Parameters that are not assigned values using
[sqlite3_bind_blob() | sqlite3_bind()] are treated
as NULL.  The [sqlite3_bind_parameter_index()] interface can be used
to translate a symbolic parameter name into its equivalent numeric index.</p>

<p>^The maximum parameter number is set at compile-time by
the [SQLITE_MAX_VARIABLE_NUMBER] macro.  ^(An individual [database connection]
D can reduce its maximum parameter number below the compile-time maximum
using the [sqlite3_limit](D, [SQLITE_LIMIT_VARIABLE_NUMBER],...) interface.)^
</p>

<tcl>hd_fragment like LIKE ESCAPE</tcl>
<h3>The LIKE and GLOB operators</h3>
<p>^The LIKE operator does a pattern matching comparison. ^The operand
................................................................................
  <td> ^When casting a BLOB value to INTEGER, the value is first converted to
        TEXT.
       <p>^When casting a TEXT value to INTEGER, the longest possible prefix of
        the value that can be interpreted as an integer number is extracted from
        the TEXT value and the remainder ignored. ^Any leading spaces in the
        TEXT value when converting from TEXT to INTEGER are ignored. ^If there
        is no prefix that can be interpreted as an integer number, the result
        of the conversion is 0.  ^(The CAST operator understands decimal integers
        only &mdash; conversion of [hexadecimal integers] stops at the "x" in the
        "0x" prefix of the hexadecimal integer string and thus result of the 
        CAST is always zero.)^

      <p>^A cast of a REAL value into an INTEGER results in the integer
      between the REAL value and zero that is closest to the REAL value.
      ^If a REAL is greater than the greatest possible signed
      integer (+9223372036854775807) then the result is the greatest possible
      signed integer and if the REAL is less than the least possible signed
      integer (-9223372036854775808) then the result is the least possible
................................................................................
    <li> the HAVING clause of a SELECT statement,
    <li> the WHEN clause of an SQL trigger, and
    <li> the WHEN clause or clauses of some CASE expressions.
  </ul>

<p>^(To convert the results of an SQL expression to a boolean value, SQLite
first casts the result to a NUMERIC value in the same way as a 
[CAST expression]. A numeric zero value (integer value 0 or real 
value 0.0) is considered to be false.  A NULL value is still NULL.
All other values are considered true.)^

<p>^(For example, the values NULL, 0.0, 0, 'english' and '0' are all considered
to be false.)^ ^(Values 1, 1.0, 0.1, -0.1 and '1english' are considered to 
be true.)^

<h3>Functions</h3>
<p>SQLite supports many [corefunc|simple] and [aggfunc|aggregate]
SQL functions.  For presentation purposes, simple functions are further
subdivided into [corefunc | core functions] and [datefunc|date-time functions].
Applications can add new functions, written in C/C++, using the
[sqlite3_create_function()] interface.
</p>


<p>^It is possible to have an aggregate function with the same name as a
simple function, as long as the number of arguments for the two forms of the
function are different.  ^For example, the [agg_max|max()] function with a
single argument is an aggregate and the [max()] function with two or more
arguments is a simple function.

<tcl>
##############################################################################
Section {Core Functions} corefunc {*corefunc}
proc funcdef {syntax keywords desc} {
  hd_puts {<tr>}
  regsub -all {\s+} [string trim $syntax] {<br />} syntax
................................................................................
funcdef {max(X,Y,...)} {*maxCoreFunc *max {max() SQL function}} {
  ^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
  [maxAggFunc | aggregate function] if given only a single argument.)^
}

funcdef {min(X,Y,...)} {*minCoreFunc *min {min() SQL function}} {
  ^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 
  [minAggFunc | aggregate function] if given
  only a single argument.)^
}

funcdef {nullif(X,Y)} {} {
  ^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