** This file contains the C functions that implement various SQL
** functions of SQLite.  
**
** There is only one exported symbol in this file - the function
** sqliteRegisterBuildinFunctions() found at the bottom of the file.
** All other code has file scope.
**
** $Id: func.c,v 1.141 2007/04/27 01:18:03 drh Exp $
*/
#include "sqliteInt.h"
#include <ctype.h>
/* #include <math.h> */
#include <stdlib.h>
#include <assert.h>
#include "vdbeInt.h"
................................................................................

/*
** Implementation of the upper() and lower() SQL functions.
*/
static void upperFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
  char *z1;
  const char *z2;
  int i;
  if( argc<1 || SQLITE_NULL==sqlite3_value_type(argv[0]) ) return;

  z2 = (char*)sqlite3_value_text(argv[0]);
  if( z2 ){
    z1 = sqlite3_malloc(sqlite3_value_bytes(argv[0])+1);
    if( z1 ){
      strcpy(z1, z2);
      for(i=0; z1[i]; i++){
        z1[i] = toupper(z1[i]);
      }
      sqlite3_result_text(context, z1, -1, sqlite3_free);
    }
  }
}
static void lowerFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
  char *z1;
  const char *z2;
  int i;
  if( argc<1 || SQLITE_NULL==sqlite3_value_type(argv[0]) ) return;

  z2 = (char*)sqlite3_value_text(argv[0]);
  if( z2 ){
    z1 = sqlite3_malloc(sqlite3_value_bytes(argv[0])+1);
    if( z1 ){
      strcpy(z1, z2);
      for(i=0; z1[i]; i++){
        z1[i] = tolower(z1[i]);
      }
      sqlite3_result_text(context, z1, -1, sqlite3_free);
    }
................................................................................
  int nPattern;            /* Size of zPattern */
  int nRep;                /* Size of zRep */
  int nOut;                /* Maximum size of zOut */
  int loopLimit;           /* Last zStr[] that might match zPattern[] */
  int i, j;                /* Loop counters */

  assert( argc==3 );

  zStr = sqlite3_value_text(argv[0]);
  if( zStr==0 ) return;
  nStr = sqlite3_value_bytes(argv[0]);
  zPattern = sqlite3_value_text(argv[1]);
  if( zPattern==0 || zPattern[0]==0 ) return;
  nPattern = sqlite3_value_bytes(argv[1]);
  zRep = sqlite3_value_text(argv[2]);
  if( zRep==0 ) return;
  nRep = sqlite3_value_bytes(argv[2]);
  if( nPattern>=nRep ){
    nOut = nStr;
  }else{
    nOut = (nStr/nPattern + 1)*nRep;
  }
  zOut = sqlite3_malloc(nOut+1);
  if( zOut==0 ) return;
................................................................................
  int nIn;                          /* Number of bytes in input */
  int flags;
  int i;
  unsigned char cFirst, cNext;
  if( sqlite3_value_type(argv[0])==SQLITE_NULL ){
    return;
  }

  zIn = sqlite3_value_text(argv[0]);
  if( zIn==0 ) return;
  nIn = sqlite3_value_bytes(argv[0]);
  if( argc==1 ){
    static const unsigned char zSpace[] = " ";
    zCharSet = zSpace;
  }else if( (zCharSet = sqlite3_value_text(argv[1]))==0 ){
    return;
  }
  cFirst = zCharSet[0];

** This file contains the C functions that implement various SQL
** functions of SQLite.  
**
** There is only one exported symbol in this file - the function
** sqliteRegisterBuildinFunctions() found at the bottom of the file.
** All other code has file scope.
**
** $Id: func.c,v 1.142 2007/04/27 17:16:20 drh Exp $
*/
#include "sqliteInt.h"
#include <ctype.h>
/* #include <math.h> */
#include <stdlib.h>
#include <assert.h>
#include "vdbeInt.h"
................................................................................

/*
** Implementation of the upper() and lower() SQL functions.
*/
static void upperFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
  char *z1;
  const char *z2;
  int i, n;
  if( argc<1 || SQLITE_NULL==sqlite3_value_type(argv[0]) ) return;
  n = sqlite3_value_bytes(argv[0]);
  z2 = (char*)sqlite3_value_text(argv[0]);
  if( z2 ){
    z1 = sqlite3_malloc(n+1);
    if( z1 ){
      strcpy(z1, z2);
      for(i=0; z1[i]; i++){
        z1[i] = toupper(z1[i]);
      }
      sqlite3_result_text(context, z1, -1, sqlite3_free);
    }
  }
}
static void lowerFunc(sqlite3_context *context, int argc, sqlite3_value **argv){
  char *z1;
  const char *z2;
  int i, n;
  if( argc<1 || SQLITE_NULL==sqlite3_value_type(argv[0]) ) return;
  n = sqlite3_value_bytes(argv[0]);
  z2 = (char*)sqlite3_value_text(argv[0]);
  if( z2 ){
    z1 = sqlite3_malloc(n+1);
    if( z1 ){
      strcpy(z1, z2);
      for(i=0; z1[i]; i++){
        z1[i] = tolower(z1[i]);
      }
      sqlite3_result_text(context, z1, -1, sqlite3_free);
    }
................................................................................
  int nPattern;            /* Size of zPattern */
  int nRep;                /* Size of zRep */
  int nOut;                /* Maximum size of zOut */
  int loopLimit;           /* Last zStr[] that might match zPattern[] */
  int i, j;                /* Loop counters */

  assert( argc==3 );
  nStr = sqlite3_value_bytes(argv[0]);
  zStr = sqlite3_value_text(argv[0]);
  if( zStr==0 ) return;
  nPattern = sqlite3_value_bytes(argv[1]);
  zPattern = sqlite3_value_text(argv[1]);
  if( zPattern==0 || zPattern[0]==0 ) return;
  nRep = sqlite3_value_bytes(argv[2]);
  zRep = sqlite3_value_text(argv[2]);
  if( zRep==0 ) return;

  if( nPattern>=nRep ){
    nOut = nStr;
  }else{
    nOut = (nStr/nPattern + 1)*nRep;
  }
  zOut = sqlite3_malloc(nOut+1);
  if( zOut==0 ) return;
................................................................................
  int nIn;                          /* Number of bytes in input */
  int flags;
  int i;
  unsigned char cFirst, cNext;
  if( sqlite3_value_type(argv[0])==SQLITE_NULL ){
    return;
  }
  nIn = sqlite3_value_bytes(argv[0]);
  zIn = sqlite3_value_text(argv[0]);
  if( zIn==0 ) return;

  if( argc==1 ){
    static const unsigned char zSpace[] = " ";
    zCharSet = zSpace;
  }else if( (zCharSet = sqlite3_value_text(argv[1]))==0 ){
    return;
  }
  cFirst = zCharSet[0];

**    May you share freely, never taking more than you give.
**
*************************************************************************
** Code for testing all sorts of SQLite interfaces.  This code
** is not included in the SQLite library.  It is used for automated
** testing of the SQLite library.
**
** $Id: test1.c,v 1.239 2007/04/23 23:56:31 drh Exp $
*/
#include "sqliteInt.h"
#include "tcl.h"
#include "os.h"
#include <stdlib.h>
#include <string.h>

................................................................................
  sqlite3_context *context,
  int argc,
  sqlite3_value **argv
){
  int i;
  for(i=0; i<argc; i++){
    if( SQLITE_NULL!=sqlite3_value_type(argv[i]) ){

      sqlite3_result_text(context, (char*)sqlite3_value_text(argv[i]),
          sqlite3_value_bytes(argv[i]), SQLITE_TRANSIENT);
      break;
    }
  }
}

/*
** These are test functions.    hex8() interprets its argument as
................................................................................
    sqlite3_result_error(context, "tkt2213 is not fixed", -1);
  }else{
    char *zCopy = (char *)sqlite3_malloc(nText);
    memcpy(zCopy, zText1, nText);
    sqlite3_result_text(context, zCopy, nText, sqlite3_free);
  }
}












































































/*
** Usage:  sqlite_test_create_function DB
**
** Call the sqlite3_create_function API on the given database in order
** to create a function named "x_coalesce".  This function does the same thing
** as the "coalesce" function.  This function also registers an SQL function
................................................................................
          hex16Func, 0, 0);
  }
#endif
  if( rc==SQLITE_OK ){
    rc = sqlite3_create_function(db, "tkt2213func", 1, SQLITE_ANY, 0, 
          tkt2213Function, 0, 0);
  }





#ifndef SQLITE_OMIT_UTF16
  /* Use the sqlite3_create_function16() API here. Mainly for fun, but also 
  ** because it is not tested anywhere else. */
  if( rc==SQLITE_OK ){
    sqlite3_value *pVal;
#ifdef SQLITE_MEMDEBUG
................................................................................
       Tcl_GetString(objv[0]), " STMT column", 0);
    return TCL_ERROR;
  }

  if( getStmtPointer(interp, Tcl_GetString(objv[1]), &pStmt) ) return TCL_ERROR;
  if( Tcl_GetIntFromObj(interp, objv[2], &col) ) return TCL_ERROR;

  pBlob = sqlite3_column_blob(pStmt, col);
  len = sqlite3_column_bytes(pStmt, col);

  Tcl_SetObjResult(interp, Tcl_NewByteArrayObj(pBlob, len));
  return TCL_OK;
}

/*
** Usage: sqlite3_column_double STMT column
**

**    May you share freely, never taking more than you give.
**
*************************************************************************
** Code for testing all sorts of SQLite interfaces.  This code
** is not included in the SQLite library.  It is used for automated
** testing of the SQLite library.
**
** $Id: test1.c,v 1.240 2007/04/27 17:16:20 drh Exp $
*/
#include "sqliteInt.h"
#include "tcl.h"
#include "os.h"
#include <stdlib.h>
#include <string.h>

................................................................................
  sqlite3_context *context,
  int argc,
  sqlite3_value **argv
){
  int i;
  for(i=0; i<argc; i++){
    if( SQLITE_NULL!=sqlite3_value_type(argv[i]) ){
      int n = sqlite3_value_bytes(argv[i]);
      sqlite3_result_text(context, (char*)sqlite3_value_text(argv[i]),
          n, SQLITE_TRANSIENT);
      break;
    }
  }
}

/*
** These are test functions.    hex8() interprets its argument as
................................................................................
    sqlite3_result_error(context, "tkt2213 is not fixed", -1);
  }else{
    char *zCopy = (char *)sqlite3_malloc(nText);
    memcpy(zCopy, zText1, nText);
    sqlite3_result_text(context, zCopy, nText, sqlite3_free);
  }
}

/*
** The following SQL function takes 4 arguments.  The 2nd and
** 4th argument must be one of these strings:  'text', 'text16',
** or 'blob' corresponding to API functions
**
**      sqlite3_value_text()
**      sqlite3_value_text16()
**      sqlite3_value_blob()
**
** The third argument is a string, either 'bytes' or 'bytes16' or 'noop',
** corresponding to APIs:
**
**      sqlite3_value_bytes()
**      sqlite3_value_bytes16()
**      noop
**
** The APIs designated by the 2nd through 4th arguments are applied
** to the first argument in order.  If the pointers returned by the
** second and fourth are different, this routine returns 1.  Otherwise,
** this routine returns 0.
**
** This function is used to test to see when returned pointers from
** the _text(), _text16() and _blob() APIs become invalidated.
*/
static void ptrChngFunction(
  sqlite3_context *context, 
  int argc,  
  sqlite3_value **argv
){
  const void *p1, *p2;
  const char *zCmd;
  if( argc!=4 ) return;
  zCmd = (const char*)sqlite3_value_text(argv[1]);
  if( zCmd==0 ) return;
  if( strcmp(zCmd,"text")==0 ){
    p1 = (const void*)sqlite3_value_text(argv[0]);
#ifndef SQLITE_OMIT_UTF16
  }else if( strcmp(zCmd, "text16")==0 ){
    p1 = (const void*)sqlite3_value_text16(argv[0]);
#endif
  }else if( strcmp(zCmd, "blob")==0 ){
    p1 = (const void*)sqlite3_value_blob(argv[0]);
  }else{
    return;
  }
  zCmd = (const char*)sqlite3_value_text(argv[2]);
  if( zCmd==0 ) return;
  if( strcmp(zCmd,"bytes")==0 ){
    sqlite3_value_bytes(argv[0]);
#ifndef SQLITE_OMIT_UTF16
  }else if( strcmp(zCmd, "bytes16")==0 ){
    sqlite3_value_bytes16(argv[0]);
#endif
  }else if( strcmp(zCmd, "noop")==0 ){
    /* do nothing */
  }else{
    return;
  }
  zCmd = (const char*)sqlite3_value_text(argv[3]);
  if( zCmd==0 ) return;
  if( strcmp(zCmd,"text")==0 ){
    p2 = (const void*)sqlite3_value_text(argv[0]);
#ifndef SQLITE_OMIT_UTF16
  }else if( strcmp(zCmd, "text16")==0 ){
    p2 = (const void*)sqlite3_value_text16(argv[0]);
#endif
  }else if( strcmp(zCmd, "blob")==0 ){
    p2 = (const void*)sqlite3_value_blob(argv[0]);
  }else{
    return;
  }
  sqlite3_result_int(context, p1!=p2);
}


/*
** Usage:  sqlite_test_create_function DB
**
** Call the sqlite3_create_function API on the given database in order
** to create a function named "x_coalesce".  This function does the same thing
** as the "coalesce" function.  This function also registers an SQL function
................................................................................
          hex16Func, 0, 0);
  }
#endif
  if( rc==SQLITE_OK ){
    rc = sqlite3_create_function(db, "tkt2213func", 1, SQLITE_ANY, 0, 
          tkt2213Function, 0, 0);
  }
  if( rc==SQLITE_OK ){
    rc = sqlite3_create_function(db, "pointer_change", 4, SQLITE_ANY, 0, 
          ptrChngFunction, 0, 0);
  }

#ifndef SQLITE_OMIT_UTF16
  /* Use the sqlite3_create_function16() API here. Mainly for fun, but also 
  ** because it is not tested anywhere else. */
  if( rc==SQLITE_OK ){
    sqlite3_value *pVal;
#ifdef SQLITE_MEMDEBUG
................................................................................
       Tcl_GetString(objv[0]), " STMT column", 0);
    return TCL_ERROR;
  }

  if( getStmtPointer(interp, Tcl_GetString(objv[1]), &pStmt) ) return TCL_ERROR;
  if( Tcl_GetIntFromObj(interp, objv[2], &col) ) return TCL_ERROR;


  len = sqlite3_column_bytes(pStmt, col);
  pBlob = sqlite3_column_blob(pStmt, col);
  Tcl_SetObjResult(interp, Tcl_NewByteArrayObj(pBlob, len));
  return TCL_OK;
}

/*
** Usage: sqlite3_column_double STMT column
**

/**************************** sqlite3_value_  *******************************
** The following routines extract information from a Mem or sqlite3_value
** structure.
*/
const void *sqlite3_value_blob(sqlite3_value *pVal){
  Mem *p = (Mem*)pVal;
  if( p->flags & (MEM_Blob|MEM_Str) ){



    return p->z;
  }else{
    return sqlite3_value_text(pVal);
  }
}
int sqlite3_value_bytes(sqlite3_value *pVal){
  return sqlite3ValueBytes(pVal, SQLITE_UTF8);

/**************************** sqlite3_value_  *******************************
** The following routines extract information from a Mem or sqlite3_value
** structure.
*/
const void *sqlite3_value_blob(sqlite3_value *pVal){
  Mem *p = (Mem*)pVal;
  if( p->flags & (MEM_Blob|MEM_Str) ){
    if( (p->flags & MEM_Term)==0 ){
      p->flags &= ~MEM_Str;
    }
    return p->z;
  }else{
    return sqlite3_value_text(pVal);
  }
}
int sqlite3_value_bytes(sqlite3_value *pVal){
  return sqlite3ValueBytes(pVal, SQLITE_UTF8);

# 2007 April 27
#
# The author disclaims copyright to this source code.  In place of
# a legal notice, here is a blessing:
#
#    May you do good and not evil.
#    May you find forgiveness for yourself and forgive others.
#    May you share freely, never taking more than you give.
#
#***********************************************************************
# This file implements regression tests for SQLite library.
#
# The focus of the tests in this file are to verify that the
# underlying TEXT or BLOB representation of an sqlite3_value
# changes appropriately when APIs from the following set are
# called:
#
#     sqlite3_value_text()
#     sqlite3_value_text16()
#     sqlite3_value_blob()
#     sqlite3_value_bytes()
#     sqlite3_value_bytes16()
#
# $Id: ptrchng.test,v 1.1 2007/04/27 17:16:22 drh Exp $

set testdir [file dirname $argv0]
source $testdir/tester.tcl

# Register the "pointer_change" SQL function.
#
sqlite3_create_function db

do_test ptrchng-1.1 {
  execsql {
    CREATE TABLE t1(x INTEGER PRIMARY KEY, y BLOB);
    INSERT INTO t1 VALUES(1, 'abc');
    INSERT INTO t1 VALUES(2, 
       'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234356789');
    INSERT INTO t1 VALUES(3, x'626c6f62');
    INSERT INTO t1 VALUES(4,
 x'000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f2021222324'
    );
    SELECT count(*) FROM t1;
  }
} {4}

# For the short entries that fit in the Mem.zBuf[], the pointer should
# never change regardless of what type conversions occur.
#
do_test ptrchng-2.1 {
  execsql {
    SELECT pointer_change(y, 'text', 'noop', 'blob') FROM t1 WHERE x=1
  }
} {0}
do_test ptrchng-2.2 {
  execsql {
    SELECT pointer_change(y, 'blob', 'noop', 'text') FROM t1 WHERE x=1
  }
} {0}
ifcapable utf16 {
  do_test ptrchng-2.3 {
    execsql {
      SELECT pointer_change(y, 'text', 'noop', 'text16') FROM t1 WHERE x=1
    }
  } {0}
  do_test ptrchng-2.4 {
    execsql {
      SELECT pointer_change(y, 'blob', 'noop', 'text16') FROM t1 WHERE x=1
    }
  } {0}
  do_test ptrchng-2.5 {
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'blob') FROM t1 WHERE x=1
    }
  } {0}
  do_test ptrchng-2.6 {
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'text') FROM t1 WHERE x=1
    }
  } {0}
}
do_test ptrchng-2.11 {
  execsql {
    SELECT pointer_change(y, 'text', 'noop', 'blob') FROM t1 WHERE x=3
  }
} {0}
do_test ptrchng-2.12 {
  execsql {
    SELECT pointer_change(y, 'blob', 'noop', 'text') FROM t1 WHERE x=3
  }
} {0}
ifcapable utf16 {
  do_test ptrchng-2.13 {
    execsql {
      SELECT pointer_change(y, 'text', 'noop', 'text16') FROM t1 WHERE x=3
    }
  } {0}
  do_test ptrchng-2.14 {
    execsql {
      SELECT pointer_change(y, 'blob', 'noop', 'text16') FROM t1 WHERE x=3
    }
  } {0}
  do_test ptrchng-2.15 {
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'blob') FROM t1 WHERE x=3
    }
  } {0}
  do_test ptrchng-2.16 {
btree_breakpoint
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'text') FROM t1 WHERE x=3
    }
  } {0}
}

# For the long entries that do not fit in the Mem.zBuf[], the pointer
# should change sometimes.
#
do_test ptrchng-3.1 {
  execsql {
    SELECT pointer_change(y, 'text', 'noop', 'blob') FROM t1 WHERE x=2
  }
} {0}
do_test ptrchng-3.2 {
  execsql {
    SELECT pointer_change(y, 'blob', 'noop', 'text') FROM t1 WHERE x=2
  }
} {0}
ifcapable utf16 {
  do_test ptrchng-3.3 {
    execsql {
      SELECT pointer_change(y, 'text', 'noop', 'text16') FROM t1 WHERE x=2
    }
  } {1}
  do_test ptrchng-3.4 {
    execsql {
      SELECT pointer_change(y, 'blob', 'noop', 'text16') FROM t1 WHERE x=2
    }
  } {1}
  do_test ptrchng-3.5 {
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'blob') FROM t1 WHERE x=2
    }
  } {0}
  do_test ptrchng-3.6 {
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'text') FROM t1 WHERE x=2
    }
  } {1}
}
do_test ptrchng-3.11 {
  execsql {
    SELECT pointer_change(y, 'text', 'noop', 'blob') FROM t1 WHERE x=4
  }
} {0}
do_test ptrchng-3.12 {
  execsql {
    SELECT pointer_change(y, 'blob', 'noop', 'text') FROM t1 WHERE x=4
  }
} {0}
ifcapable utf16 {
  do_test ptrchng-3.13 {
    execsql {
      SELECT pointer_change(y, 'text', 'noop', 'text16') FROM t1 WHERE x=4
    }
  } {1}
  do_test ptrchng-3.14 {
    execsql {
      SELECT pointer_change(y, 'blob', 'noop', 'text16') FROM t1 WHERE x=4
    }
  } {1}
  do_test ptrchng-3.15 {
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'blob') FROM t1 WHERE x=4
    }
  } {0}
  do_test ptrchng-3.16 {
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'text') FROM t1 WHERE x=4
    }
  } {1}
}

# A call to _bytes() should never reformat a _text() or _blob().
#
do_test ptrchng-4.1 {
  execsql {
    SELECT pointer_change(y, 'text', 'bytes', 'text') FROM t1
  }
} {0 0 0 0}
do_test ptrchng-4.2 {
  execsql {
    SELECT pointer_change(y, 'blob', 'bytes', 'blob') FROM t1
  }
} {0 0 0 0}

# A call to _blob() should never trigger a reformat
#
do_test ptrchng-5.1 {
  execsql {
    SELECT pointer_change(y, 'text', 'bytes', 'blob') FROM t1
  }
} {0 0 0 0}
ifcapable utf16 {
  do_test ptrchng-5.2 {
    execsql {
      SELECT pointer_change(y, 'text16', 'noop', 'blob') FROM t1
    }
  } {0 0 0 0}
  do_test ptrchng-5.3 {
    execsql {
      SELECT pointer_change(y, 'text16', 'bytes16', 'blob') FROM t1
    }
  } {0 0 0 0}
}

finish_test

set rcsid {$Id: capi3.tcl,v 1.9 2005/03/11 04:39:58 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}

proc AddHyperlinks {txt} {
  regsub -all {([^:alnum:>])(sqlite3_\w+)(\([^\)]*\))} $txt \
      {\1<a href="capi3ref.html#\2">\2</a>\3} t2
  puts $t2
................................................................................

<p>
It is not necessary to retrieve data in the format specify by
sqlite3_column_type().  If a different format is requested, the data
is converted automatically.
</p>



















































<h4>2.3 User-defined functions</h4>

<p>
User defined functions can be created using the following routine:
</p>

<blockquote><pre>

set rcsid {$Id: capi3.tcl,v 1.10 2007/04/27 17:16:22 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}

proc AddHyperlinks {txt} {
  regsub -all {([^:alnum:>])(sqlite3_\w+)(\([^\)]*\))} $txt \
      {\1<a href="capi3ref.html#\2">\2</a>\3} t2
  puts $t2
................................................................................

<p>
It is not necessary to retrieve data in the format specify by
sqlite3_column_type().  If a different format is requested, the data
is converted automatically.
</p>

<p>
Data format conversions can invalidate the pointer returned by
prior calls to sqlite3_column_blob(), sqlite3_column_text(), and/or
sqlite3_column_text16().  Pointers might be invalided in the following
cases:
</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>
<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>
<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>
Note that 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 this: assume that any
result from
<ul>
<li>sqlite3_column_blob(),</li>
<li>sqlite3_column_text(), or</li>
<li>sqlite3_column_text16()</li>
</ul>
is invalided by subsequent calls to 
<ul>
<li>sqlite3_column_bytes(),</li>
<li>sqlite3_column_bytes16(),</li>
<li>sqlite3_column_text(), or</li>
<li>sqlite3_column_text16().</li>
</ul>
This means that you should always call sqlite3_column_bytes() or
sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(),
sqlite3_column_text(), or sqlite3_column_text16().
</p>

<h4>2.3 User-defined functions</h4>

<p>
User defined functions can be created using the following routine:
</p>

<blockquote><pre>

set rcsid {$Id: capi3ref.tcl,v 1.55 2007/04/16 15:35:24 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
................................................................................
<tr><td> BLOB </td><td>    FLOAT </td><td> Convert to TEXT then use atof()</td></tr>
<tr><td> BLOB </td><td>    TEXT </td><td>  Add a \\000 terminator if needed</td></tr>
</table>
</blockquote>

  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.  So, for example, if
  you initially call sqlite3_column_text() and get back a pointer to





  a UTF-8 string, then you call sqlite3_column_text16(), after the























  call to sqlite3_column_text16() the pointer returned by the prior
  call to sqlite3_column_text() will likely point to deallocated memory.
  Attempting to use the original pointer might lead to heap corruption



  or a segfault.  Note also that calls  to sqlite3_column_bytes()
  and sqlite3_column_bytes16() can also cause type conversion that
  and deallocate prior buffers.  Use these routines carefully.







}

api {} {
int sqlite3_column_count(sqlite3_stmt *pStmt);
} {
 Return the number of columns in the result set returned by the prepared
 SQL statement. This routine returns 0 if pStmt is an SQL statement
................................................................................
 to access their arguments.  These routines are the same as the
 sqlite3_column_... routines except that these routines take a single
 sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
 column number.

 See the documentation under sqlite3_column_blob for additional
 information.






}

api {} {
  int sqlite3_sleep(int);
} {
 Sleep for a little while. The second parameter is the number of
 miliseconds to sleep for. 

set rcsid {$Id: capi3ref.tcl,v 1.56 2007/04/27 17:16:22 drh Exp $}
source common.tcl
header {C/C++ Interface For SQLite Version 3}
puts {
<h2 class=pdf_section>C/C++ Interface For SQLite Version 3</h2>
}

proc api {name prototype desc {notused x}} {
................................................................................
<tr><td> BLOB </td><td>    FLOAT </td><td> Convert to TEXT then use atof()</td></tr>
<tr><td> BLOB </td><td>    TEXT </td><td>  Add a \\000 terminator if needed</td></tr>
</table>
</blockquote>

  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:

  <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>
  <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>
  <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>

  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.  

  The safest and easiest to remember policy is this: assume that any
  result from
  <ul>
  <li>sqlite3_column_blob(),</li>
  <li>sqlite3_column_text(), or</li>
  <li>sqlite3_column_text16()</li>

  </ul>
  is invalided by subsequent calls to 
  <ul>
  <li>sqlite3_column_bytes(),</li>
  <li>sqlite3_column_bytes16(),</li>

  <li>sqlite3_column_text(), or</li>
  <li>sqlite3_column_text16().</li>
  </ul>
  This means that you should always call sqlite3_column_bytes() or
  sqlite3_column_bytes16() <u>before</u> calling sqlite3_column_blob(),
  sqlite3_column_text(), or sqlite3_column_text16().

}

api {} {
int sqlite3_column_count(sqlite3_stmt *pStmt);
} {
 Return the number of columns in the result set returned by the prepared
 SQL statement. This routine returns 0 if pStmt is an SQL statement
................................................................................
 to access their arguments.  These routines are the same as the
 sqlite3_column_... routines except that these routines take a single
 sqlite3_value* pointer instead of an sqlite3_stmt* and an integer
 column number.

 See the documentation under sqlite3_column_blob for additional
 information.

 Please pay particular attention to the fact that the pointer that
 is returned from sqlite3_value_blob(), sqlite3_value_text(), or
 sqlite3_value_text16() can be invalidated by a subsequent call to
 sqlite3_value_bytes(), sqlite3_value_bytes16(), sqlite_value_text(),
 or sqlite3_value_text16().  
}

api {} {
  int sqlite3_sleep(int);
} {
 Sleep for a little while. The second parameter is the number of
 miliseconds to sleep for.