Update SQL syntax documentation to describe the new CAST expressions. (CVS 2531)

FossilOrigin-Name: d5392866bfd6e06c6d072f649356050b82273a23

manifest

@@ -1,5 +1,5 @@
-C Tcl\sinterface\suses\sTcl_Objs\sto\simplement\suser-defined\sfunctions,\sthus\sallowing\nBLOB\svalues\sto\sbe\stransferred\scorrectly.\s\sTicket\s#1304.\s(CVS\s2530)
-D 2005-06-26T17:55:34
+C Update\sSQL\ssyntax\sdocumentation\sto\sdescribe\sthe\snew\sCAST\sexpressions.\s(CVS\s2531)
+D 2005-06-26T20:00:46
 F Makefile.in 64a6635ef44a98325e0cffe8d67669920a3dad47
 F Makefile.linux-gcc 06be33b2a9ad4f005a5f42b22c4a19dab3cbb5c7
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -266,7 +266,7 @@ F www/faq.tcl 49f31a703f74c71ce66da646aaf18b07a5042672
 F www/fileformat.tcl 900c95b9633abc3dcfc384d9ddd8eb4876793059
 F www/formatchng.tcl 053ddb73646701353a5b1c9ca6274d5900739b45
 F www/index.tcl 9527f4eed69739cf5f81b3d75e0478d1c84d0a8a
-F www/lang.tcl 0083a59de9081f579964a6c3f701b9af3e29bfb6
+F www/lang.tcl 81310355cb9e12fe2b37071b54b3ad9d49290573
 F www/lockingv3.tcl f59b19d6c8920a931f096699d6faaf61c05db55f
 F www/mingw.tcl d96b451568c5d28545fefe0c80bee3431c73f69c
 F www/nulls.tcl ec35193f92485b87b90a994a01d0171b58823fcf
@@ -283,7 +283,7 @@ F www/tclsqlite.tcl 425be741b8ae664f55cb1ef2371aab0a75109cf9
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl a99cf5f6d8bd4d5537584a2b342f0fb9fa601d8b
 F www/whentouse.tcl 528299b8316726dbcc5548e9aa0648c8b1bd055b
-P 3dcdb7942ea9a9e5d708a198ba5183103d5075d9
-R 921bd56e87c8fac8c240733a327a399e
+P 514aaab3f99637ebb8b6e352f4e29738102579b4
+R 1ab86d1a9e2b07f93e497763112fdc00
 U drh
-Z 2d49decf778ceb912dc5c67c477d786e
+Z 409e6bc2a756bbfb87175e52685f9d7e

manifest.uuid

@@ -1 +1 @@
-514aaab3f99637ebb8b6e352f4e29738102579b4
+d5392866bfd6e06c6d072f649356050b82273a23

www/lang.tcl

@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the lang-*.html files.
 #
-set rcsid {$Id: lang.tcl,v 1.92 2005/06/25 19:42:38 drh Exp $}
+set rcsid {$Id: lang.tcl,v 1.93 2005/06/26 20:00:46 drh Exp $}
 source common.tcl
 
 if {[llength $argv]>0} {
@@ -915,14 +915,14 @@ Section expression expr
 
 Syntax {expr} {
 <expr> <binary-op> <expr> |
-<expr> <like-op> <expr> [ESCAPE <expr>] |
-<expr> <glob-op> <expr> |
+<expr> [NOT] <like-op> <expr> [ESCAPE <expr>] |
 <unary-op> <expr> |
 ( <expr> ) |
 <column-name> |
 <table-name> . <column-name> |
 <database-name> . <table-name> . <column-name> |
 <literal-value> |
+<parameter> |
 <function-name> ( <expr-list> | STAR ) |
 <expr> ISNULL |
 <expr> NOTNULL |
@@ -931,11 +931,10 @@ Syntax {expr} {
 <expr> [NOT] IN ( <select-statement> ) |
 <expr> [NOT] IN [<database-name> .] <table-name> |
 [EXISTS] ( <select-statement> ) |
-CASE [<expr>] LP WHEN <expr> THEN <expr> RPPLUS [ELSE <expr>] END
+CASE [<expr>] LP WHEN <expr> THEN <expr> RPPLUS [ELSE <expr>] END |
+CAST ( <expr> AS <type> )
 } {like-op} {
-LIKE | NOT LIKE
-} {glob-op} {
-GLOB | NOT GLOB
+LIKE | GLOB | REGEXP
 }
 
 puts {
@@ -964,12 +963,7 @@ OR</font>
 <font color="#2c2cf0"><big>-    +    !    ~</big></font>
 </pre></blockquote>
 
-<p>Any SQLite value can be used as part of an expression.  
-For arithmetic operations, integers are treated as integers.
-Strings are first converted to real numbers using <b>atof()</b>.
-For comparison operators, numbers compare as numbers and strings
-compare using the <b>strcmp()</b> function.
-Note that there are two variations of the equals and not equals
+<p>Note that there are two variations of the equals and not equals
 operators.  Equals can be either}
 puts "[Operator =] or [Operator ==].
 The non-equals operator can be either
@@ -977,9 +971,77 @@ The non-equals operator can be either
 The [Operator ||] operator is \"concatenate\" - it joins together
 the two strings of its operands.
 The operator [Operator %] outputs the remainder of its left 
-operand modulo its right operand.</p>"
+operand modulo its right operand.</p>
+
+<p>The result of any binary operator is a numeric value, except
+for the [Operator ||] concatenation operator which gives a string
+result.</p>"
+
 puts {
 
+<a name="literal_value"></a>
+<p>
+A literal value is an integer number or a floating point number.
+Scientific notation is supported.  The "." character is always used
+as the decimal point even if the locale setting specifies "," for
+this role - the use of "," for the decimal point would result in
+syntactic ambiguity.  A string constant is formed by enclosing the
+string in single quotes (').  A single quote within the string can
+be encoded by putting two single quotes in a row - as in Pascal.
+C-style escapes using the backslash character are not supported because
+they are not standard SQL.
+BLOB literals are string literals containing hexadecimal data and
+preceded by a single "x" or "X" character.  For example:</p>
+
+<blockquote><pre>
+X'53514697465'
+</pre></blockquote>
+
+<p>
+A literal value can also be the token "NULL".
+</p>
+
+<p>
+A parameter specifies a placeholder in the expression for a literal
+value that is filled in at runtime using the
+<a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> API.
+Parameters can take several forms:
+</p
+
+<blockquote>
+<table>
+<tr>
+<td align="right" valign="top"><b>?</b><i>NNN</i></td><td width="20"></td>
+<td>A question mark followed by a number <i>NNN</i> holds a spot for the
+NNN-th parameter.  NNN must be between 1 and 999.</td>
+</tr>
+<tr>
+<td align="right" valign="top"><b>?</b></td><td width="20"></td>
+<td>A question mark that is not followed by a number holds a spot for
+the next unused parameter.</td>
+</tr>
+<tr>
+<td align="right" valign="top"><b>:</b><i>AAAA</i></td><td width="20"></td>
+<td>A colon followed by an identifier name holds a spot for a named
+parameter with the name AAAA.  Named parameters are also numbered.
+The number assigned is the next unused number.  To avoid confusion,
+it is best to avoid mixing named and numbered parameters.</td>
+</tr>
+<tr>
+<td align="right" valign="top"><b>$</b><i>AAAA</i></td><td width="20"></td>
+<td>A dollar-sign followed by an identifier name also holds a spot for a named
+parameter with the name AAAA.  The identifier name in this case can include
+one or more occurances of "::" and a suffix enclosed in "(...)" containing
+any text at all.  This syntax is the form of a variable name in the Tcl
+programming language.</td>
+</tr>
+</table>
+</blockquote>
+
+<p>Parameters that are not assigned values using
+<a href="capi3ref.html#sqlite3_bind_int">sqlite3_bind</a> are treated
+as NULL.</p>
+
 <a name="like"></a>
 <p>The LIKE operator does a pattern matching comparison. The operand
 to the right contains the pattern, the left hand operand contains the
@@ -1013,9 +1075,14 @@ characters on one side against lower case characters on the other.
 characters.  Hence the LIKE operator is case sensitive for 8-bit
 iso8859 characters or UTF-8 characters.  For example, the expression
 <b>'a'&nbsp;LIKE&nbsp;'A'</b> is TRUE but
-<b>'&aelig;'&nbsp;LIKE&nbsp;'&AElig;'</b> is FALSE.).  The infix LIKE
-operator is identical the user function <a href="#likeFunc">
-like(<i>X</i>,<i>Y</i>)</a>.
+<b>'&aelig;'&nbsp;LIKE&nbsp;'&AElig;'</b> is FALSE.).</p>
+
+<p>The infix LIKE
+operator is implemented by calling the user function <a href="#likeFunc">
+like(<i>X</i>,<i>Y</i>)</a>.  If an ESCAPE clause is present, it adds
+a third parameter to the function call. If the functionality of LIKE can be
+overridden by defining an alternative implementation of the
+like() SQL function.</p>
 </p>
 
 <a name="glob"></a>
@@ -1023,8 +1090,17 @@ like(<i>X</i>,<i>Y</i>)</a>.
 file globbing syntax for its wildcards.  Also, GLOB is case
 sensitive, unlike LIKE.  Both GLOB and LIKE may be preceded by
 the NOT keyword to invert the sense of the test.  The infix GLOB 
-operator is identical the user function <a href="#globFunc">
-glob(<i>X</i>,<i>Y</i>)</a>.</p>
+operator is implemented by calling the user function <a href="#globFunc">
+glob(<i>X</i>,<i>Y</i>)</a> and can be modified by overriding
+that function.</p>
+
+<a name="regexp"></a>
+<p>The REGEXP operator is a special syntax for the regexp()
+user function.  No regexp() user function is defined by default
+and so use of the REGEXP operator will normally result in an
+error message.  If a user-defined function named "regexp"
+is defined at run-time, that function will be called in order
+to implement the REGEXP operator.</p>
 
 <p>A column name can be any of the names defined in the CREATE TABLE
 statement or one of the following special identifiers: "<b>ROWID</b>",
@@ -1066,6 +1142,10 @@ SELECT becomes the value used in the expression.  If the SELECT yields
 more than one result row, all rows after the first are ignored.  If
 the SELECT yields no rows, then the value of the SELECT is NULL.</p>
 
+<p>A CAST expression changes the datatype of the <expr> into the
+type specified by <type>.  <type> can be any non-empty type name that if valid
+for the type in a column definition of a CREATE TABLE statement.</p>
+
 <p>Both simple and aggregate functions are supported.  A simple
 function can be used in any expression.  Simple functions return
 a result immediately based on their inputs.  Aggregate functions