Tuple

class
Superclass
rb_cObject
Included Modules
Enumerable

The class to represent one query result tuple (row). An instance of this class can be created by PG::Result#tuple .

All field values of the tuple are retrieved on demand from the underlying PGresult object and converted to a Ruby object. Subsequent access to the same field returns the same object, since they are cached when materialized. Each PG::Tuple holds a reference to the related PG::Result object, but gets detached, when all fields are materialized.

Example:

require 'pg'
conn = PG.connect(:dbname => 'test')
res  = conn.exec('VALUES(1,2), (3,4)')
t0 = res.tuple(0)  # => #<PG::Tuple column1: "1", column2: "2">
t1 = res.tuple(1)  # => #<PG::Tuple column1: "3", column2: "4">
t1[0]  # => "3"
t1["column2"]  # => "4"

Public Instance Methods

anchor
tup[ key ] → value

Returns a field value by either column index or column name.

An integer key is interpreted as column index. Negative values of index count from the end of the array.

Depending on Result#field_name_type= a string or symbol key is interpreted as column name.

If the key can’t be found, it returns nil .

static VALUE
pg_tuple_aref(VALUE self, VALUE key)
{
        VALUE index;
        int field_num;
        t_pg_tuple *this = pg_tuple_get_this(self);

        switch(rb_type(key)){
                case T_FIXNUM:
                case T_BIGNUM:
                        field_num = NUM2INT(key);
                        if ( field_num < 0 )
                                field_num = this->num_fields + field_num;
                        if ( field_num < 0 || field_num >= this->num_fields )
                                return Qnil;
                        break;
                default:
                        index = rb_hash_aref(this->field_map, key);
                        if( index == Qnil ) return Qnil;
                        field_num = NUM2INT(index);
        }

        return pg_tuple_materialize_field(this, field_num);
}
anchor
each{ |key, value| ... }

Invokes block for each field name and value in the tuple.

static VALUE
pg_tuple_each(VALUE self)
{
        t_pg_tuple *this = pg_tuple_get_this(self);
        VALUE field_names;

        RETURN_SIZED_ENUMERATOR(self, 0, NULL, pg_tuple_num_fields_for_enum);

        field_names = pg_tuple_get_field_names(this);

        if( field_names == Qfalse ){
                rb_hash_foreach(this->field_map, pg_tuple_yield_key_value, (VALUE)this);
        } else {
                int i;
                for( i = 0; i < this->num_fields; i++ ){
                        VALUE value = pg_tuple_materialize_field(this, i);
                        rb_yield_values(2, RARRAY_AREF(field_names, i), value);
                }
        }

        pg_tuple_detach(this);
        return self;
}
anchor
each_key(&block)
# File lib/pg/tuple.rb, line 22
def each_key(&block)
        if fn=field_names
                fn.each(&block)
        else
                field_map.each_key(&block)
        end
end
anchor
each_value{ |value| ... }

Invokes block for each field value in the tuple.

static VALUE
pg_tuple_each_value(VALUE self)
{
        t_pg_tuple *this = pg_tuple_get_this(self);
        int field_num;

        RETURN_SIZED_ENUMERATOR(self, 0, NULL, pg_tuple_num_fields_for_enum);

        for(field_num = 0; field_num < this->num_fields; field_num++) {
                VALUE value = pg_tuple_materialize_field(this, field_num);
                rb_yield(value);
        }

        pg_tuple_detach(this);
        return self;
}
anchor
fetch(key) → value
fetch(key, default) → value
fetch(key) { |key| block } → value

Returns a field value by either column index or column name.

An integer key is interpreted as column index. Negative values of index count from the end of the array.

Depending on Result#field_name_type= a string or symbol key is interpreted as column name.

If the key can’t be found, there are several options: With no other arguments, it will raise a IndexError exception; if default is given, then that will be returned; if the optional code block is specified, then that will be run and its result returned.

static VALUE
pg_tuple_fetch(int argc, VALUE *argv, VALUE self)
{
        VALUE key;
        long block_given;
        VALUE index;
        int field_num;
        t_pg_tuple *this = pg_tuple_get_this(self);

        rb_check_arity(argc, 1, 2);
        key = argv[0];

        block_given = rb_block_given_p();
        if (block_given && argc == 2) {
                rb_warn("block supersedes default value argument");
        }

        switch(rb_type(key)){
                case T_FIXNUM:
                case T_BIGNUM:
                        field_num = NUM2INT(key);
                        if ( field_num < 0 )
                                field_num = this->num_fields + field_num;
                        if ( field_num < 0 || field_num >= this->num_fields ){
                                if (block_given) return rb_yield(key);
                                if (argc == 1) rb_raise( rb_eIndexError, "Index %d is out of range", field_num );
                                return argv[1];
                        }
                        break;
                default:
                        index = rb_hash_aref(this->field_map, key);

                        if (index == Qnil) {
                                if (block_given) return rb_yield(key);
                                if (argc == 1) rb_raise( rb_eKeyError, "column not found" );
                                return argv[1];
                        }

                        field_num = NUM2INT(index);
        }

        return pg_tuple_materialize_field(this, field_num);
}
anchor
has_key?(key)
# File lib/pg/tuple.rb, line 13
def has_key?(key)
        field_map.has_key?(key)
end
Also aliased as: key?
anchor
index(key) → integer

Returns the field number which matches the given column name.

static VALUE
pg_tuple_index(VALUE self, VALUE key)
{
        t_pg_tuple *this = pg_tuple_get_this(self);
        return rb_hash_aref(this->field_map, key);
}
anchor
inspect()

Return a String representation of the object suitable for debugging.

# File lib/pg/tuple.rb, line 9
def inspect
        "#<#{self.class} #{self.map{|k,v| "#{k}: #{v.inspect}" }.join(", ") }>"
end
anchor
key?(key)
Alias for: has_key?
anchor
keys()
# File lib/pg/tuple.rb, line 18
def keys
        field_names || field_map.keys.freeze
end
anchor
length → integer

Returns number of fields of this tuple.

static VALUE
pg_tuple_length(VALUE self)
{
        t_pg_tuple *this = pg_tuple_get_this(self);
        return INT2NUM(this->num_fields);
}
Also aliased as: size
anchor
size()

Returns number of fields of this tuple.

Alias for: length
anchor
values → Array

Returns the values of this tuple as Array. +res.tuple(i).values+ is equal to +res.tuple_values(i)+ .

static VALUE
pg_tuple_values(VALUE self)
{
        t_pg_tuple *this = pg_tuple_get_this(self);

        pg_tuple_materialize(this);
        return rb_ary_new4(this->num_fields, &this->values[0]);
}