/ Check-in [99eec556]
Login

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

Overview
Comment:Remove a lot of the text describing extended format options from the documentation on sqlite3_mprintf() and friends, since that information is now covered by the separate printf.html document. Provide links to that other document. No changes to code.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA3-256:99eec556f065ad19548e48d1f4ae0a3767b4e82e1c83fa2365062e3c5e0071fb
User & Date: drh 2018-02-20 13:46:20
Context
2018-02-20
15:23
Optimize calls to sqlite3_mprintf("%z...") so that they attempt to append text onto the end of the existing memory allocation rather than reallocating and copying. check-in: 4bc8a48e user: drh tags: trunk
13:46
Remove a lot of the text describing extended format options from the documentation on sqlite3_mprintf() and friends, since that information is now covered by the separate printf.html document. Provide links to that other document. No changes to code. check-in: 99eec556 user: drh tags: trunk
2018-02-19
22:46
Enhance the string formatter (used by printf()) so that the width and precision of string substitution operators refer to characters instead of bytes when the alternate-form-2 flag ("!") is used. Also fix the %c substition to always work within unicode, regardless of the alternate-form-2 flag. check-in: c883c4d3 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  2492   2492   void sqlite3_free_table(char **result);
  2493   2493   
  2494   2494   /*
  2495   2495   ** CAPI3REF: Formatted String Printing Functions
  2496   2496   **
  2497   2497   ** These routines are work-alikes of the "printf()" family of functions
  2498   2498   ** from the standard C library.
  2499         -** These routines understand most of the common K&R formatting options,
  2500         -** plus some additional non-standard formats, detailed below.
  2501         -** Note that some of the more obscure formatting options from recent
  2502         -** C-library standards are omitted from this implementation.
         2499  +** These routines understand most of the common formatting options from
         2500  +** the standard library printf() 
         2501  +** plus some additional non-standard formats ([%q], [%Q], [%w], and [%z]).
         2502  +** See the [built-in printf()] documentation for details.
  2503   2503   **
  2504   2504   ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  2505         -** results into memory obtained from [sqlite3_malloc()].
         2505  +** results into memory obtained from [sqlite3_malloc64()].
  2506   2506   ** The strings returned by these two routines should be
  2507   2507   ** released by [sqlite3_free()].  ^Both routines return a
  2508         -** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
         2508  +** NULL pointer if [sqlite3_malloc64()] is unable to allocate enough
  2509   2509   ** memory to hold the resulting string.
  2510   2510   **
  2511   2511   ** ^(The sqlite3_snprintf() routine is similar to "snprintf()" from
  2512   2512   ** the standard C library.  The result is written into the
  2513   2513   ** buffer supplied as the second parameter whose size is given by
  2514   2514   ** the first parameter. Note that the order of the
  2515   2515   ** first two parameters is reversed from snprintf().)^  This is an
................................................................................
  2525   2525   ** guarantees that the buffer is always zero-terminated.  ^The first
  2526   2526   ** parameter "n" is the total size of the buffer, including space for
  2527   2527   ** the zero terminator.  So the longest string that can be completely
  2528   2528   ** written will be n-1 characters.
  2529   2529   **
  2530   2530   ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
  2531   2531   **
  2532         -** These routines all implement some additional formatting
  2533         -** options that are useful for constructing SQL statements.
  2534         -** All of the usual printf() formatting options apply.  In addition, there
  2535         -** is are "%q", "%Q", "%w" and "%z" options.
  2536         -**
  2537         -** ^(The %q option works like %s in that it substitutes a nul-terminated
  2538         -** string from the argument list.  But %q also doubles every '\'' character.
  2539         -** %q is designed for use inside a string literal.)^  By doubling each '\''
  2540         -** character it escapes that character and allows it to be inserted into
  2541         -** the string.
  2542         -**
  2543         -** For example, assume the string variable zText contains text as follows:
  2544         -**
  2545         -** <blockquote><pre>
  2546         -**  char *zText = "It's a happy day!";
  2547         -** </pre></blockquote>
  2548         -**
  2549         -** One can use this text in an SQL statement as follows:
  2550         -**
  2551         -** <blockquote><pre>
  2552         -**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);
  2553         -**  sqlite3_exec(db, zSQL, 0, 0, 0);
  2554         -**  sqlite3_free(zSQL);
  2555         -** </pre></blockquote>
  2556         -**
  2557         -** Because the %q format string is used, the '\'' character in zText
  2558         -** is escaped and the SQL generated is as follows:
  2559         -**
  2560         -** <blockquote><pre>
  2561         -**  INSERT INTO table1 VALUES('It''s a happy day!')
  2562         -** </pre></blockquote>
  2563         -**
  2564         -** This is correct.  Had we used %s instead of %q, the generated SQL
  2565         -** would have looked like this:
  2566         -**
  2567         -** <blockquote><pre>
  2568         -**  INSERT INTO table1 VALUES('It's a happy day!');
  2569         -** </pre></blockquote>
  2570         -**
  2571         -** This second example is an SQL syntax error.  As a general rule you should
  2572         -** always use %q instead of %s when inserting text into a string literal.
  2573         -**
  2574         -** ^(The %Q option works like %q except it also adds single quotes around
  2575         -** the outside of the total string.  Additionally, if the parameter in the
  2576         -** argument list is a NULL pointer, %Q substitutes the text "NULL" (without
  2577         -** single quotes).)^  So, for example, one could say:
  2578         -**
  2579         -** <blockquote><pre>
  2580         -**  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
  2581         -**  sqlite3_exec(db, zSQL, 0, 0, 0);
  2582         -**  sqlite3_free(zSQL);
  2583         -** </pre></blockquote>
  2584         -**
  2585         -** The code above will render a correct SQL statement in the zSQL
  2586         -** variable even if the zText variable is a NULL pointer.
  2587         -**
  2588         -** ^(The "%w" formatting option is like "%q" except that it expects to
  2589         -** be contained within double-quotes instead of single quotes, and it
  2590         -** escapes the double-quote character instead of the single-quote
  2591         -** character.)^  The "%w" formatting option is intended for safely inserting
  2592         -** table and column names into a constructed SQL statement.
  2593         -**
  2594         -** ^(The "%z" formatting option works like "%s" but with the
  2595         -** addition that after the string has been read and copied into
  2596         -** the result, [sqlite3_free()] is called on the input string.)^
         2532  +** See also:  [built-in printf()], [printf() SQL function]
  2597   2533   */
  2598   2534   char *sqlite3_mprintf(const char*,...);
  2599   2535   char *sqlite3_vmprintf(const char*, va_list);
  2600   2536   char *sqlite3_snprintf(int,char*,const char*, ...);
  2601   2537   char *sqlite3_vsnprintf(int,char*,const char*, va_list);
  2602   2538   
  2603   2539   /*