column_blob.html

嵌入式数据库sqlite 3.5.9的文档

<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 its
on equavalent internal routines.  The atoi() and atof() names are
used in the table for brevity and because they are familiar to most
C programmers.</p>

<p>Note that when type conversions occur, pointers returned by prior
calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
sqlite3_column_text16() may be invalidated.
Type conversions and pointer invalidations might occur
in 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 might
need to be added to the string.</p></li></p>

<p><li><p>  The initial content is UTF-8 text and sqlite3_column_bytes16() or
sqlite3_column_text16() is called.  The content must be converted
to UTF-16.</p></li></p>

<p><li><p>  The initial content is UTF-16 text and sqlite3_column_bytes() or
sqlite3_column_text() is called.  The content must be converted
to UTF-8.</p></li>
</ul></p>

<p>Conversions between UTF-16be and UTF-16le are always done in place and do
not invalidate a prior pointer, though of course the content of the buffer
that the prior pointer points to will have been modified.  Other kinds
of conversion are done in place when it is possible, but sometime it is
not possible and in those cases prior pointers are invalidated.</p>

<p>The safest and easiest to remember policy is to invoke these routines
in 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 desired
format, then invoke sqlite3_column_bytes() or sqlite3_column_bytes16() to
find the size of the result.  Do not mix call to sqlite3_column_text() or
sqlite3_column_blob() with calls to sqlite3_column_bytes16().  And do not
mix calls to sqlite3_column_text16() with calls to sqlite3_column_bytes().</p>

<p>The pointers returned are valid until a type conversion occurs as
described 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 strings
and 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 any
of these routines, a default value is returned.  The default value
is either the integer 0, the floating point number 0.0, or a NULL
pointer.  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 the
Nth 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 a
pointer 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 the
number of bytes in the blob or string (exclusive of the
zero terminator on the string) that was returned by the
most 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 the
number of bytes in the string (exclusive of the
zero terminator on the string) that was returned by the
most 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 the
Nth column in the current row of the result set for

<a href="../c3ref/stmt.html">prepared statement</a> S into a floating point value and
returns 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 the
Nth 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 and
returns the lower 32 bits 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 the
Nth 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 and
returns 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 the
Nth column in the current row of the result set for

<a href="../c3ref/stmt.html">prepared statement</a> S into a zero-terminated UTF-8
string 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 the
Nth column in the current row of the result set for

<a href="../c3ref/stmt.html">prepared statement</a> S into a zero-terminated 2-byte
aligned UTF-16 native byte order
string 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 returns
one 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 for
the 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 a
pointer to an 
<a href="../c3ref/value.html">unprotected sqlite3_value</a> object for the
Nth 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/05/12 13:08:44 UTC
</i></small></div></body></html>