Capi3ref: formatted string printing functions
**
** These routines are work-alikes of the "printf ()" family of functions
** From the Standard C library.
**
** ^ The sqlite3_mprintf () and sqlite3_vmprintf () routines write their
** Results into memory obtained from [sqlite3_malloc ()].
** The strings returned by these two routines shocould be
** Released by [sqlite3_free ()]. ^ both routines return
** NULL pointer if [sqlite3_malloc ()] is unable to allocate enough
** Memory to hold the resulting string.
**
** ^ (In sqlite3_snprintf () routine is similar to "snprintf ()" from
** The Standard C library. The result is written into
** Buffer supplied as the second parameter whose size is given
** The first parameter. Note that the order of
** First two parameters is reversed from snprintf ().) ^ this is
** Historical accident that cannot be fixed without breaking
** Backwards compatibility. ^ (note also that sqlite3_snprintf ()
** Returns a pointer to its buffer instead of the number
** Characters actually written into the buffer.) ^ We admit that
** The number of characters written wocould be a more useful return
** Value 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 first
** Parameter "N" is the total size of the buffer, including space
** The zero Terminator. So the longest string that can be completely
** Written will be n-1 characters.
**
** These routines all implement some additional formatting
** Options that are useful for constructing SQL statements.
** All of the usual printf () Formatting options apply. In addition, there
** Is are "% Q", "% Q", and "% Z" options.
**
** ^ (The % Q option works like % s in that it substitutes a null-terminated
** String 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
** The string.
**
** For example, assume the string variable ztext contains text as follows:
**
** <BLOCKQUOTE> <PRE>
** Char * ztext = "it's a happy day! ";
** </PRE> </BLOCKQUOTE>
**
** One can use this text in an SQL statement as follows:
**
** <BLOCKQUOTE> <PRE>
** Char * zsql = sqlite3_mprintf ("insert into table values ('% Q')", ztext );
** Sqlite3_exec (dB, zsql, 0, 0, 0 );
** Sqlite3_free (zsql );
** </PRE> </BLOCKQUOTE>
**
** Because the % Q Format String is used, the '\' character in ztext
** Is escaped and the SQL generated is as follows:
**
** <BLOCKQUOTE> <PRE>
** Insert into Table1 values ('it''s a happy day! ')
** </PRE> </BLOCKQUOTE>
**
** This is correct. Had we used % s instead of % Q, the generated SQL
** Wocould have looked like this:
**
** <BLOCKQUOTE> <PRE>
** Insert into Table1 values ('It's a happy day! ');
** </PRE> </BLOCKQUOTE>
**
** This second example is an SQL syntax error. As a general rule you shoshould
** Always use % Q instead of % s when inserting text into a string literal.
**
** ^ (The % Q option works like % Q should t it also adds single quotes around und
** The outside of the total string. Additionally, if the parameter in
** Argument list is a null pointer, % Q substitutes the text "null" (
** Single quotes).) ^ so, for example, one cocould say:
**
** <BLOCKQUOTE> <PRE>
** Char * zsql = sqlite3_mprintf ("insert into table values (% q)", ztext );
** Sqlite3_exec (dB, zsql, 0, 0, 0 );
** Sqlite3_free (zsql );
** </PRE> </BLOCKQUOTE>
**
** The code above will render a correct SQL statement in the zsql
** Variable even if the ztext variable is a null pointer.
**
** ^ (The "% Z" formatting option works like "% s" but with
** Addition that after the string has been read and copied
** The result, [sqlite3_free ()] is called on the input string.) ^
*/
Sqlite_api char * sqlite3_mprintf (const char *,...);
Sqlite_api char * sqlite3_vmprintf (const char *, va_list );
Sqlite_api char * sqlite3_snprintf (INT, char *, const char *,...);