📄 mprintf.html
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Formatted String Printing Functions</title><style type="text/css">body { margin: auto; font-family: "Verdana" "sans-serif"; padding: 8px 1%;}a { color: #45735f }a:visited { color: #734559 }.logo { position:absolute; margin:3px; }.tagline { float:right; text-align:right; font-style:italic; width:240px; margin:12px; margin-top:58px;}.toolbar { font-variant: small-caps; text-align: center; line-height: 1.6em; margin: 0; padding:1px 8px;}.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }.toolbar a:visited { color: white; }.toolbar a:hover { color: #80a796; background: white; }.content { margin: 5%; }.content dt { font-weight:bold; }.content dd { margin-bottom: 25px; margin-left:20%; }.content ul { padding:0px; padding-left: 15px; margin:0px; }/* rounded corners */.se { background: url(../images/se.png) 100% 100% no-repeat #80a796}.sw { background: url(../images/sw.png) 0% 100% no-repeat }.ne { background: url(../images/ne.png) 100% 0% no-repeat }.nw { background: url(../images/nw.png) 0% 0% no-repeat }</style><meta http-equiv="content-type" content="text/html; charset=UTF-8"> </head><body><div><!-- container div to satisfy validator --><a href="../index.html"><img class="logo" src="../images/SQLite.gif" alt="SQLite Logo" border="0"></a><div><!-- IE hack to prevent disappearing logo--></div><div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div><table width=100% style="clear:both"><tr><td> <div class="se"><div class="sw"><div class="ne"><div class="nw"> <div class="toolbar"> <a href="../about.html">About</a> <a href="../sitemap.html">Sitemap</a> <a href="../docs.html">Documentation</a> <a href="../download.html">Download</a> <a href="../copyright.html">License</a> <a href="../news.html">News</a> <a href="http://www.sqlite.org/cvstrac/index">Developers</a> <a href="../support.html">Support</a> </div></div></div></div></div></td></tr></table> <a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Formatted String Printing Functions</h2><blockquote><pre>char *sqlite3_mprintf(const char*,...);char *sqlite3_vmprintf(const char*, va_list);char *sqlite3_snprintf(int,char*,const char*, ...);</pre></blockquote><p>These routines are workalikes of the "printf()" family of functionsfrom the standard C library.</p><p>The sqlite3_mprintf() and sqlite3_vmprintf() routines write theirresults into memory obtained from <a href="../c3ref/free.html">sqlite3_malloc()</a>.The strings returned by these two routines should bereleased by <a href="../c3ref/free.html">sqlite3_free()</a>. Both routines return aNULL pointer if <a href="../c3ref/free.html">sqlite3_malloc()</a> is unable to allocate enoughmemory to hold the resulting string.</p><p>In 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.</p><p>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.</p><p>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.</p><p>The %q option works like %s in that it substitutes a null-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.</p><p>For example, so some string variable contains text as follows:</p><p><blockquote><pre>char *zText = "It's a happy day!";</pre></blockquote></p><p>One can use this text in an SQL statement as follows:</p><p><blockquote><pre>char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES('%q')", zText);sqlite3_exec(db, zSQL, 0, 0, 0);sqlite3_free(zSQL);</pre></blockquote></p><p>Because the %q format string is used, the '\'' character in zTextis escaped and the SQL generated is as follows:</p><p><blockquote><pre>INSERT INTO table1 VALUES('It''s a happy day!')</pre></blockquote></p><p>This is correct. Had we used %s instead of %q, the generated SQLwould have looked like this:</p><p><blockquote><pre>INSERT INTO table1 VALUES('It's a happy day!');</pre></blockquote></p><p>This second example is an SQL syntax error. As a general rule youshould always use %q instead of %s when inserting text into a stringliteral.</p><p>The %Q option works like %q except it also adds single quotes aroundthe outside of the total string. Or if the parameter in the argumentlist is a NULL pointer, %Q substitutes the text "NULL" (without singlequotes) in place of the %Q option. So, for example, one could say:</p><p><blockquote><pre>char *zSQL = sqlite3_mprintf("INSERT INTO table VALUES(%Q)", zText);sqlite3_exec(db, zSQL, 0, 0, 0);sqlite3_free(zSQL);</pre></blockquote></p><p>The code above will render a correct SQL statement in the zSQLvariable even if the zText variable is a NULL pointer.</p><p>The "%z" formatting option works exactly like "%s" with theaddition that after the string has been read and copied intothe result, <a href="../c3ref/free.html">sqlite3_free()</a> is called on the input string.</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">F17403</td> <td valign="top">The <a href="../c3ref/mprintf.html">sqlite3_mprintf()</a> and <a href="../c3ref/mprintf.html">sqlite3_vmprintf()</a> interfacesreturn either pointers to zero-terminated UTF-8 strings held inmemory obtained from <a href="../c3ref/free.html">sqlite3_malloc()</a> or NULL pointers ifa call to <a href="../c3ref/free.html">sqlite3_malloc()</a> fails.</td></tr><tr><td valign="top">F17406</td> <td valign="top">The <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> interface writes a zero-terminatedUTF-8 string into the buffer pointed to by the second parameterprovided that the first parameter is greater than zero.</td></tr><tr><td valign="top">F17407</td> <td valign="top">The <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> interface does not writes slots ofits output buffer (the second parameter) outside the rangeof 0 through N-1 (where N is the first parameter)regardless of the length of the stringrequested by the format specification.</td></tr></table></p><p>See also lists of <a href="objlist.html">Objects</a>, <a href="constlist.html">Constants</a>, and <a href="funclist.html">Functions</a>.</p><hr><small><i>This page last modified 2008/05/12 13:08:44 UTC</i></small></div></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -