/ Check-in [f8917ba4]
Login

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

Overview
Comment:Update document on sqlite3_mprintf() and related functions. Discuss the %w format and point out that obscure ANSI-C formats are not supported. No changes to code.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: f8917ba4d917bc762b3b252466ab72a8a70dc0d8
User & Date: drh 2015-02-21 15:42:57
Context
2015-02-24
20:04
Make sure partial indexes are not qualified incorrectly by a constraint that is inside the ON clause of a LEFT JOIN. Fix for ticket [2326c258d02ead33]. check-in: 491cfe9b user: drh tags: trunk
16:05
Make sure partial automatic indexes are not based on terms in the ON clause of a LEFT JOIN. Fix for ticket [2326c258d02ead3]. UPDATE: This fix does not work where the partial index is a named index. check-in: c0f4e308 user: drh tags: tkt-2326c258
2015-02-23
16:17
Merge latest trunk changes with this branch. check-in: e5ca79d2 user: dan tags: ota-update
2015-02-21
15:42
Update document on sqlite3_mprintf() and related functions. Discuss the %w format and point out that obscure ANSI-C formats are not supported. No changes to code. check-in: f8917ba4 user: drh tags: trunk
00:56
Fix a compiler warning associated with USE_PREAD64. check-in: c299e55a user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

  2228   2228   void sqlite3_free_table(char **result);
  2229   2229   
  2230   2230   /*
  2231   2231   ** CAPI3REF: Formatted String Printing Functions
  2232   2232   **
  2233   2233   ** These routines are work-alikes of the "printf()" family of functions
  2234   2234   ** from the standard C library.
         2235  +** These routines understand most of the common K&R formatting options,
         2236  +** plus some additional non-standard formats, detailed below.
         2237  +** Note that some of the more obscure formatting options from recent
         2238  +** C-library standards are omitted from this implementation.
  2235   2239   **
  2236   2240   ** ^The sqlite3_mprintf() and sqlite3_vmprintf() routines write their
  2237   2241   ** results into memory obtained from [sqlite3_malloc()].
  2238   2242   ** The strings returned by these two routines should be
  2239   2243   ** released by [sqlite3_free()].  ^Both routines return a
  2240   2244   ** NULL pointer if [sqlite3_malloc()] is unable to allocate enough
  2241   2245   ** memory to hold the resulting string.
................................................................................
  2260   2264   ** written will be n-1 characters.
  2261   2265   **
  2262   2266   ** ^The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().
  2263   2267   **
  2264   2268   ** These routines all implement some additional formatting
  2265   2269   ** options that are useful for constructing SQL statements.
  2266   2270   ** All of the usual printf() formatting options apply.  In addition, there
  2267         -** is are "%q", "%Q", and "%z" options.
         2271  +** is are "%q", "%Q", "%w" and "%z" options.
  2268   2272   **
  2269   2273   ** ^(The %q option works like %s in that it substitutes a nul-terminated
  2270   2274   ** string from the argument list.  But %q also doubles every '\'' character.
  2271   2275   ** %q is designed for use inside a string literal.)^  By doubling each '\''
  2272   2276   ** character it escapes that character and allows it to be inserted into
  2273   2277   ** the string.
  2274   2278   **
................................................................................
  2312   2316   **  char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);
  2313   2317   **  sqlite3_exec(db, zSQL, 0, 0, 0);
  2314   2318   **  sqlite3_free(zSQL);
  2315   2319   ** </pre></blockquote>
  2316   2320   **
  2317   2321   ** The code above will render a correct SQL statement in the zSQL
  2318   2322   ** variable even if the zText variable is a NULL pointer.
         2323  +**
         2324  +** ^(The "%w" formatting option is like "%q" except that it expects to
         2325  +** be contained within double-quotes instead of single quotes, and it
         2326  +** escapes the double-quote character instead of the single-quote
         2327  +** character.)^  The "%w" formatting option is intended for safely inserting
         2328  +** table and column names into a constructed SQL statement.
  2319   2329   **
  2320   2330   ** ^(The "%z" formatting option works like "%s" but with the
  2321   2331   ** addition that after the string has been read and copied into
  2322   2332   ** the result, [sqlite3_free()] is called on the input string.)^
  2323   2333   */
  2324   2334   char *sqlite3_mprintf(const char*,...);
  2325   2335   char *sqlite3_vmprintf(const char*, va_list);