Debian Codegraph @

www/c3ref/value_blob.html

raw
1 <!DOCTYPE html>
2 <html><head>
3 <meta name="viewport" content="width=device-width, initial-scale=1.0">
4 <meta http-equiv="content-type" content="text/html; charset=UTF-8">
5 <link href="../sqlite.css" rel="stylesheet">
6 <title>Obtaining SQL Values</title>
7 <!-- path=../ -->
8 </head>
9 <body>
10 <div class=nosearch>
11 <a href="../index.html">
12 <img class="logo" src="../images/sqlite370_banner.svg" alt="SQLite" border="0">
13 </a>
14 <div><!-- IE hack to prevent disappearing logo --></div>
15 <div class="tagline desktoponly">
16 Small. Fast. Reliable.<br>Choose any three.
17 </div>
18 <div class="menu mainmenu">
19 <ul>
20 <li><a href="../index.html">Home</a>
21 <li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
22 <li class='wideonly'><a href='../about.html'>About</a>
23 <li class='desktoponly'><a href="../docs.html">Documentation</a>
24 <li class='desktoponly'><a href="../download.html">Download</a>
25 <li class='wideonly'><a href='../copyright.html'>License</a>
26 <li class='desktoponly'><a href="../support.html">Support</a>
27 <li class='desktoponly'><a href="../prosupport.html">Purchase</a>
28 <li class='search' id='search_menubutton'>
29 <a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
30 </ul>
31 </div>
32 <div class="menu submenu" id="submenu">
33 <ul>
34 <li><a href='../about.html'>About</a>
35 <li><a href='../docs.html'>Documentation</a>
36 <li><a href='../download.html'>Download</a>
37 <li><a href='../support.html'>Support</a>
38 <li><a href='../prosupport.html'>Purchase</a>
39 </ul>
40 </div>
41 <div class="searchmenu" id="searchmenu">
42 <form method="GET" action="../search">
43 <select name="s" id="searchtype">
44 <option value="d">Search Documentation</option>
45 <option value="c">Search Changelog</option>
46 </select>
47 <input type="text" name="q" id="searchbox" value="">
48 <input type="submit" value="Go">
49 </form>
50 </div>
51 </div>
52 <script>
53 function toggle_div(nm) {
54 var w = document.getElementById(nm);
55 if( w.style.display=="block" ){
56 w.style.display = "none";
57 }else{
58 w.style.display = "block";
59 }
60 }
61 function toggle_search() {
62 var w = document.getElementById("searchmenu");
63 if( w.style.display=="block" ){
64 w.style.display = "none";
65 } else {
66 w.style.display = "block";
67 setTimeout(function(){
68 document.getElementById("searchbox").focus()
69 }, 30);
70 }
71 }
72 function div_off(nm){document.getElementById(nm).style.display="none";}
73 window.onbeforeunload = function(e){div_off("submenu");}
74 /* Disable the Search feature if we are not operating from CGI, since */
75 /* Search is accomplished using CGI and will not work without it. */
76 if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
77 document.getElementById("search_menubutton").style.display = "none";
78 }
79 /* Used by the Hide/Show button beside syntax diagrams, to toggle the */
80 function hideorshow(btn,obj){
81 var x = document.getElementById(obj);
82 var b = document.getElementById(btn);
83 if( x.style.display!='none' ){
84 x.style.display = 'none';
85 b.innerHTML='show';
86 }else{
87 x.style.display = '';
88 b.innerHTML='hide';
89 }
90 return false;
91 }
92 var antiRobot = 0;
93 function antiRobotGo(){
94 if( antiRobot!=3 ) return;
95 antiRobot = 7;
96 var j = document.getElementById("mtimelink");
97 if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
98 }
99 function antiRobotDefense(){
100 document.body.onmousedown=function(){
101 antiRobot |= 2;
102 antiRobotGo();
103 document.body.onmousedown=null;
104 }
105 document.body.onmousemove=function(){
106 antiRobot |= 2;
107 antiRobotGo();
108 document.body.onmousemove=null;
109 }
110 setTimeout(function(){
111 antiRobot |= 1;
112 antiRobotGo();
113 }, 100)
114 antiRobotGo();
115 }
116 antiRobotDefense();
117 </script>
118 <!-- keywords: sqlite3_value_blob sqlite3_value_bytes sqlite3_value_bytes16 sqlite3_value_double sqlite3_value_frombind sqlite3_value_int sqlite3_value_int64 sqlite3_value_nochange sqlite3_value_numeric_type sqlite3_value_pointer sqlite3_value_text sqlite3_value_text16 sqlite3_value_text16be sqlite3_value_text16le sqlite3_value_type -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Obtaining SQL Values</h2>
122 </div>
123 <blockquote><pre>
124 const void *sqlite3_value_blob(sqlite3_value*);
125 double sqlite3_value_double(sqlite3_value*);
126 int sqlite3_value_int(sqlite3_value*);
127 sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
128 void *sqlite3_value_pointer(sqlite3_value*, const char*);
129 const unsigned char *sqlite3_value_text(sqlite3_value*);
130 const void *sqlite3_value_text16(sqlite3_value*);
131 const void *sqlite3_value_text16le(sqlite3_value*);
132 const void *sqlite3_value_text16be(sqlite3_value*);
133 int sqlite3_value_bytes(sqlite3_value*);
134 int sqlite3_value_bytes16(sqlite3_value*);
135 int sqlite3_value_type(sqlite3_value*);
136 int sqlite3_value_numeric_type(sqlite3_value*);
137 int sqlite3_value_nochange(sqlite3_value*);
138 int sqlite3_value_frombind(sqlite3_value*);
139 </pre></blockquote>
140 <p>
141 <b>Summary:</b>
142 <blockquote><table border=0 cellpadding=0 cellspacing=0>
143 <tr><td><b>sqlite3_value_blob</b><td>&rarr;<td>BLOB value
144 <tr><td><b>sqlite3_value_double</b><td>&rarr;<td>REAL value
145 <tr><td><b>sqlite3_value_int</b><td>&rarr;<td>32-bit INTEGER value
146 <tr><td><b>sqlite3_value_int64</b><td>&rarr;<td>64-bit INTEGER value
147 <tr><td><b>sqlite3_value_pointer</b><td>&rarr;<td>Pointer value
148 <tr><td><b>sqlite3_value_text</b><td>&rarr;<td>UTF-8 TEXT value
149 <tr><td><b>sqlite3_value_text16</b><td>&rarr;<td>UTF-16 TEXT value in
150 the native byteorder
151 <tr><td><b>sqlite3_value_text16be</b><td>&rarr;<td>UTF-16be TEXT value
152 <tr><td><b>sqlite3_value_text16le</b><td>&rarr;<td>UTF-16le TEXT value
153 <tr><td>&nbsp;<td>&nbsp;<td>&nbsp;
154 <tr><td><b>sqlite3_value_bytes</b><td>&rarr;<td>Size of a BLOB
155 or a UTF-8 TEXT in bytes
156 <tr><td><b>sqlite3_value_bytes16&nbsp;&nbsp;</b>
157 <td>&rarr;&nbsp;&nbsp;<td>Size of UTF-16
158 TEXT in bytes
159 <tr><td><b>sqlite3_value_type</b><td>&rarr;<td>Default
160 datatype of the value
161 <tr><td><b>sqlite3_value_numeric_type&nbsp;&nbsp;</b>
162 <td>&rarr;&nbsp;&nbsp;<td>Best numeric datatype of the value
163 <tr><td><b>sqlite3_value_nochange&nbsp;&nbsp;</b>
164 <td>&rarr;&nbsp;&nbsp;<td>True if the column is unchanged in an UPDATE
165 against a virtual table.
166 <tr><td><b>sqlite3_value_frombind&nbsp;&nbsp;</b>
167 <td>&rarr;&nbsp;&nbsp;<td>True if value originated from a <a href="../lang_expr.html#varparam">bound parameter</a>
168 </table></blockquote></p>
169
170 <p><b>Details:</b></p>
171
172 <p>These routines extract type, size, and content information from
173 <a href="../c3ref/value.html">protected sqlite3_value</a> objects. Protected sqlite3_value objects
174 are used to pass parameter information into the functions that
175 implement <a href="../appfunc.html">application-defined SQL functions</a> and <a href="../vtab.html">virtual tables</a>.</p>
176
177 <p>These routines work only with <a href="../c3ref/value.html">protected sqlite3_value</a> objects.
178 Any attempt to use these routines on an <a href="../c3ref/value.html">unprotected sqlite3_value</a>
179 is not threadsafe.</p>
180
181 <p>These routines work just like the corresponding <a href="../c3ref/column_blob.html">column access functions</a>
182 except that these routines take a single <a href="../c3ref/value.html">protected sqlite3_value</a> object
183 pointer instead of a <a href="../c3ref/stmt.html">sqlite3_stmt*</a> pointer and an integer column number.</p>
184
185 <p>The sqlite3_value_text16() interface extracts a UTF-16 string
186 in the native byte-order of the host machine. The
187 sqlite3_value_text16be() and sqlite3_value_text16le() interfaces
188 extract UTF-16 strings as big-endian and little-endian respectively.</p>
189
190 <p>If <a href="../c3ref/value.html">sqlite3_value</a> object V was initialized
191 using <a href="../c3ref/bind_blob.html">sqlite3_bind_pointer(S,I,P,X,D)</a> or <a href="../c3ref/result_blob.html">sqlite3_result_pointer(C,P,X,D)</a>
192 and if X and Y are strings that compare equal according to strcmp(X,Y),
193 then sqlite3_value_pointer(V,Y) will return the pointer P. Otherwise,
194 sqlite3_value_pointer(V,Y) returns a NULL. The sqlite3_bind_pointer()
195 routine is part of the <a href="../bindptr.html">pointer passing interface</a> added for SQLite 3.20.0.</p>
196
197 <p>The sqlite3_value_type(V) interface returns the
198 <a href="../c3ref/c_blob.html">datatype code</a> for the initial datatype of the
199 <a href="../c3ref/value.html">sqlite3_value</a> object V. The returned value is one of <a href="../c3ref/c_blob.html">SQLITE_INTEGER</a>,
200 <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>.
201 Other interfaces might change the datatype for an sqlite3_value object.
202 For example, if the datatype is initially SQLITE_INTEGER and
203 sqlite3_value_text(V) is called to extract a text value for that
204 integer, then subsequent calls to sqlite3_value_type(V) might return
205 SQLITE_TEXT. Whether or not a persistent internal datatype conversion
206 occurs is undefined and may change from one release of SQLite to the next.</p>
207
208 <p>The sqlite3_value_numeric_type() interface attempts to apply
209 numeric affinity to the value. This means that an attempt is
210 made to convert the value to an integer or floating point. If
211 such a conversion is possible without loss of information (in other
212 words, if the value is a string that looks like a number)
213 then the conversion is performed. Otherwise no conversion occurs.
214 The <a href="../c3ref/c_blob.html">datatype</a> after conversion is returned.</p>
215
216 <p>Within the <a href="../vtab.html#xupdate">xUpdate</a> method of a <a href="../vtab.html">virtual table</a>, the
217 sqlite3_value_nochange(X) interface returns true if and only if
218 the column corresponding to X is unchanged by the UPDATE operation
219 that the xUpdate method call was invoked to implement and if
220 the prior <a href="../vtab.html#xcolumn">xColumn</a> method call that was invoked to extract
221 the value for that column returned without setting a result (probably
222 because it queried <a href="../c3ref/vtab_nochange.html">sqlite3_vtab_nochange()</a> and found that the column
223 was unchanging). Within an <a href="../vtab.html#xupdate">xUpdate</a> method, any value for which
224 sqlite3_value_nochange(X) is true will in all other respects appear
225 to be a NULL value. If sqlite3_value_nochange(X) is invoked anywhere other
226 than within an <a href="../vtab.html#xupdate">xUpdate</a> method call for an UPDATE statement, then
227 the return value is arbitrary and meaningless.</p>
228
229 <p>The sqlite3_value_frombind(X) interface returns non-zero if the
230 value X originated from one of the <a href="../c3ref/bind_blob.html">sqlite3_bind()</a>
231 interfaces. If X comes from an SQL literal value, or a table column,
232 or an expression, then sqlite3_value_frombind(X) returns zero.</p>
233
234 <p>Please pay particular attention to the fact that the pointer returned
235 from <a href="../c3ref/value_blob.html">sqlite3_value_blob()</a>, <a href="../c3ref/value_blob.html">sqlite3_value_text()</a>, or
236 <a href="../c3ref/value_blob.html">sqlite3_value_text16()</a> can be invalidated by a subsequent call to
237 <a href="../c3ref/value_blob.html">sqlite3_value_bytes()</a>, <a href="../c3ref/value_blob.html">sqlite3_value_bytes16()</a>, <a href="../c3ref/value_blob.html">sqlite3_value_text()</a>,
238 or <a href="../c3ref/value_blob.html">sqlite3_value_text16()</a>.</p>
239
240 <p>These routines must be called from the same thread as
241 the SQL function that supplied the <a href="../c3ref/value.html">sqlite3_value*</a> parameters.</p>
242
243 <p>As long as the input parameter is correct, these routines can only
244 fail if an out-of-memory error occurs while trying to do a
245 UTF8&rarr;UTF16 or UTF16&rarr;UTF8 conversion.
246 If an out-of-memory error occurs, then the return value from these
247 routines is the same as if the column had contained an SQL NULL value.
248 If the input sqlite3_value was not obtained from <a href="../c3ref/value_dup.html">sqlite3_value_dup()</a>,
249 then valid SQL NULL returns can also be distinguished from
250 out-of-memory errors after extracting the value
251 by invoking the <a href="../c3ref/errcode.html">sqlite3_errcode()</a> immediately after the suspicious
252 return value is obtained and before any
253 other SQLite interface is called on the same <a href="../c3ref/sqlite3.html">database connection</a>.
254 If the input sqlite3_value was obtained from sqlite3_value_dup() then
255 it is disconnected from the database connection and so sqlite3_errcode()
256 will not work.
257 In that case, the only way to distinguish an out-of-memory
258 condition from a true SQL NULL is to invoke sqlite3_value_type() on the
259 input to see if it is NULL prior to trying to extract the value.
260 </p><p>See also lists of
261 <a href="../c3ref/objlist.html">Objects</a>,
262 <a href="../c3ref/constlist.html">Constants</a>, and
263 <a href="../c3ref/funclist.html">Functions</a>.</p>
264