Added explanation and examples for %Q format specifier. (CVS 623)

FossilOrigin-Name: 633ce4dd252ac351b04bdb7bed2d5374ee9a3f12

manifest

@@ -1,5 +1,5 @@
-C Added\sprintf-4.(2-4)\stest\scases\sto\stest\snew\s%Q\sformat\sspecifier.\s(CVS\s622)
-D 2002-06-16T04:56:37
+C Added\sexplanation\sand\sexamples\sfor\s%Q\sformat\sspecifier.\s(CVS\s623)
+D 2002-06-16T04:57:32
 F Makefile.in 6291a33b87d2a395aafd7646ee1ed562c6f2c28c
 F Makefile.template 4e11752e0b5c7a043ca50af4296ec562857ba495
 F README a4c0ba11354ef6ba0776b400d057c59da47a4cc0
@@ -121,7 +121,7 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F www/arch.fig d5f9752a4dbf242e9cfffffd3f5762b6c63b3bcf
 F www/arch.png 82ef36db1143828a7abc88b1e308a5f55d4336f4
 F www/arch.tcl 72a0c80e9054cc7025a50928d28d9c75c02c2b8b
-F www/c_interface.tcl badaceafef1cccbdca3bfcb09c1bf2391859e431
+F www/c_interface.tcl 58cf4d128dcae08d91d0011c6d4d11de323f470f
 F www/changes.tcl d1057bb733c574d9dca73578daf78a3128a61426
 F www/conflict.tcl 81dd21f9a679e60aae049e9dd8ab53d59570cda2
 F www/crosscompile.tcl 3622ebbe518927a3854a12de51344673eb2dd060
@@ -137,7 +137,7 @@ F www/speed.tcl da8afcc1d3ccc5696cfb388a68982bc3d9f7f00f
 F www/sqlite.tcl 8b5884354cb615049aed83039f8dfe1552a44279
 F www/tclsqlite.tcl 1db15abeb446aad0caf0b95b8b9579720e4ea331
 F www/vdbe.tcl 2013852c27a02a091d39a766bc87cff329f21218
-P b9c7ecc2f9d8d7d57c51dc4ba0aaa520e89eb31f
-R e772258ee0dc04fdc02553a51e656b4b
+P 7d5fc35b5d38230230344b4f70763f75940ab908
+R d122c615a4148cedce3cbd33972d093f
 U chw
-Z 413c80ebe0a7609981d76612786a2b60
+Z 3a86dbdae8ed57285b80b82bbf99d831

manifest.uuid

@@ -1 +1 @@
-7d5fc35b5d38230230344b4f70763f75940ab908
+633ce4dd252ac351b04bdb7bed2d5374ee9a3f12

www/c_interface.tcl

@@ -1,7 +1,7 @@
 #
 # Run this Tcl script to generate the sqlite.html file.
 #
-set rcsid {$Id: c_interface.tcl,v 1.29 2002/05/15 23:26:23 drh Exp $}
+set rcsid {$Id: c_interface.tcl,v 1.30 2002/06/16 04:57:32 chw Exp $}
 
 puts {<html>
 <head>
@@ -618,14 +618,18 @@ as much memory as is
 necessary to hold the SQL statements generated.</p>
 
 <p>The second advantage the SQLite printf routines have over
-<b>sprintf()</b> is a new formatting option specifically designed
+<b>sprintf()</b> are two new formatting options specifically designed
 to support string literals in SQL.  Within the format string,
 the %q formatting option works very much like %s in that it
 reads a null-terminated string from the argument list and inserts
 it into the result.  But %q translates the inserted string by
 making two copies of every single-quote (') character in the
 substituted string.  This has the effect of escaping the end-of-string
-meaning of single-quote within a string literal.
+meaning of single-quote within a string literal. The %Q formatting
+option works similar; it translates the single-quotes like %q and
+additionally encloses the resulting string in single-quotes.
+If the argument for the %Q formatting options is a NULL pointer,
+the resulting string is NULL without single quotes.
 </p>
 
 <p>Consider an example.  Suppose you are trying to insert a string
@@ -668,6 +672,28 @@ single-quote character ('), it is always a good idea to use the
 SQLite printf routines and the %q formatting option instead of <b>sprintf</b>.
 </p>
 
+<p>If the %Q formatting option is used instead of %q, like this:</p>
+
+<blockquote><pre>
+sqlite_exec_printf(db,
+  "INSERT INTO table1 VALUES(%Q)",
+  0, 0, 0, zString);
+</pre></blockquote>
+
+<p>Then the generated SQL will look like the following:</p>
+
+<blockquote><pre>
+INSERT INTO table1 VALUES('Hi y''all')
+</pre></blockquote>
+
+<p>If the value of the zString variable is NULL, the generated SQL
+will look like the following:</p>
+
+<blockquote><pre>
+INSERT INTO table1 VALUES(NULL)
+</pre></blockquote>
+
+
 <h2>Adding New SQL Functions</h2>
 
 <p>Beginning with version 2.4.0, SQLite allows the SQL language to be