[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
scratch/sqlite 1b2a8e0 3/3: Add sqlite-finalize and edit the manual sect
From: |
Lars Ingebrigtsen |
Subject: |
scratch/sqlite 1b2a8e0 3/3: Add sqlite-finalize and edit the manual section |
Date: |
Fri, 10 Dec 2021 22:47:47 -0500 (EST) |
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