Clarify documentation on the return value from sqlite3_column_blob() for

a zero-length BLOB.  Clarify the documentation on what happens when you
have a zeroblob() with a negative length.  Additional test cases but no
changes to code.  Ticket #2623. (CVS 4395)

FossilOrigin-Name: 63ca02a5b2700858f0eceadc9b58b942d473b191

manifest

@@ -1,5 +1,5 @@
-C Documentation\sfixes.\s\sNo\schanges\sto\scode.\s\sTickets\s#2622\sand\s#2624.\s(CVS\s4394)
-D 2007-09-04T12:00:00
+C Clarify\sdocumentation\son\sthe\sreturn\svalue\sfrom\ssqlite3_column_blob()\sfor\na\szero-length\sBLOB.\s\sClarify\sthe\sdocumentation\son\swhat\shappens\swhen\syou\nhave\sa\szeroblob()\swith\sa\snegative\slength.\s\sAdditional\stest\scases\sbut\sno\nchanges\sto\scode.\s\sTicket\s#2623.\s(CVS\s4395)
+D 2007-09-04T12:18:42
 F Makefile.in cbfb898945536a8f9ea8b897e1586dd1fdbcc5db
 F Makefile.linux-gcc 65241babba6faf1152bf86574477baab19190499
 F README 9c4e2d6706bdcc3efdd773ce752a8cdab4f90028
@@ -130,7 +130,7 @@ F src/random.c 4a22746501bf36b0a088c66e38dde5daba6a35da
 F src/select.c 4706a6115da1bdc09a2be5991168a6cc2c0df267
 F src/server.c 087b92a39d883e3fa113cae259d64e4c7438bc96
 F src/shell.c ac29402b538515fa4697282387be9c1205e6e9eb
-F src/sqlite.h.in ba55b61cbedad6de6182c51cc8e4546d7a2bbcf9
+F src/sqlite.h.in 3926f5d7422ce8e0641f4fc941fc368c19ef6c94
 F src/sqlite3ext.h a93f59cdee3638dc0c9c086f80df743a4e68c3cb
 F src/sqliteInt.h bb126b074352ef0ee20399883172161baf5eead2
 F src/sqliteLimit.h 1bcbbdfa856f8b71b561abb31edb864b0eca1d12
@@ -489,7 +489,7 @@ F test/where2.test 3249d426b3fc7a106713d784e1628307fc308d2e
 F test/where3.test 0a30fe9808b0fa01c46d0fcf4fac0bf6cf75bb30
 F test/where4.test f80207a4ea6504f3d0962f3ecebc7db274ea50c0
 F test/where5.test fdf66f96d29a064b63eb543e28da4dfdccd81ad2
-F test/zeroblob.test 987cc5e565dc0a905eaf87897ad958855d755f69
+F test/zeroblob.test 566fc9826297bb42bfcdcb1e3a2d39f336c16541
 F tool/diffdb.c 7524b1b5df217c20cd0431f6789851a4e0cb191b
 F tool/fragck.tcl 5265a95126abcf6ab357f7efa544787e5963f439
 F tool/lemon.c 0ab4cca47950da4dc04cf957db0c0ed54b464aa9
@@ -569,7 +569,7 @@ F www/tclsqlite.tcl 8be95ee6dba05eabcd27a9d91331c803f2ce2130
 F www/vdbe.tcl 87a31ace769f20d3627a64fa1fade7fed47b90d0
 F www/version3.tcl 890248cf7b70e60c383b0e84d77d5132b3ead42b
 F www/whentouse.tcl fc46eae081251c3c181bd79c5faef8195d7991a5
-P d5fec873102728a1ea9fbdae6799780bfb98bcfb
-R 68e25215cf50cde905b761eb593c1d2a
+P 2eadef90162590a7b947c38acf0016d0c55821c7
+R a5be8e3038cc725b3d325f8649b6f5b5
 U drh
-Z 502f0943ba181ec43a59b4174dcd9436
+Z 9f6f2dde9339d174ebf4469c17340052

manifest.uuid

@@ -1 +1 @@
-2eadef90162590a7b947c38acf0016d0c55821c7
+63ca02a5b2700858f0eceadc9b58b942d473b191

src/sqlite.h.in

@@ -30,7 +30,7 @@
 ** the version number) and changes its name to "sqlite3.h" as
 ** part of the build process.
 **
-** @(#) $Id: sqlite.h.in,v 1.257 2007/09/04 12:00:00 drh Exp $
+** @(#) $Id: sqlite.h.in,v 1.258 2007/09/04 12:18:42 drh Exp $
 */
 #ifndef _SQLITE3_H_
 #define _SQLITE3_H_
@@ -1703,7 +1703,8 @@ typedef struct sqlite3_context sqlite3_context;
 ** (just an integer to hold it size) while it is being processed.
 ** Zeroblobs are intended to serve as place-holders for BLOBs whose
 ** content is later written using 
-** [sqlite3_blob_open | increment BLOB I/O] routines.
+** [sqlite3_blob_open | increment BLOB I/O] routines.  A negative
+** value for the zeroblob results in a zero-length BLOB.
 **
 ** The sqlite3_bind_*() routines must be called after
 ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
@@ -2059,6 +2060,11 @@ int sqlite3_data_count(sqlite3_stmt *pStmt);
 ** of the string.  For clarity: the value returned is the number of
 ** bytes in the string, not the number of characters.
 **
+** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
+** even zero-length strings, are always zero terminated.  The return
+** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
+** pointer, possibly even a NULL pointer.
+**
 ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
 ** but leaves the result in UTF-16 instead of UTF-8.  
 ** The zero terminator is not included in this count.

test/zeroblob.test

@@ -13,7 +13,7 @@
 # including the sqlite3_bind_zeroblob(), sqlite3_result_zeroblob(),
 # and the built-in zeroblob() SQL function.
 #
-# $Id: zeroblob.test,v 1.8 2007/09/01 16:16:16 danielk1977 Exp $
+# $Id: zeroblob.test,v 1.9 2007/09/04 12:18:42 drh Exp $
 
 set testdir [file dirname $argv0]
 source $testdir/tester.tcl
@@ -174,7 +174,13 @@ do_test zeroblob-6.4 {
 } {1 {string or blob too big}} 
 do_test zeroblob-6.5 { 
   catchsql {select zeroblob(2147483648)} 
-} {1 {string or blob too big}} 
+} {1 {string or blob too big}}
+do_test zeroblob-6.6 {
+  execsql {select hex(zeroblob(-1))}
+} {{}}
+do_test zeroblob-6.7 {
+  execsql {select typeof(zeroblob(-1))}
+} {blob}
 
 # Test bind_zeroblob()
 #