Formatted String Printing Functions

char *sqlite3_mprintf(const char*,...);
char *sqlite3_vmprintf(const char*,va_list);
char *sqlite3_snprintf(int,char*,const char*,...);
char *sqlite3_vsnprintf(int,va_list);

These routines are work-alikes of the "printf()" family of functionsfrom the standard C library.

The sqlite3_mprintf() and sqlite3_vmprintf() routines write theirresults into memory obtained from sqlite3_malloc().The strings returned by these two routines should bereleased by sqlite3_free(). Both routines return aNULL pointer if sqlite3_malloc() is unable to allocate enoughmemory to hold the resulting string.

The sqlite3_snprintf() routine is similar to "snprintf()" fromthe standard C library. The result is written into thebuffer supplied as the second parameter whose size is given bythe first parameter. Note that the order of thefirst two parameters is reversed from snprintf(). This is anhistorical accident that cannot be fixed without breakingbackwards compatibility. Note also that sqlite3_snprintf()returns a pointer to its buffer instead of the number ofcharacters actually written into the buffer. We admit thatthe number of characters written would be a more useful returnvalue but we cannot change the implementation of sqlite3_snprintf()now without breaking compatibility.

As long as the buffer size is greater than zero,sqlite3_snprintf()guarantees that the buffer is always zero-terminated. The firstparameter "n" is the total size of the buffer,including space forthe zero terminator. So the longest string that can be completelywritten will be n-1 characters.

The sqlite3_vsnprintf() routine is a varargs version of sqlite3_snprintf().

These routines all implement some additional formattingoptions that are useful for constructing sql statements.All of the usual printf() formatting options apply. In addition,thereis are "%q","%Q",and "%z" options.

The %q option works like %s in that it substitutes a nul-terminatedstring from the argument list. But %q also doubles every '\'' character.%q is designed for use inside a string literal. By doubling each '\''character it escapes that character and allows it to be inserted intothe string.

For example,assume the string variable zText contains text as follows:

char *zText = "It's a happy day!";

One can use this text in an sql statement as follows:

char *zsql = sqlite3_mprintf("INSERT INTO table VALUES('%q')",zText);
sqlite3_exec(db,zsql,0);
sqlite3_free(zsql);

Because the %q format string is used,the '\'' character in zTextis escaped and the sql generated is as follows:

INSERT INTO table1 VALUES('It''s a happy day!')

This is correct. Had we used %s instead of %q,the generated sqlwould have looked like this:

INSERT INTO table1 VALUES('It's a happy day!');

This second example is an sql Syntax error. As a general rule you shouldalways use %q instead of %s when inserting text into a string literal.

The %Q option works like %q except it also adds single quotes aroundthe outside of the total string. Additionally,if the parameter in theargument list is a NULL pointer,%Q substitutes the text "NULL" (withoutsingle quotes). So,for example,one could say:

char *zsql = sqlite3_mprintf("INSERT INTO table VALUES(%Q)",0);
sqlite3_free(zsql);

The code above will render a correct sql statement in the zsqlvariable even if the zText variable is a NULL pointer.

The "%z" formatting option works like "%s" but with theaddition that after the string has been read and copied intothe result,sqlite3_free() is called on the input string.

See also lists of Objects,Constants,and Functions.