/ Check-in [63ca02a5]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment: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)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 63ca02a5b2700858f0eceadc9b58b942d473b191
User & Date: drh 2007-09-04 12:18:42
Context
2007-09-04
14:31
Add internal locking to the test_async.c backend. So that more than one connection may be used from within a single process. (CVS 4396) check-in: 17ca684c user: danielk1977 tags: trunk
12:18
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) check-in: 63ca02a5 user: drh tags: trunk
12:00
Documentation fixes. No changes to code. Tickets #2622 and #2624. (CVS 4394) check-in: 2eadef90 user: drh tags: trunk
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

    26     26   ** on how SQLite interfaces are suppose to operate.
    27     27   **
    28     28   ** The name of this file under configuration management is "sqlite.h.in".
    29     29   ** The makefile makes some minor changes to this file (such as inserting
    30     30   ** the version number) and changes its name to "sqlite3.h" as
    31     31   ** part of the build process.
    32     32   **
    33         -** @(#) $Id: sqlite.h.in,v 1.257 2007/09/04 12:00:00 drh Exp $
           33  +** @(#) $Id: sqlite.h.in,v 1.258 2007/09/04 12:18:42 drh Exp $
    34     34   */
    35     35   #ifndef _SQLITE3_H_
    36     36   #define _SQLITE3_H_
    37     37   #include <stdarg.h>     /* Needed for the definition of va_list */
    38     38   
    39     39   /*
    40     40   ** Make sure we can call this stuff from C++.
................................................................................
  1699   1699   ** routine returns.
  1700   1700   **
  1701   1701   ** The sqlite3_bind_zeroblob() routine binds a BLOB of length n that
  1702   1702   ** is filled with zeros.  A zeroblob uses a fixed amount of memory
  1703   1703   ** (just an integer to hold it size) while it is being processed.
  1704   1704   ** Zeroblobs are intended to serve as place-holders for BLOBs whose
  1705   1705   ** content is later written using 
  1706         -** [sqlite3_blob_open | increment BLOB I/O] routines.
         1706  +** [sqlite3_blob_open | increment BLOB I/O] routines.  A negative
         1707  +** value for the zeroblob results in a zero-length BLOB.
  1707   1708   **
  1708   1709   ** The sqlite3_bind_*() routines must be called after
  1709   1710   ** [sqlite3_prepare_v2()] (and its variants) or [sqlite3_reset()] and
  1710   1711   ** before [sqlite3_step()].
  1711   1712   ** Bindings are not cleared by the [sqlite3_reset()] routine.
  1712   1713   ** Unbound parameters are interpreted as NULL.
  1713   1714   **
................................................................................
  2054   2055   ** the string to UTF-8 and then returns the number of bytes.
  2055   2056   ** If the result is a numeric value then sqlite3_column_bytes() uses
  2056   2057   ** [sqlite3_snprintf()] to convert that value to a UTF-8 string and returns
  2057   2058   ** the number of bytes in that string.
  2058   2059   ** The value returned does not include the zero terminator at the end
  2059   2060   ** of the string.  For clarity: the value returned is the number of
  2060   2061   ** bytes in the string, not the number of characters.
         2062  +**
         2063  +** Strings returned by sqlite3_column_text() and sqlite3_column_text16(),
         2064  +** even zero-length strings, are always zero terminated.  The return
         2065  +** value from sqlite3_column_blob() for a zero-length blob is an arbitrary
         2066  +** pointer, possibly even a NULL pointer.
  2061   2067   **
  2062   2068   ** The sqlite3_column_bytes16() routine is similar to sqlite3_column_bytes()
  2063   2069   ** but leaves the result in UTF-16 instead of UTF-8.  
  2064   2070   ** The zero terminator is not included in this count.
  2065   2071   **
  2066   2072   ** These routines attempt to convert the value where appropriate.  For
  2067   2073   ** example, if the internal representation is FLOAT and a text result

Changes to test/zeroblob.test.

     9      9   #
    10     10   #***********************************************************************
    11     11   # This file implements regression tests for SQLite library.  The
    12     12   # focus of this file is testing of the zero-filled blob functionality
    13     13   # including the sqlite3_bind_zeroblob(), sqlite3_result_zeroblob(),
    14     14   # and the built-in zeroblob() SQL function.
    15     15   #
    16         -# $Id: zeroblob.test,v 1.8 2007/09/01 16:16:16 danielk1977 Exp $
           16  +# $Id: zeroblob.test,v 1.9 2007/09/04 12:18:42 drh Exp $
    17     17   
    18     18   set testdir [file dirname $argv0]
    19     19   source $testdir/tester.tcl
    20     20   
    21     21   ifcapable !incrblob {
    22     22     finish_test
    23     23     return
................................................................................
   170    170     execsql {select zeroblob(-1)|1} 
   171    171   } {1} 
   172    172   do_test zeroblob-6.4 { 
   173    173     catchsql {select length(zeroblob(2147483648))} 
   174    174   } {1 {string or blob too big}} 
   175    175   do_test zeroblob-6.5 { 
   176    176     catchsql {select zeroblob(2147483648)} 
   177         -} {1 {string or blob too big}} 
          177  +} {1 {string or blob too big}}
          178  +do_test zeroblob-6.6 {
          179  +  execsql {select hex(zeroblob(-1))}
          180  +} {{}}
          181  +do_test zeroblob-6.7 {
          182  +  execsql {select typeof(zeroblob(-1))}
          183  +} {blob}
   178    184   
   179    185   # Test bind_zeroblob()
   180    186   #
   181    187   do_test zeroblob-7.1 {
   182    188     set ::STMT [sqlite3_prepare $::DB "SELECT length(?)" -1 DUMMY]
   183    189     sqlite3_bind_zeroblob $::STMT 1 450
   184    190     sqlite3_step $::STMT