class SQLite3::Statement - RDoc Documentation

Source

static VALUE
bind_param(VALUE self, VALUE key, VALUE value)
{
    sqlite3StmtRubyPtr ctx;
    int status;
    int index;

    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    switch (TYPE(key)) {
        case T_SYMBOL:
            key = rb_funcall(key, rb_intern("to_s"), 0);
        case T_STRING:
            if (RSTRING_PTR(key)[0] != ':') { key = rb_str_plus(rb_str_new2(":"), key); }
            index = sqlite3_bind_parameter_index(ctx->st, StringValuePtr(key));
            break;
        default:
            index = (int)NUM2INT(key);
    }

    if (index == 0) {
        rb_raise(rb_path2class("SQLite3::Exception"), "no such bind parameter");
    }

    switch (TYPE(value)) {
        case T_STRING:
            if (CLASS_OF(value) == cSqlite3Blob
                    || rb_enc_get_index(value) == rb_ascii8bit_encindex()
               ) {
                status = sqlite3_bind_blob(
                             ctx->st,
                             index,
                             (const char *)StringValuePtr(value),
                             (int)RSTRING_LEN(value),
                             SQLITE_TRANSIENT
                         );
            } else {


                if (UTF16_LE_P(value) || UTF16_BE_P(value)) {
                    status = sqlite3_bind_text16(
                                 ctx->st,
                                 index,
                                 (const char *)StringValuePtr(value),
                                 (int)RSTRING_LEN(value),
                                 SQLITE_TRANSIENT
                             );
                } else {
                    if (!UTF8_P(value) || !USASCII_P(value)) {
                        value = rb_str_encode(value, rb_enc_from_encoding(rb_utf8_encoding()), 0, Qnil);
                    }
                    status = sqlite3_bind_text(
                                 ctx->st,
                                 index,
                                 (const char *)StringValuePtr(value),
                                 (int)RSTRING_LEN(value),
                                 SQLITE_TRANSIENT
                             );
                }
            }
            break;
        case T_BIGNUM: {
            sqlite3_int64 num64;
            if (bignum_to_int64(value, &num64)) {
                status = sqlite3_bind_int64(ctx->st, index, num64);
                break;
            }
        }
        case T_FLOAT:
            status = sqlite3_bind_double(ctx->st, index, NUM2DBL(value));
            break;
        case T_FIXNUM:
            status = sqlite3_bind_int64(ctx->st, index, (sqlite3_int64)FIX2LONG(value));
            break;
        case T_NIL:
            status = sqlite3_bind_null(ctx->st, index);
            break;
        default:
            rb_raise(rb_eRuntimeError, "can't prepare %s",
                     rb_class2name(CLASS_OF(value)));
            break;
    }

    CHECK(sqlite3_db_handle(ctx->st), status);

    return self;
}

Binds value to the named (or positional) placeholder. If param is a Fixnum, it is treated as an index for a positional placeholder. Otherwise it is used as the name of the placeholder to bind to.

See also bind_params.

bind_parameter_count

Source

static VALUE
bind_parameter_count(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    return INT2NUM(sqlite3_bind_parameter_count(ctx->st));
}

Return the number of bind parameters

clear_bindings!

Source

static VALUE
clear_bindings_bang(VALUE self)
{
    sqlite3StmtRubyPtr ctx;

    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    sqlite3_clear_bindings(ctx->st);

    ctx->done_p = 0;

    return self;
}

Resets the statement. This is typically done internally, though it might occasionally be necessary to manually reset the statement.

close

Source

static VALUE
sqlite3_rb_close(VALUE self)
{
    sqlite3StmtRubyPtr ctx;

    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_OPEN_STMT(ctx);

    sqlite3_finalize(ctx->st);
    ctx->st = NULL;

    return self;
}

Closes the statement by finalizing the underlying statement handle. The statement must not be used after being closed.

closed?

Source

static VALUE
closed_p(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    if (!ctx->st) { return Qtrue; }

    return Qfalse;
}

Returns true if the statement has been closed.

column_count

Source

static VALUE
column_count(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    return INT2NUM(sqlite3_column_count(ctx->st));
}

Returns the number of columns to be returned for this statement

column_decltype(index)

Source

static VALUE
column_decltype(VALUE self, VALUE index)
{
    sqlite3StmtRubyPtr ctx;
    const char *name;

    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    name = sqlite3_column_decltype(ctx->st, (int)NUM2INT(index));

    if (name) { return rb_str_new2(name); }
    return Qnil;
}

Get the column type at index. 0 based.

column_name(index)

Source

static VALUE
column_name(VALUE self, VALUE index)
{
    sqlite3StmtRubyPtr ctx;
    const char *name;

    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    name = sqlite3_column_name(ctx->st, (int)NUM2INT(index));

    VALUE ret = Qnil;

    if (name) {
        ret = interned_utf8_cstr(name);
    }
    return ret;
}

Get the column name at index. 0 based.

database_name(column_index)

Source

static VALUE
database_name(VALUE self, VALUE index)
{
    sqlite3StmtRubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    return SQLITE3_UTF8_STR_NEW2(
               sqlite3_column_database_name(ctx->st, NUM2INT(index)));
}

Return the database name for the column at column_index

done?

Source

static VALUE
done_p(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    if (ctx->done_p) { return Qtrue; }
    return Qfalse;
}

returns true if all rows have been returned.

expanded_sql

Source

static VALUE
get_expanded_sql(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    char *expanded_sql;
    VALUE rb_expanded_sql;

    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    expanded_sql = sqlite3_expanded_sql(ctx->st);
    rb_expanded_sql = rb_obj_freeze(SQLITE3_UTF8_STR_NEW2(expanded_sql));
    sqlite3_free(expanded_sql);

    return rb_expanded_sql;
}

Returns the SQL statement used to create this prepared statement, but with bind parameters substituted in to the statement.

memused

Source

static VALUE
memused(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    return INT2NUM(sqlite3_stmt_status(ctx->st, SQLITE_STMTSTATUS_MEMUSED, 0));
}

Return the approximate number of bytes of heap memory used to store the prepared statement

named_params

Source

static VALUE
named_params(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    int param_count = sqlite3_bind_parameter_count(ctx->st);
    VALUE params = rb_ary_new2(param_count);

    // The first host parameter has an index of 1, not 0.
    for (int i = 1; i <= param_count; i++) {
        const char *name = sqlite3_bind_parameter_name(ctx->st, i);
        // We ignore positional and anonymous parameters, and also null values, since there can be
        // gaps in the list.
        if (name && *name != '?') {
            VALUE param = interned_utf8_cstr(name + 1);
            rb_ary_push(params, param);
        }
    }
    return rb_obj_freeze(params);
}

Return the list of named parameters in the statement. This returns a frozen array of strings (without the leading prefix character). The values of this list can be used to bind parameters to the statement using bind_param. Positional (?NNN) and anonymous (?) parameters are excluded.

reset!

Source

static VALUE
reset_bang(VALUE self)
{
    sqlite3StmtRubyPtr ctx;

    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    sqlite3_reset(ctx->st);

    ctx->done_p = 0;

    return self;
}

Resets the statement. This is typically done internally, though it might occasionally be necessary to manually reset the statement.

sql

Source

static VALUE
get_sql(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    return rb_obj_freeze(SQLITE3_UTF8_STR_NEW2(sqlite3_sql(ctx->st)));
}

Returns the SQL statement used to create this prepared statement

step ()

Source

static VALUE
step(VALUE self)
{
    sqlite3StmtRubyPtr ctx;
    sqlite3_stmt *stmt;
    int value, length;
    VALUE list;
    rb_encoding *internal_encoding;

    TypedData_Get_Struct(self, sqlite3StmtRuby, &statement_type, ctx);

    REQUIRE_LIVE_DB(ctx);
    REQUIRE_OPEN_STMT(ctx);

    if (ctx->done_p) { return Qnil; }

    internal_encoding = rb_default_internal_encoding();

    stmt = ctx->st;

    value = sqlite3_step(stmt);
    if (rb_errinfo() != Qnil) {
        /* some user defined function was invoked as a callback during step and
         * it raised an exception that has been suppressed until step returns.
         * Now re-raise it. */
        VALUE exception = rb_errinfo();
        rb_set_errinfo(Qnil);
        rb_exc_raise(exception);
    }

    length = sqlite3_column_count(stmt);
    list = rb_ary_new2((long)length);

    switch (value) {
        case SQLITE_ROW: {
            int i;
            for (i = 0; i < length; i++) {
                VALUE val;

                switch (sqlite3_column_type(stmt, i)) {
                    case SQLITE_INTEGER:
                        val = LL2NUM(sqlite3_column_int64(stmt, i));
                        break;
                    case SQLITE_FLOAT:
                        val = rb_float_new(sqlite3_column_double(stmt, i));
                        break;
                    case SQLITE_TEXT: {
                        val = rb_utf8_str_new(
                                  (const char *)sqlite3_column_text(stmt, i),
                                  (long)sqlite3_column_bytes(stmt, i)
                              );
                        if (internal_encoding) {
                            val = rb_str_export_to_enc(val, internal_encoding);
                        }
                        rb_obj_freeze(val);
                    }
                    break;
                    case SQLITE_BLOB: {
                        val = rb_str_new(
                                  (const char *)sqlite3_column_blob(stmt, i),
                                  (long)sqlite3_column_bytes(stmt, i)
                              );
                        rb_obj_freeze(val);
                    }
                    break;
                    case SQLITE_NULL:
                        val = Qnil;
                        break;
                    default:
                        rb_raise(rb_eRuntimeError, "bad type");
                }

                rb_ary_store(list, (long)i, val);
            }
        }
        break;
        case SQLITE_DONE:
            ctx->done_p = 1;
            return Qnil;
            break;
        default:
            sqlite3_reset(stmt);
            ctx->done_p = 0;
            CHECK(sqlite3_db_handle(ctx->st), value);
    }

    rb_obj_freeze(list);

    return list;
}