extralite-bundle 2.3 → 2.5

data/ext/extralite/query.c

@@ -20,8 +20,14 @@ static size_t Query_size(const void *ptr) {
 
 static void Query_mark(void *ptr) {
   Query_t *query = ptr;
-  rb_gc_mark(query->db);
-  rb_gc_mark(query->sql);
+  rb_gc_mark_movable(query->db);
+  rb_gc_mark_movable(query->sql);
+}
+
+static void Query_compact(void *ptr) {
+  Query_t *query = ptr;
+  query->db = rb_gc_location(query->db);
+  query->sql = rb_gc_location(query->sql);
 }
 
 static void Query_free(void *ptr) {
@@ -32,8 +38,8 @@ static void Query_free(void *ptr) {
 
 static const rb_data_type_t Query_type = {
     "Query",
-    {Query_mark, Query_free, Query_size,},
-    0, 0, RUBY_TYPED_FREE_IMMEDIATELY
+    {Query_mark, Query_free, Query_size, Query_compact},
+    0, 0, RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_WB_PROTECTED
 };
 
 static VALUE Query_allocate(VALUE klass) {
@@ -67,10 +73,12 @@ VALUE Query_initialize(VALUE self, VALUE db, VALUE sql) {
   if (!RSTRING_LEN(sql))
     rb_raise(cError, "Cannot prepare an empty SQL query");
 
+  RB_OBJ_WRITE(self, &query->db, db);
+  RB_OBJ_WRITE(self, &query->sql, sql);
+
   query->db = db;
   query->db_struct = self_to_database(db);
   query->sqlite3_db = Database_sqlite3_db(db);
-  query->sql = sql;
   query->stmt = NULL;
   query->closed = 0;
   query->eof = 0;
@@ -134,14 +142,14 @@ VALUE Query_reset(VALUE self) {
  * Bound parameters can be specified as a list of values or as a hash mapping
  * parameter names to values. When parameters are given as a splatted array, the
  * query should specify parameters using `?`:
- * 
+ *
  *     query = db.prepare('select * from foo where x = ?')
  *     query.bind(42)
  *
  * Named placeholders are specified using `:`. The placeholder values are
  * specified using a hash, where keys are either strings are symbols. String
  * keys can include or omit the `:` prefix. The following are equivalent:
- * 
+ *
  *     query = db.prepare('select * from foo where x = :bar')
  *     query.bind(bar: 42)
  *
@@ -171,19 +179,18 @@ VALUE Query_eof_p(VALUE self) {
 static inline VALUE Query_perform_next(VALUE self, int max_rows, VALUE (*call)(query_ctx *)) {
   Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
-  
+
   if (!query->stmt) query_reset(query);
   if (query->eof) return rb_block_given_p() ? self : Qnil;
 
-  query_ctx ctx = {
+  query_ctx ctx = QUERY_CTX(
     self,
-    query->sqlite3_db,
+    query->db_struct,
     query->stmt,
     Qnil,
     QUERY_MODE(max_rows == SINGLE_ROW ? QUERY_SINGLE_ROW : QUERY_MULTI_ROW),
-    MAX_ROWS(max_rows),
-    0
-  };
+    MAX_ROWS(max_rows)
+  );
   VALUE result = call(&ctx);
   query->eof = ctx.eof;
   return (ctx.mode == QUERY_YIELD) ? self : result;
@@ -193,12 +200,12 @@ static inline VALUE Query_perform_next(VALUE self, int max_rows, VALUE (*call)(q
 
 /* Returns the next 1 or more rows from the associated query's result set as a
  * hash.
- * 
+ *
  * If no row count is given, a single row is returned. If a row count is given,
  * an array containing up to the `row_count` rows is returned. If `row_count` is
  * -1, all rows are returned. If the end of the result set has been reached,
  * `nil` is returned.
- * 
+ *
  * If a block is given, rows are passed to the block and self is returned.
  *
  * @overload next()
@@ -219,12 +226,12 @@ VALUE Query_next_hash(int argc, VALUE *argv, VALUE self) {
 
 /* Returns the next 1 or more rows from the associated query's result set as an
  * array.
- * 
+ *
  * If no row count is given, a single row is returned. If a row count is given,
  * an array containing up to the `row_count` rows is returned. If `row_count` is
  * -1, all rows are returned. If the end of the result set has been reached,
  * `nil` is returned.
- * 
+ *
  * If a block is given, rows are passed to the block and self is returned.
  *
  * @overload next_ary()
@@ -241,12 +248,12 @@ VALUE Query_next_ary(int argc, VALUE *argv, VALUE self) {
 /* Returns the next 1 or more rows from the associated query's result set as an
  * single values. If the result set contains more than one column an error is
  * raised.
- * 
+ *
  * If no row count is given, a single row is returned. If a row count is given,
  * an array containing up to the `row_count` rows is returned. If `row_count` is
  * -1, all rows are returned. If the end of the result set has been reached,
  * `nil` is returned.
- * 
+ *
  * If a block is given, rows are passed to the block and self is returned.
  *
  * @overload next_ary()
@@ -261,7 +268,7 @@ VALUE Query_next_single_column(int argc, VALUE *argv, VALUE self) {
 }
 
 /* Returns all rows in the associated query's result set as hashes.
- * 
+ *
  * @overload to_a()
  *   @return [Array<Hash>] all rows
  * @overload to_a_hash
@@ -274,7 +281,7 @@ VALUE Query_to_a_hash(VALUE self) {
 }
 
 /* Returns all rows in the associated query's result set as arrays.
- * 
+ *
  * @return [Array<Array>] all rows
  */
 VALUE Query_to_a_ary(VALUE self) {
@@ -285,7 +292,7 @@ VALUE Query_to_a_ary(VALUE self) {
 
 /* Returns all rows in the associated query's result set as single values. If
  * the result set contains more than one column an error is raised.
- * 
+ *
  * @return [Array<Object>] all rows
  */
 VALUE Query_to_a_single_column(VALUE self) {
@@ -297,7 +304,7 @@ VALUE Query_to_a_single_column(VALUE self) {
 /* Iterates through the result set, passing each row to the given block as a
  * hash. If no block is given, returns a `Extralite::Iterator` instance in hash
  * mode.
- * 
+ *
  * @return [Extralite::Query, Extralite::Iterator] self or an iterator if no block is given
  */
 VALUE Query_each_hash(VALUE self) {
@@ -311,7 +318,7 @@ VALUE Query_each_hash(VALUE self) {
 /* Iterates through the result set, passing each row to the given block as an
  * array. If no block is given, returns a `Extralite::Iterator` instance in
  * array mode.
- * 
+ *
  * @return [Extralite::Query, Extralite::Iterator] self or an iterator if no block is given
  */
 VALUE Query_each_ary(VALUE self) {
@@ -326,7 +333,7 @@ VALUE Query_each_ary(VALUE self) {
  * single value. If the result set contains more than one column an error is
  * raised. If no block is given, returns a `Extralite::Iterator` instance in
  * single column mode.
- * 
+ *
  * @return [Extralite::Query, Extralite::Iterator] self or an iterator if no block is given
  */
 VALUE Query_each_single_column(VALUE self) {
@@ -366,30 +373,213 @@ VALUE Query_execute(int argc, VALUE *argv, VALUE self) {
   return Query_perform_next(self, ALL_ROWS, safe_query_changes);
 }
 
-/* Executes the query for each set of parameters in the given array. Parameters
- * can be specified as either an array (for unnamed parameters) or a hash (for
- * named parameters). Returns the number of changes effected. This method is
- * designed for inserting multiple records.
+/* call-seq:
+ *   query << [...] -> query
+ *   query << { ... } -> query
+ *
+ * Runs the with the given parameters, returning the total changes effected.
+ * This method should be used for data- or schema-manipulation queries.
+ *
+ * Query parameters to be bound to placeholders in the query can be specified as
+ * a list of values or as a hash mapping parameter names to values. When
+ * parameters are given as an array, the query should specify parameters using
+ * `?`:
+ *
+ *     query = db.prepare('update foo set x = ? where y = ?')
+ *     query << [42, 43]
+ *
+ * Named placeholders are specified using `:`. The placeholder values are
+ * specified using a hash, where keys are either strings are symbols. String
+ * keys can include or omit the `:` prefix. The following are equivalent:
+ *
+ *     query = db.prepare('update foo set x = :bar')
+ *     query << { bar: 42 }
+ *     query << { 'bar' => 42 }
+ *     query << { ':bar' => 42 }
+ */
+VALUE Query_execute_chevrons(VALUE self, VALUE params) {
+  Query_execute(1, &params, self);
+  return self;
+}
+
+/* call-seq:
+ *   query.batch_execute(params_array) -> changes
+ *   query.batch_execute(enumerable) -> changes
+ *   query.batch_execute(callable) -> changes
+ *
+ * Executes the query for each set of parameters in the paramter source. If an
+ * enumerable is given, it is iterated and each of its values is used as the
+ * parameters for running the query. If a callable is given, it is called
+ * repeatedly and each of its return values is used as the parameters, until nil
+ * is returned.
+ * 
+ * Returns the number of changes effected. This method is designed for inserting
+ * multiple records.
  *
  *     query = db.prepare('insert into foo values (?, ?, ?)')
  *     records = [
  *       [1, 2, 3],
  *       [4, 5, 6]
  *     ]
- *     query.execute_multi(records)
+ *     query.batch_execute(records)
+ * 
+ *     source = [
+ *       [1, 2, 3],
+ *       [4, 5, 6]
+ *     ]
+ *     query.batch_execute { records.shift }
  *
- * @param parameters [Array<Array, Hash>] array of parameters to run query with
+ * @param parameters [Array<Array, Hash>, Enumerable, Enumerator, Callable] array of parameters to run query with
  * @return [Integer] number of changes effected
  */
-VALUE Query_execute_multi(VALUE self, VALUE parameters) {
+VALUE Query_batch_execute(VALUE self, VALUE parameters) {
   Query_t *query = self_to_query(self);
   if (query->closed) rb_raise(cError, "Query is closed");
 
   if (!query->stmt)
     prepare_single_stmt(query->sqlite3_db, &query->stmt, query->sql);
 
-  query_ctx ctx = { self, query->sqlite3_db, query->stmt, parameters, QUERY_MODE(QUERY_MULTI_ROW), ALL_ROWS };
-  return safe_execute_multi(&ctx);
+  query_ctx ctx = QUERY_CTX(
+    self,
+    query->db_struct,
+    query->stmt,
+    parameters,
+    QUERY_MODE(QUERY_MULTI_ROW),
+    ALL_ROWS
+  );
+  return safe_batch_execute(&ctx);
+}
+
+/* call-seq:
+ *   query.batch_query(sql, params_array) -> rows
+ *   query.batch_query(sql, enumerable) -> rows
+ *   query.batch_query(sql, callable) -> rows
+ *   query.batch_query(sql, params_array) { |rows| ... } -> changes
+ *   query.batch_query(sql, enumerable) { |rows| ... } -> changes
+ *   query.batch_query(sql, callable) { |rows| ... } -> changes
+ *
+ * Executes the prepared query for each list of parameters in the given paramter
+ * source. If a block is given, it is called with the resulting rows for each
+ * invocation of the query, and the total number of changes is returned.
+ * Otherwise, an array containing the resulting rows for each invocation is
+ * returned.
+ *
+ *     q = db.prepare('insert into foo values (?, ?) returning bar, baz')
+ *     records = [
+ *       [1, 2],
+ *       [3, 4]
+ *     ]
+ *     q.batch_query(records)
+ *     #=> [{ bar: 1, baz: 2 }, { bar: 3, baz: 4}]
+ * *
+ * @param sql [String] query SQL
+ * @param parameters [Array<Array, Hash>, Enumerable, Enumerator, Callable] parameters to run query with
+ * @return [Array<Hash>, Integer] Total number of changes effected
+ */
+VALUE Query_batch_query(VALUE self, VALUE parameters) {
+  Query_t *query = self_to_query(self);
+  if (query->closed) rb_raise(cError, "Query is closed");
+
+  if (!query->stmt)
+    prepare_single_stmt(query->sqlite3_db, &query->stmt, query->sql);
+
+  query_ctx ctx = QUERY_CTX(
+    self,
+    query->db_struct,
+    query->stmt,
+    parameters,
+    QUERY_MODE(QUERY_MULTI_ROW),
+    ALL_ROWS
+  );
+  return safe_batch_query(&ctx);
+}
+
+/* call-seq:
+ *   query.batch_query_ary(sql, params_array) -> rows
+ *   query.batch_query_ary(sql, enumerable) -> rows
+ *   query.batch_query_ary(sql, callable) -> rows
+ *   query.batch_query_ary(sql, params_array) { |rows| ... } -> changes
+ *   query.batch_query_ary(sql, enumerable) { |rows| ... } -> changes
+ *   query.batch_query_ary(sql, callable) { |rows| ... } -> changes
+ *
+ * Executes the prepared query for each list of parameters in the given paramter
+ * source. If a block is given, it is called with the resulting rows for each
+ * invocation of the query, and the total number of changes is returned.
+ * Otherwise, an array containing the resulting rows for each invocation is
+ * returned. Rows are represented as arrays.
+ *
+ *     q = db.prepare('insert into foo values (?, ?) returning bar, baz')
+ *     records = [
+ *       [1, 2],
+ *       [3, 4]
+ *     ]
+ *     q.batch_query_ary(records)
+ *     #=> [{ bar: 1, baz: 2 }, { bar: 3, baz: 4}]
+ * *
+ * @param sql [String] query SQL
+ * @param parameters [Array<Array, Hash>, Enumerable, Enumerator, Callable] parameters to run query with
+ * @return [Array<Hash>, Integer] Total number of changes effected
+ */
+VALUE Query_batch_query_ary(VALUE self, VALUE parameters) {
+  Query_t *query = self_to_query(self);
+  if (query->closed) rb_raise(cError, "Query is closed");
+
+  if (!query->stmt)
+    prepare_single_stmt(query->sqlite3_db, &query->stmt, query->sql);
+
+  query_ctx ctx = QUERY_CTX(
+    self,
+    query->db_struct,
+    query->stmt,
+    parameters,
+    QUERY_MODE(QUERY_MULTI_ROW),
+    ALL_ROWS
+  );
+  return safe_batch_query_ary(&ctx);
+}
+
+/* call-seq:
+ *   query.batch_query_single_column(sql, params_array) -> rows
+ *   query.batch_query_single_column(sql, enumerable) -> rows
+ *   query.batch_query_single_column(sql, callable) -> rows
+ *   query.batch_query_single_column(sql, params_array) { |rows| ... } -> changes
+ *   query.batch_query_single_column(sql, enumerable) { |rows| ... } -> changes
+ *   query.batch_query_single_column(sql, callable) { |rows| ... } -> changes
+ *
+ * Executes the prepared query for each list of parameters in the given paramter
+ * source. If a block is given, it is called with the resulting rows for each
+ * invocation of the query, and the total number of changes is returned.
+ * Otherwise, an array containing the resulting rows for each invocation is
+ * returned. Rows are represented as single values.
+ *
+ *     q = db.prepare('insert into foo values (?, ?) returning bar, baz')
+ *     records = [
+ *       [1, 2],
+ *       [3, 4]
+ *     ]
+ *     q.batch_query_single_column(records)
+ *     #=> [{ bar: 1, baz: 2 }, { bar: 3, baz: 4}]
+ * *
+ * @param sql [String] query SQL
+ * @param parameters [Array<Array, Hash>, Enumerable, Enumerator, Callable] parameters to run query with
+ * @return [Array<Hash>, Integer] Total number of changes effected
+ */
+VALUE Query_batch_query_single_column(VALUE self, VALUE parameters) {
+  Query_t *query = self_to_query(self);
+  if (query->closed) rb_raise(cError, "Query is closed");
+
+  if (!query->stmt)
+    prepare_single_stmt(query->sqlite3_db, &query->stmt, query->sql);
+
+  query_ctx ctx = QUERY_CTX(
+    self,
+    query->db_struct,
+    query->stmt,
+    parameters,
+    QUERY_MODE(QUERY_MULTI_ROW),
+    ALL_ROWS
+  );
+  return safe_batch_query_single_column(&ctx);
 }
 
 /* Returns the database associated with the query.
@@ -405,7 +595,7 @@ VALUE Query_database(VALUE self) {
 }
 
 /* Returns the SQL string for the query.
- * 
+ *
  * @return [String] SQL string
  */
 VALUE Query_sql(VALUE self) {
@@ -414,7 +604,7 @@ VALUE Query_sql(VALUE self) {
 }
 
 /* Returns the column names for the query without running it.
- * 
+ *
  * @return [Array<Symbol>] column names
  */
 VALUE Query_columns(VALUE self) {
@@ -423,8 +613,21 @@ VALUE Query_columns(VALUE self) {
   return Query_perform_next(self, ALL_ROWS, safe_query_columns);
 }
 
+/* call-seq:
+ *   query.clone -> copy
+ *   query.dup -> copy
+ *
+ * Returns a new query instance for the same SQL as the original query.
+ *
+ * @return [Extralite::Query] copy of query
+ */
+VALUE Query_clone(VALUE self) {
+  Query_t *query = self_to_query(self);
+  return rb_funcall(cQuery, ID_new, 2, query->db, query->sql);
+}
+
 /* Closes the query. Attempting to run a closed query will raise an error.
- * 
+ *
  * @return [Extralite::Query] self
  */
 VALUE Query_close(VALUE self) {
@@ -438,7 +641,7 @@ VALUE Query_close(VALUE self) {
 }
 
 /* Returns true if the query is closed.
- * 
+ *
  * @return [boolean] true if query is closed
  */
 VALUE Query_closed_p(VALUE self) {
@@ -449,7 +652,7 @@ VALUE Query_closed_p(VALUE self) {
 /* Returns the current [status
  * value](https://sqlite.org/c3ref/c_stmtstatus_counter.html) for the given op.
  * To reset the value, pass true as reset.
- * 
+ *
  * @overload status(op)
  *   @param op [Integer] status op
  *   @return [Integer] current status value for the given op
@@ -486,7 +689,7 @@ VALUE Query_inspect(VALUE self) {
     rb_str_cat2(sql, "...");
   }
   sql = rb_funcall(sql, ID_inspect, 0);
-    
+
   RB_GC_GUARD(sql);
   return rb_sprintf("#<%"PRIsVALUE":%p %"PRIsVALUE">", cname, (void*)self, sql);
 }
@@ -501,8 +704,10 @@ void Init_ExtraliteQuery(void) {
   rb_define_method(cQuery, "close", Query_close, 0);
   rb_define_method(cQuery, "closed?", Query_closed_p, 0);
   rb_define_method(cQuery, "columns", Query_columns, 0);
+  rb_define_method(cQuery, "clone", Query_clone, 0);
   rb_define_method(cQuery, "database", Query_database, 0);
   rb_define_method(cQuery, "db", Query_database, 0);
+  rb_define_method(cQuery, "dup", Query_clone, 0);
 
   rb_define_method(cQuery, "each", Query_each_hash, 0);
   rb_define_method(cQuery, "each_ary", Query_each_ary, 0);
@@ -511,7 +716,11 @@ void Init_ExtraliteQuery(void) {
 
   rb_define_method(cQuery, "eof?", Query_eof_p, 0);
   rb_define_method(cQuery, "execute", Query_execute, -1);
-  rb_define_method(cQuery, "execute_multi", Query_execute_multi, 1);
+  rb_define_method(cQuery, "<<", Query_execute_chevrons, 1);
+  rb_define_method(cQuery, "batch_execute", Query_batch_execute, 1);
+  rb_define_method(cQuery, "batch_query", Query_batch_query, 1);
+  rb_define_method(cQuery, "batch_query_ary", Query_batch_query_ary, 1);
+  rb_define_method(cQuery, "batch_query_single_column", Query_batch_query_single_column, 1);
   rb_define_method(cQuery, "initialize", Query_initialize, 2);
   rb_define_method(cQuery, "inspect", Query_inspect, 0);