📄 column_blob.html

📁 这是sqlite3.56的文档。拿来给大家阅读使用
💻 HTML
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Results Values From A Query</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>Results Values From A Query</h2><blockquote><pre>const void *sqlite3_column_blob(sqlite3_stmt*, int iCol);int sqlite3_column_bytes(sqlite3_stmt*, int iCol);int sqlite3_column_bytes16(sqlite3_stmt*, int iCol);double sqlite3_column_double(sqlite3_stmt*, int iCol);int sqlite3_column_int(sqlite3_stmt*, int iCol);sqlite3_int64 sqlite3_column_int64(sqlite3_stmt*, int iCol);const unsigned char *sqlite3_column_text(sqlite3_stmt*, int iCol);const void *sqlite3_column_text16(sqlite3_stmt*, int iCol);int sqlite3_column_type(sqlite3_stmt*, int iCol);sqlite3_value *sqlite3_column_value(sqlite3_stmt*, int iCol);</pre></blockquote><p>These routines form the "result set query" interface.</p><p>These routines return information abouta single column of the current result row of a query.  In everycase the first argument is a pointer to the<a href="../c3ref/stmt.html">prepared statement</a> that is beingevaluated (the <a href="../c3ref/stmt.html">sqlite3_stmt*</a> that was returned from<a href="../c3ref/prepare.html">sqlite3_prepare_v2()</a> or one of its variants) andthe second argument is the index of the column for which informationshould be returned.  The left-most column of the result sethas an index of 0.</p><p>If the SQL statement is not currently point to a valid row, or if thethe column index is out of range, the result is undefined.These routines may only be called when the most recent call to<a href="../c3ref/step.html">sqlite3_step()</a> has returned <a href="../c3ref/c_abort.html">SQLITE_ROW</a> and neither<a href="../c3ref/reset.html">sqlite3_reset()</a> nor <a href="../c3ref/finalize.html">sqlite3_finalize()</a> has been call subsequently.If any of these routines are called after <a href="../c3ref/reset.html">sqlite3_reset()</a> or<a href="../c3ref/finalize.html">sqlite3_finalize()</a> or after <a href="../c3ref/step.html">sqlite3_step()</a> has returnedsomething other than <a href="../c3ref/c_abort.html">SQLITE_ROW</a>, the results are undefined.If <a href="../c3ref/step.html">sqlite3_step()</a> or <a href="../c3ref/reset.html">sqlite3_reset()</a> or <a href="../c3ref/finalize.html">sqlite3_finalize()</a>are called from a different thread while any of these routinesare pending, then the results are undefined.</p><p>The sqlite3_column_type() routine returns<a href="../c3ref/c_blob.html">datatype code</a> for the initial data typeof the result column.  The returned value is one of <a href="../c3ref/c_blob.html">SQLITE_INTEGER</a>,<a href="../c3ref/c_blob.html">SQLITE_FLOAT</a>, <a href="../c3ref/c_blob.html">SQLITE_TEXT</a>, <a href="../c3ref/c_blob.html">SQLITE_BLOB</a>, or <a href="../c3ref/c_blob.html">SQLITE_NULL</a>.  The valuereturned by sqlite3_column_type() is only meaningful if no typeconversions have occurred as described below.  After a type conversion,the value returned by sqlite3_column_type() is undefined.  Futureversions of SQLite may change the behavior of sqlite3_column_type()following a type conversion.</p><p>If the result is a BLOB or UTF-8 string then the sqlite3_column_bytes()routine returns the number of bytes in that BLOB or string.If the result is a UTF-16 string, then sqlite3_column_bytes() convertsthe string to UTF-8 and then returns the number of bytes.If the result is a numeric value then sqlite3_column_bytes() uses<a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> to convert that value to a UTF-8 string and returnsthe number of bytes in that string.The value returned does not include the zero terminator at the endof the string.  For clarity: the value returned is the number ofbytes in the string, not the number of characters.</p><p>Strings returned by sqlite3_column_text() and sqlite3_column_text16(),even empty strings, are always zero terminated.  The returnvalue from sqlite3_column_blob() for a zero-length blob is an arbitrarypointer, possibly even a NULL pointer.</p><p>The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()but leaves the result in UTF-16 in native byte order instead of UTF-8.The zero terminator is not included in this count.</p><p>These routines attempt to convert the value where appropriate.  Forexample, if the internal representation is FLOAT and a text resultis requested, <a href="../c3ref/mprintf.html">sqlite3_snprintf()</a> is used internally to do the conversionautomatically.  The following table details the conversions thatare applied:</p><p><blockquote><table border="1"><tr><th> Internal<br>Type <th> Requested<br>Type <th>  Conversion</p><p><tr><td>  NULL    <td> INTEGER   <td> Result is 0<tr><td>  NULL    <td>  FLOAT    <td> Result is 0.0<tr><td>  NULL    <td>   TEXT    <td> Result is NULL pointer<tr><td>  NULL    <td>   BLOB    <td> Result is NULL pointer<tr><td> INTEGER  <td>  FLOAT    <td> Convert from integer to float<tr><td> INTEGER  <td>   TEXT    <td> ASCII rendering of the integer<tr><td> INTEGER  <td>   BLOB    <td> Same as for INTEGER->TEXT<tr><td>  FLOAT   <td> INTEGER   <td> Convert from float to integer<tr><td>  FLOAT   <td>   TEXT    <td> ASCII rendering of the float<tr><td>  FLOAT   <td>   BLOB    <td> Same as FLOAT->TEXT<tr><td>  TEXT    <td> INTEGER   <td> Use atoi()<tr><td>  TEXT    <td>  FLOAT    <td> Use atof()<tr><td>  TEXT    <td>   BLOB    <td> No change<tr><td>  BLOB    <td> INTEGER   <td> Convert to TEXT then use atoi()<tr><td>  BLOB    <td>  FLOAT    <td> Convert to TEXT then use atof()<tr><td>  BLOB    <td>   TEXT    <td> Add a zero terminator if needed</table></blockquote></p><p>The table above makes reference to standard C library functions atoi()and atof().  SQLite does not really use these functions.  It has itson equavalent internal routines.  The atoi() and atof() names areused in the table for brevity and because they are familiar to mostC programmers.</p><p>Note that when type conversions occur, pointers returned by priorcalls to sqlite3_column_blob(), sqlite3_column_text(), and/orsqlite3_column_text16() may be invalidated.Type conversions and pointer invalidations might occurin the following cases:</p><p><ul><li><p>  The initial content is a BLOB and sqlite3_column_text()or sqlite3_column_text16() is called.  A zero-terminator mightneed to be added to the string.</p></li></p><p><li><p>  The initial content is UTF-8 text and sqlite3_column_bytes16() orsqlite3_column_text16() is called.  The content must be convertedto UTF-16.</p></li></p><p><li><p>  The initial content is UTF-16 text and sqlite3_column_bytes() orsqlite3_column_text() is called.  The content must be convertedto UTF-8.</p></li></ul></p><p>Conversions between UTF-16be and UTF-16le are always done in place and donot invalidate a prior pointer, though of course the content of the bufferthat the prior pointer points to will have been modified.  Other kindsof conversion are done in place when it is possible, but sometime it isnot possible and in those cases prior pointers are invalidated.</p><p>The safest and easiest to remember policy is to invoke these routinesin one of the following ways:</p><p><ul><li>sqlite3_column_text() followed by sqlite3_column_bytes()</li><li>sqlite3_column_blob() followed by sqlite3_column_bytes()</li><li>sqlite3_column_text16() followed by sqlite3_column_bytes16()</li></ul></p><p>In other words, you should call sqlite3_column_text(), sqlite3_column_blob(),or sqlite3_column_text16() first to force the result into the desiredformat, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() tofind the size of the result.  Do not mix call to sqlite3_column_text() orsqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do notmix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().</p><p>The pointers returned are valid until a type conversion occurs asdescribed above, or until <a href="../c3ref/step.html">sqlite3_step()</a> or <a href="../c3ref/reset.html">sqlite3_reset()</a> or<a href="../c3ref/finalize.html">sqlite3_finalize()</a> is called.  The memory space used to hold stringsand blobs is freed automatically.  Do <b>not</b> pass the pointers returned<a href="../c3ref/column_blob.html">sqlite3_column_blob()</a>, <a href="../c3ref/column_blob.html">sqlite3_column_text()</a>, etc. into<a href="../c3ref/free.html">sqlite3_free()</a>.</p><p>If a memory allocation error occurs during the evaluation of anyof these routines, a default value is returned.  The default valueis either the integer 0, the floating point number 0.0, or a NULLpointer.  Subsequent calls to <a href="../c3ref/errcode.html">sqlite3_errcode()</a> will return<a href="../c3ref/c_abort.html">SQLITE_NOMEM</a>.</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">F13803</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_blob(S,N)</a> interface converts theNth column in the current row of the result set for<a href="../c3ref/stmt.html">prepared statement</a> S into a blob and then returns apointer to the converted value.</td></tr><tr><td valign="top">F13806</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_bytes(S,N)</a> interface returns thenumber of bytes in the blob or string (exclusive of thezero terminator on the string) that was returned by themost recent call to <a href="../c3ref/column_blob.html">sqlite3_column_blob(S,N)</a> or<a href="../c3ref/column_blob.html">sqlite3_column_text(S,N)</a>.</td></tr><tr><td valign="top">F13809</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_bytes16(S,N)</a> interface returns thenumber of bytes in the string (exclusive of thezero terminator on the string) that was returned by themost recent call to <a href="../c3ref/column_blob.html">sqlite3_column_text16(S,N)</a>.</td></tr><tr><td valign="top">F13812</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_double(S,N)</a> interface converts theNth column in the current row of the result set for<a href="../c3ref/stmt.html">prepared statement</a> S into a floating point value andreturns a copy of that value.</td></tr><tr><td valign="top">F13815</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_int(S,N)</a> interface converts theNth column in the current row of the result set for<a href="../c3ref/stmt.html">prepared statement</a> S into a 32-bit signed integer andreturns a copy of that integer.</td></tr><tr><td valign="top">F13818</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_int64(S,N)</a> interface converts theNth column in the current row of the result set for<a href="../c3ref/stmt.html">prepared statement</a> S into a 64-bit signed integer andreturns a copy of that integer.</td></tr><tr><td valign="top">F13821</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_text(S,N)</a> interface converts theNth column in the current row of the result set for<a href="../c3ref/stmt.html">prepared statement</a> S into a zero-terminated UTF-8string and returns a pointer to that string.</td></tr><tr><td valign="top">F13824</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_text16(S,N)</a> interface converts theNth column in the current row of the result set for<a href="../c3ref/stmt.html">prepared statement</a> S into a zero-terminated 2-bytealigned UTF-16 native byte orderstring and returns a pointer to that string.</td></tr><tr><td valign="top">F13827</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_type(S,N)</a> interface returnsone of <a href="../c3ref/c_blob.html">SQLITE_NULL</a>, <a href="../c3ref/c_blob.html">SQLITE_INTEGER</a>, <a href="../c3ref/c_blob.html">SQLITE_FLOAT</a>,<a href="../c3ref/c_blob.html">SQLITE_TEXT</a>, or <a href="../c3ref/c_blob.html">SQLITE_BLOB</a> as appropriate forthe Nth column in the current row of the result set for<a href="../c3ref/stmt.html">prepared statement</a> S.</td></tr><tr><td valign="top">F13830</td> <td valign="top">The <a href="../c3ref/column_blob.html">sqlite3_column_value(S,N)</a> interface returns apointer to the <a href="../c3ref/value.html">sqlite3_value</a> object that for theNth column in the current row of the result set for<a href="../c3ref/stmt.html">prepared statement</a> S.</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/01/31 20:37:13 UTC</i></small></div></body></html>
⌨️ 快捷键说明

复制代码 Ctrl + C
搜索代码 Ctrl + F
全屏模式 F11
切换主题 Ctrl + Shift + D
显示快捷键 ?
增大字号 Ctrl + =
减小字号 Ctrl + -