scratch/sqlite 1b2a8e0 3/3: Add sqlite-finalize and edit the manual section

[Lars Ingebrigtsen]

branch: scratch/sqlite
commit 1b2a8e08e29a83481314e7fe2e6a4d60175a1a5d
Author: Lars Ingebrigtsen <larsi@gnus.org>
Commit: Lars Ingebrigtsen <larsi@gnus.org>

    Add sqlite-finalize and edit the manual section
---
 doc/lispref/text.texi | 27 ++++++++++++++++++++++-----
 src/sqlite.c          | 15 ++++++++++++++-
 2 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
index 6576ac7..e964d7b 100644
--- a/doc/lispref/text.texi
+++ b/doc/lispref/text.texi
@@ -5151,7 +5151,7 @@ When SQLite support is available, the following functions 
can be used.
 @defun sqlite-open &optional file
 This function opens @var{file} as a database file.  If it doesn't
 exist, a new database will be created and stored there.  If this
-argument is missing or @code{nil}, an in-memory database is created
+argument is missing or @code{nil}, a new in-memory database is created
 instead.
 
 The return value is a @dfn{database object} that can be used as the
@@ -5189,7 +5189,9 @@ This has exactly the same effect as the first form, but 
is more
 efficient and safer (because it doesn't involve any string parsing or
 interpolation).
 
-The number of affected rows is returned.
+The number of affected rows is returned.  For instance, an
+@samp{insert} statement will return @samp{1}, but an @samp{update}
+statement may return zero or a higher number.
 @end defun
 
 @defun sqlite-select db query &optional values result-type
@@ -5204,7 +5206,7 @@ As with the @code{sqlite-execute} command, you can pass 
in a list or a
 vector of values that will be bound before executing the select:
 
 @lisp
-(sqlite-select db "select * from foo where key = ?" '(2))
+(sqlite-select db "select * from foo where key = ?" [2])
   @result{} (("bar" 2))
 @end lisp
 
@@ -5218,7 +5220,10 @@ the first element in the return value.
 If @var{return-type} is @code{set}, this function will return a
 @dfn{statement object} instead.  This object can be interrogated by
 the @code{sqlite-next}, @code{sqlite-columns} and @code{sqlite-more-p}
-functions.
+functions.  If the result set is small, it's often more convenient to
+just return the data directly, but if the result set is large (or if
+you won't be using all the data from the set), using the @code{set}
+method will allocate a lot less data, and therefore be more efficient.
 @end defun
 
 @defun sqlite-next statement
@@ -5234,6 +5239,11 @@ This function returns the next row in the result set 
returned by
 @defun sqlite-columns statement
 This function returns the column names of the result set returned by
 @code{sqlite-select}.
+
+@lisp
+(sqlite-columns stmt)
+    @result{} ("name" "issue")
+@end lisp
 @end defun
 
 @defun sqlite-more-p statement
@@ -5241,6 +5251,13 @@ This predicate says whether there is more data to be 
fetched in the
 result set returned by @code{sqlite-select}.
 @end defun
 
+@defun sqlite-finalize statement
+If @var{statement} is not going to be used any more, calling this
+function will free the resources bound by @var{statement}.  This is
+usually not necessary---when the statement object is
+garbage-collected, this will happen automatically.
+@end defun
+
 @defun sqlite-transaction db
 Start a transaction in @var{db}.  When in a transaction, other readers
 of the database won't access the results until the transaction has
@@ -5248,7 +5265,7 @@ been committed.
 @end defun
 
 @defun sqlite-commit db
-End a transaction and write the data out.
+End a transaction and write the data out to file.
 @end defun
 
 @defun sqlite-rollback db
diff --git a/src/sqlite.c b/src/sqlite.c
index 1f74b28..b1843bc 100644
--- a/src/sqlite.c
+++ b/src/sqlite.c
@@ -233,8 +233,10 @@ check_sqlite (Lisp_Object db, bool is_statement)
     xsignal1 (Qerror, build_string ("Invalid set object"));
   else if (!is_statement && XSQLITE (db)->is_statement)
     xsignal1 (Qerror, build_string ("Invalid database object"));
-  if (!XSQLITE (db)->db)
+  if (!is_statement && !XSQLITE (db)->db)
     xsignal1 (Qerror, build_string ("Database closed"));
+  else if (is_statement && !XSQLITE (db)->db)
+    xsignal1 (Qerror, build_string ("Statement closed"));
 }
 
 static int db_count = 0;
@@ -631,6 +633,16 @@ DEFUN ("sqlite-more-p", Fsqlite_more_p, Ssqlite_more_p, 1, 
1, 0,
     return Qt;
 }
 
+DEFUN ("sqlite-finalize", Fsqlite_finalize, Ssqlite_finalize, 1, 1, 0,
+       doc: /* Mark this SET as being finished.
+This will free the resources held by SET.  */)
+  (Lisp_Object set)
+{
+  check_sqlite (set, true);
+  sqlite3_finalize (XSQLITE (set)->stmt);
+  return Qt;
+}
+
 #endif /* HAVE_SQLITE3 */
 
 DEFUN ("sqlitep", Fsqlitep, Ssqlitep, 1, 1, 0,
@@ -683,6 +695,7 @@ syms_of_sqlite (void)
   defsubr (&Ssqlite_next);
   defsubr (&Ssqlite_columns);
   defsubr (&Ssqlite_more_p);
+  defsubr (&Ssqlite_finalize);
   DEFSYM (Qset, "set");
   DEFSYM (Qfull, "full");
 #endif