/ Check-in [633ce4dd]
Login

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

Overview
Comment:Added explanation and examples for %Q format specifier. (CVS 623)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:633ce4dd252ac351b04bdb7bed2d5374ee9a3f12
User & Date: chw 2002-06-16 04:57:32
Context
2002-06-16
18:21
Expose an additional internal API routine (sqliteInitCallback()) for use by private code. (CVS 624) check-in: cd74495f user: drh tags: trunk
04:57
Added explanation and examples for %Q format specifier. (CVS 623) check-in: 633ce4dd user: chw tags: trunk
04:56
Added printf-4.(2-4) test cases to test new %Q format specifier. (CVS 622) check-in: 7d5fc35b user: chw tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to www/c_interface.tcl.

     1      1   #
     2      2   # Run this Tcl script to generate the sqlite.html file.
     3      3   #
     4         -set rcsid {$Id: c_interface.tcl,v 1.29 2002/05/15 23:26:23 drh Exp $}
            4  +set rcsid {$Id: c_interface.tcl,v 1.30 2002/06/16 04:57:32 chw Exp $}
     5      5   
     6      6   puts {<html>
     7      7   <head>
     8      8     <title>The C language interface to the SQLite library</title>
     9      9   </head>
    10     10   <body bgcolor=white>
    11     11   <h1 align=center>
................................................................................
   614    614   SQLite printf routines, there is never a danger of overflowing a
   615    615   static buffer as there is with <b>sprintf()</b>.  The SQLite
   616    616   printf routines automatically allocate (and later free)
   617    617   as much memory as is 
   618    618   necessary to hold the SQL statements generated.</p>
   619    619   
   620    620   <p>The second advantage the SQLite printf routines have over
   621         -<b>sprintf()</b> is a new formatting option specifically designed
          621  +<b>sprintf()</b> are two new formatting options specifically designed
   622    622   to support string literals in SQL.  Within the format string,
   623    623   the %q formatting option works very much like %s in that it
   624    624   reads a null-terminated string from the argument list and inserts
   625    625   it into the result.  But %q translates the inserted string by
   626    626   making two copies of every single-quote (') character in the
   627    627   substituted string.  This has the effect of escaping the end-of-string
   628         -meaning of single-quote within a string literal.
          628  +meaning of single-quote within a string literal. The %Q formatting
          629  +option works similar; it translates the single-quotes like %q and
          630  +additionally encloses the resulting string in single-quotes.
          631  +If the argument for the %Q formatting options is a NULL pointer,
          632  +the resulting string is NULL without single quotes.
   629    633   </p>
   630    634   
   631    635   <p>Consider an example.  Suppose you are trying to insert a string
   632    636   value into a database table where the string value was obtained from
   633    637   user input.  Suppose the string to be inserted is stored in a variable
   634    638   named zString.  The code to do the insertion might look like this:</p>
   635    639   
................................................................................
   663    667   </pre></blockquote>
   664    668   
   665    669   <p>Here the apostrophy has been escaped and the SQL statement is well-formed.
   666    670   When generating SQL on-the-fly from data that might contain a
   667    671   single-quote character ('), it is always a good idea to use the
   668    672   SQLite printf routines and the %q formatting option instead of <b>sprintf</b>.
   669    673   </p>
          674  +
          675  +<p>If the %Q formatting option is used instead of %q, like this:</p>
          676  +
          677  +<blockquote><pre>
          678  +sqlite_exec_printf(db,
          679  +  "INSERT INTO table1 VALUES(%Q)",
          680  +  0, 0, 0, zString);
          681  +</pre></blockquote>
          682  +
          683  +<p>Then the generated SQL will look like the following:</p>
          684  +
          685  +<blockquote><pre>
          686  +INSERT INTO table1 VALUES('Hi y''all')
          687  +</pre></blockquote>
          688  +
          689  +<p>If the value of the zString variable is NULL, the generated SQL
          690  +will look like the following:</p>
          691  +
          692  +<blockquote><pre>
          693  +INSERT INTO table1 VALUES(NULL)
          694  +</pre></blockquote>
          695  +
   670    696   
   671    697   <h2>Adding New SQL Functions</h2>
   672    698   
   673    699   <p>Beginning with version 2.4.0, SQLite allows the SQL language to be
   674    700   extended with new functions implemented as C code.  The following interface
   675    701   is used:
   676    702   </p>