class PG::Tuple
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
Returns field name.
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); }
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; }
# 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
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; }
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.
A string 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); }
# File lib/pg/tuple.rb, line 13 def has_key?(key) field_map.has_key?(key) end
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); }
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
# File lib/pg/tuple.rb, line 18 def keys field_names || field_map.keys.freeze end
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); }
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]); }