New interfaces sqlite3_str_truncate() and sqlite3_str_free(). Version number

increases to 3.52.0.

FossilOrigin-Name: fa85534ed927851dc37a4943e83259bff4509f141449226ffb506f9acc7b2cc5

src/loadext.c

@@ -522,7 +522,10 @@ static const sqlite3_api_routines sqlite3Apis = {
   sqlite3_setlk_timeout,
   /* Version 3.51.0 and later */
   sqlite3_set_errmsg,
-  sqlite3_db_status64
+  sqlite3_db_status64,
+  /* Version 3.52.0 and later */
+  sqlite3_str_truncate,
+  sqlite3_str_free
 };
 
 /* True if x is the directory separator character

src/printf.c

@@ -1228,6 +1228,14 @@ int sqlite3_str_length(sqlite3_str *p){
   return p ? p->nChar : 0;
 }
 
+/* Truncate the text of the string to be no more than N bytes. */
+void sqlite3_str_truncate(sqlite3_str *p, int N){
+  if( p!=0 && N>=0 && N<p->nChar ){
+    p->nChar = N;
+    p->zText[p->nChar] = 0;
+  }
+}
+
 /* Return the current value for p */
 char *sqlite3_str_value(sqlite3_str *p){
   if( p==0 || p->nChar==0 ) return 0;
@@ -1248,6 +1256,17 @@ void sqlite3_str_reset(StrAccum *p){
   p->zText = 0;
 }
 
+/*
+** Destroy a dynamically allocate sqlite3_str object and all
+** of its content, all in one call.
+*/
+void sqlite3_str_free(sqlite3_str *p){
+  if( p ){
+    sqlite3_str_reset(p);
+    sqlite3_free(p);
+  }
+}
+
 /*
 ** Initialize a string accumulator.
 **

src/sqlite.h.in

@@ -8727,15 +8727,20 @@ sqlite3_str *sqlite3_str_new(sqlite3*);
 ** errors were encountered during construction of the string.  ^The
 ** [sqlite3_str_finish(X)] interface will also return a NULL pointer if the
 ** string in [sqlite3_str] object X is zero bytes long.
+**
+** ^The [sqlite3_str_free(X)] interface destroys both the sqlite3_str object
+** X and the string content it contains.  Calling sqlite3_str_free(X) is
+** the equivalent of calling [sqlite3_free](sqlite3_str_finalize(X)).
 */
 char *sqlite3_str_finish(sqlite3_str*);
+void sqlite3_str_free(sqlite3_str*);
 
 /*
 ** CAPI3REF: Add Content To A Dynamic String
 ** METHOD: sqlite3_str
 **
-** These interfaces add content to an sqlite3_str object previously obtained
-** from [sqlite3_str_new()].
+** These interfaces add or remove content to an sqlite3_str object
+** previously obtained from [sqlite3_str_new()].
 **
 ** ^The [sqlite3_str_appendf(X,F,...)] and
 ** [sqlite3_str_vappendf(X,F,V)] interfaces uses the [built-in printf]
@@ -8758,6 +8763,10 @@ char *sqlite3_str_finish(sqlite3_str*);
 ** ^The [sqlite3_str_reset(X)] method resets the string under construction
 ** inside [sqlite3_str] object X back to zero bytes in length. 
 **
+** ^The [sqlite3_str_truncate(X,N)] method changes the length of the string
+** under construction to be N bytes are less.  This routine is a no-op if
+** N is negative or if the string is already N bytes or smaller in size.
+**
 ** These methods do not return a result code.  ^If an error occurs, that fact
 ** is recorded in the [sqlite3_str] object and can be recovered by a
 ** subsequent call to [sqlite3_str_errcode(X)].
@@ -8768,6 +8777,7 @@ void sqlite3_str_append(sqlite3_str*, const char *zIn, int N);
 void sqlite3_str_appendall(sqlite3_str*, const char *zIn);
 void sqlite3_str_appendchar(sqlite3_str*, int N, char C);
 void sqlite3_str_reset(sqlite3_str*);
+void sqlite3_str_truncate(sqlite3_str*,int N);
 
 /*
 ** CAPI3REF: Status Of A Dynamic String

src/sqlite3ext.h

@@ -371,7 +371,9 @@ struct sqlite3_api_routines {
   /* Version 3.51.0 and later */
   int (*set_errmsg)(sqlite3*,int,const char*);
   int (*db_status64)(sqlite3*,int,sqlite3_int64*,sqlite3_int64*,int);
-  
+  /* Version 3.52.0 and later */
+  void (*str_truncate)(sqlite3_str*,int);
+  void (*str_free)(sqlite3_str*);
 };
 
 /*
@@ -710,6 +712,9 @@ typedef int (*sqlite3_loadext_entry)(
 /* Version 3.51.0 and later */
 #define sqlite3_set_errmsg             sqlite3_api->set_errmsg
 #define sqlite3_db_status64            sqlite3_api->db_status64
+/* Version 3.52.0 and later */
+#define sqlite3_str_truncate           sqlite3_api->str_truncate
+#define sqlite3_str_free               sqlite3_api->str_free
 #endif /* !defined(SQLITE_CORE) && !defined(SQLITE_OMIT_LOAD_EXTENSION) */
 
 #if !defined(SQLITE_CORE) && !defined(SQLITE_OMIT_LOAD_EXTENSION)