class PG::Result

Public Instance Methods

res[ n ] → Hash click to toggle source

Returns tuple n as a hash.

static VALUE
pgresult_aref(VALUE self, VALUE index)
{
        PGresult *result = pgresult_get(self);
        int tuple_num = NUM2INT(index);
        int field_num;
        VALUE fname,val;
        VALUE tuple;

        if ( tuple_num < 0 || tuple_num >= PQntuples(result) )
                rb_raise( rb_eIndexError, "Index %d is out of range", tuple_num );

        tuple = rb_hash_new();
        for ( field_num = 0; field_num < PQnfields(result); field_num++ ) {
                fname = rb_tainted_str_new2( PQfname(result,field_num) );
                ASSOCIATE_INDEX(fname, self);
                if ( PQgetisnull(result, tuple_num, field_num) ) {
                        rb_hash_aset( tuple, fname, Qnil );
                }
                else {
                        val = rb_tainted_str_new( PQgetvalue(result, tuple_num, field_num ),
                                                  PQgetlength(result, tuple_num, field_num) );

#ifdef M17N_SUPPORTED
                        /* associate client encoding for text format only */
                        if ( 0 == PQfformat(result, field_num) ) {
                                ASSOCIATE_INDEX( val, self );
                        } else {
                                rb_enc_associate( val, rb_ascii8bit_encoding() );
                        }
#endif

                        rb_hash_aset( tuple, fname, val );
                }
        }
        return tuple;
}
clear() → nil click to toggle source

Clears the PGresult object as the result of the query.

VALUE
pg_result_clear(VALUE self)
{
        PQclear(pgresult_get(self));
        DATA_PTR(self) = NULL;
        return Qnil;
}
cmd_status() → String click to toggle source

Returns the status string of the last query command.

static VALUE
pgresult_cmd_status(VALUE self)
{
        VALUE ret = rb_tainted_str_new2(PQcmdStatus(pgresult_get(self)));
        ASSOCIATE_INDEX(ret, self);
        return ret;
}
cmd_tuples() → Fixnum click to toggle source

Returns the number of tuples (rows) affected by the SQL command.

If the SQL command that generated the PGresult was not one of:

  • INSERT

  • UPDATE

  • DELETE

  • MOVE

  • FETCH

or if no tuples were affected, 0 is returned.

static VALUE
pgresult_cmd_tuples(VALUE self)
{
        long n;
        n = strtol(PQcmdTuples(pgresult_get(self)),NULL, 10);
        return INT2NUM(n);
}
Also aliased as: cmdtuples
cmdtuples() click to toggle source
Alias for: cmd_tuples
column_values( n ) → array click to toggle source

Returns an Array of the values from the nth column of each tuple in the result.

static VALUE
pgresult_column_values(VALUE self, VALUE index)
{
        int col = NUM2INT( index );
        return make_column_result_array( self, col );
}
each{ |tuple| ... } click to toggle source

Invokes block for each tuple in the result set.

static VALUE
pgresult_each(VALUE self)
{
        PGresult *result = pgresult_get(self);
        int tuple_num;

        for(tuple_num = 0; tuple_num < PQntuples(result); tuple_num++) {
                rb_yield(pgresult_aref(self, INT2NUM(tuple_num)));
        }
        return self;
}
error_field(fieldcode) → String click to toggle source

Returns the individual field of an error.

fieldcode is one of:

  • PG_DIAG_SEVERITY

  • PG_DIAG_SQLSTATE

  • PG_DIAG_MESSAGE_PRIMARY

  • PG_DIAG_MESSAGE_DETAIL

  • PG_DIAG_MESSAGE_HINT

  • PG_DIAG_STATEMENT_POSITION

  • PG_DIAG_INTERNAL_POSITION

  • PG_DIAG_INTERNAL_QUERY

  • PG_DIAG_CONTEXT

  • PG_DIAG_SOURCE_FILE

  • PG_DIAG_SOURCE_LINE

  • PG_DIAG_SOURCE_FUNCTION

An example:

begin
    conn.exec( "SELECT * FROM nonexistant_table" )
rescue PGError => err
    p [
        result.error_field( PGresult::PG_DIAG_SEVERITY ),
        result.error_field( PGresult::PG_DIAG_SQLSTATE ),
        result.error_field( PGresult::PG_DIAG_MESSAGE_PRIMARY ),
        result.error_field( PGresult::PG_DIAG_MESSAGE_DETAIL ),
        result.error_field( PGresult::PG_DIAG_MESSAGE_HINT ),
        result.error_field( PGresult::PG_DIAG_STATEMENT_POSITION ),
        result.error_field( PGresult::PG_DIAG_INTERNAL_POSITION ),
        result.error_field( PGresult::PG_DIAG_INTERNAL_QUERY ),
        result.error_field( PGresult::PG_DIAG_CONTEXT ),
        result.error_field( PGresult::PG_DIAG_SOURCE_FILE ),
        result.error_field( PGresult::PG_DIAG_SOURCE_LINE ),
        result.error_field( PGresult::PG_DIAG_SOURCE_FUNCTION ),
    ]
end

Outputs:

["ERROR", "42P01", "relation \"nonexistant_table\" does not exist", nil, nil, 
 "15", nil, nil, nil, "path/to/parse_relation.c", "857", "parserOpenTable"]
static VALUE
pgresult_error_field(VALUE self, VALUE field)
{
        PGresult *result = pgresult_get( self );
        int fieldcode = NUM2INT( field );
        char * fieldstr = PQresultErrorField( result, fieldcode );
        VALUE ret = Qnil;

        if ( fieldstr ) {
                ret = rb_tainted_str_new2( fieldstr );
                ASSOCIATE_INDEX( ret, self );
        }

        return ret;
}
Also aliased as: result_error_field
error_message() → String click to toggle source

Returns the error message of the command as a string.

static VALUE
pgresult_error_message(VALUE self)
{
        VALUE ret = rb_tainted_str_new2(PQresultErrorMessage(pgresult_get(self)));
        ASSOCIATE_INDEX(ret, self);
        return ret;
}
Also aliased as: result_error_message
fformat( column_number ) → Fixnum click to toggle source

Returns the format (0 for text, 1 for binary) of column column_number.

Raises ArgumentError if column_number is out of range.

static VALUE
pgresult_fformat(VALUE self, VALUE column_number)
{
        PGresult *result = pgresult_get(self);
        int fnumber = NUM2INT(column_number);
        if (fnumber < 0 || fnumber >= PQnfields(result)) {
                rb_raise(rb_eArgError, "Column number is out of range: %d", 
                        fnumber);
        }
        return INT2FIX(PQfformat(result, fnumber));
}
field_values( field ) → array click to toggle source

Returns an Array of the values from the given field of each tuple in the result.

static VALUE
pgresult_field_values( VALUE self, VALUE field )
{
        PGresult *result = pgresult_get( self );
        const char *fieldname = RSTRING_PTR( field );
        int fnum = PQfnumber( result, fieldname );

        if ( fnum < 0 )
                rb_raise( rb_eIndexError, "no such field '%s' in result", fieldname );

        return make_column_result_array( self, fnum );
}
fields() → Array click to toggle source

Returns an array of Strings representing the names of the fields in the result.

static VALUE
pgresult_fields(VALUE self)
{
        PGresult *result;
        VALUE ary;
        int n, i;

        result = pgresult_get(self);
        n = PQnfields(result);
        ary = rb_ary_new2(n);
        for (i=0;i<n;i++) {
                VALUE val = rb_tainted_str_new2(PQfname(result, i));
                ASSOCIATE_INDEX(val, self);
                rb_ary_push(ary, val);
        }
        return ary;
}
fmod( column_number ) click to toggle source

Returns the type modifier associated with column column_number. See the ftype method for an example of how to use this.

Raises an ArgumentError if column_number is out of range.

static VALUE
pgresult_fmod(VALUE self, VALUE column_number)
{
        PGresult *result = pgresult_get(self);
        int fnumber = NUM2INT(column_number);
        int modifier;
        if (fnumber < 0 || fnumber >= PQnfields(result)) {
                rb_raise(rb_eArgError, "Column number is out of range: %d", 
                        fnumber);
        }
        modifier = PQfmod(result,fnumber);

        return INT2NUM(modifier);
}
fname( index ) → String click to toggle source

Returns the name of the column corresponding to index.

static VALUE
pgresult_fname(VALUE self, VALUE index)
{
        VALUE fname;
        PGresult *result;
        int i = NUM2INT(index);

        result = pgresult_get(self);
        if (i < 0 || i >= PQnfields(result)) {
                rb_raise(rb_eArgError,"invalid field number %d", i);
        }
        fname = rb_tainted_str_new2(PQfname(result, i));
        ASSOCIATE_INDEX(fname, self);
        return fname;
}
fnumber( name ) → Fixnum click to toggle source

Returns the index of the field specified by the string name.

Raises an ArgumentError if the specified name isn’t one of the field names; raises a TypeError if name is not a String.

static VALUE
pgresult_fnumber(VALUE self, VALUE name)
{
        int n;

        Check_Type(name, T_STRING);

        n = PQfnumber(pgresult_get(self), StringValuePtr(name));
        if (n == -1) {
                rb_raise(rb_eArgError,"Unknown field: %s", StringValuePtr(name));
        }
        return INT2FIX(n);
}
fsize( index ) click to toggle source

Returns the size of the field type in bytes. Returns -1 if the field is variable sized.

res = conn.exec("SELECT myInt, myVarChar50 FROM foo")
res.size(0) => 4
res.size(1) => -1
static VALUE
pgresult_fsize(VALUE self, VALUE index)
{
        PGresult *result;
        int i = NUM2INT(index);

        result = pgresult_get(self);
        if (i < 0 || i >= PQnfields(result)) {
                rb_raise(rb_eArgError,"invalid field number %d", i);
        }
        return INT2NUM(PQfsize(result, i));
}
ftable( column_number ) → Fixnum click to toggle source

Returns the Oid of the table from which the column column_number was fetched.

Raises ArgumentError if column_number is out of range or if the Oid is undefined for that column.

static VALUE
pgresult_ftable(VALUE self, VALUE column_number)
{
        Oid n ;
        int col_number = NUM2INT(column_number);
        PGresult *pgresult = pgresult_get(self);

        if( col_number < 0 || col_number >= PQnfields(pgresult)) 
                rb_raise(rb_eArgError,"Invalid column index: %d", col_number);

        n = PQftable(pgresult, col_number);
        return INT2FIX(n);
}
ftablecol( column_number ) → Fixnum click to toggle source

Returns the column number (within its table) of the table from which the column column_number is made up.

Raises ArgumentError if column_number is out of range or if the column number from its table is undefined for that column.

static VALUE
pgresult_ftablecol(VALUE self, VALUE column_number)
{
        int col_number = NUM2INT(column_number);
        PGresult *pgresult = pgresult_get(self);

        int n;

        if( col_number < 0 || col_number >= PQnfields(pgresult)) 
                rb_raise(rb_eArgError,"Invalid column index: %d", col_number);

        n = PQftablecol(pgresult, col_number);
        return INT2FIX(n);
}
ftype( column_number ) click to toggle source

Returns the data type associated with column_number.

The integer returned is the internal OID number (in PostgreSQL) of the type. To get a human-readable value for the type, use the returned OID and the field’s fmod value with the format_type() SQL function:

# Get the type of the second column of the result 'res'
typename = conn.
  exec( "SELECT format_type($1,$2)", [res.ftype(1), res.fmod(1)] ).
  getvalue( 0, 0 )

Raises an ArgumentError if column_number is out of range.

static VALUE
pgresult_ftype(VALUE self, VALUE index)
{
        PGresult* result = pgresult_get(self);
        int i = NUM2INT(index);
        if (i < 0 || i >= PQnfields(result)) {
                rb_raise(rb_eArgError, "invalid field number %d", i);
        }
        return INT2NUM(PQftype(result, i));
}
getisnull(tuple_position, field_position) → boolean click to toggle source

Returns true if the specified value is nil; false otherwise.

static VALUE
pgresult_getisnull(VALUE self, VALUE tup_num, VALUE field_num)
{
        PGresult *result;
        int i = NUM2INT(tup_num);
        int j = NUM2INT(field_num);

        result = pgresult_get(self);
        if (i < 0 || i >= PQntuples(result)) {
                rb_raise(rb_eArgError,"invalid tuple number %d", i);
        }
        if (j < 0 || j >= PQnfields(result)) {
                rb_raise(rb_eArgError,"invalid field number %d", j);
        }
        return PQgetisnull(result, i, j) ? Qtrue : Qfalse;
}
getlength( tup_num, field_num ) → Fixnum click to toggle source

Returns the (String) length of the field in bytes.

Equivalent to res.value(tup_num,field_num).length.

static VALUE
pgresult_getlength(VALUE self, VALUE tup_num, VALUE field_num)
{
        PGresult *result;
        int i = NUM2INT(tup_num);
        int j = NUM2INT(field_num);

        result = pgresult_get(self);
        if (i < 0 || i >= PQntuples(result)) {
                rb_raise(rb_eArgError,"invalid tuple number %d", i);
        }
        if (j < 0 || j >= PQnfields(result)) {
                rb_raise(rb_eArgError,"invalid field number %d", j);
        }
        return INT2FIX(PQgetlength(result, i, j));
}
getvalue( tup_num, field_num ) click to toggle source

Returns the value in tuple number tup_num, field field_num, or nil if the field is NULL.

static VALUE
pgresult_getvalue(VALUE self, VALUE tup_num, VALUE field_num)
{
        VALUE ret;
        PGresult *result;
        int i = NUM2INT(tup_num);
        int j = NUM2INT(field_num);

        result = pgresult_get(self);
        if(i < 0 || i >= PQntuples(result)) {
                rb_raise(rb_eArgError,"invalid tuple number %d", i);
        }
        if(j < 0 || j >= PQnfields(result)) {
                rb_raise(rb_eArgError,"invalid field number %d", j);
        }
        if(PQgetisnull(result, i, j))
                return Qnil;
        ret = rb_tainted_str_new(PQgetvalue(result, i, j), 
                                PQgetlength(result, i, j));
        ASSOCIATE_INDEX(ret, self);
        return ret;
}
nfields() → Fixnum click to toggle source

Returns the number of columns in the query result.

static VALUE
pgresult_nfields(VALUE self)
{
        return INT2NUM(PQnfields(pgresult_get(self)));
}
Also aliased as: num_fields
nparams() → Fixnum click to toggle source

Returns the number of parameters of a prepared statement. Only useful for the result returned by conn.describePrepared

static VALUE
pgresult_nparams(VALUE self)
{
        PGresult *result;

        result = pgresult_get(self);
        return INT2FIX(PQnparams(result));
}
ntuples() → Fixnum click to toggle source

Returns the number of tuples in the query result.

static VALUE
pgresult_ntuples(VALUE self)
{
        return INT2FIX(PQntuples(pgresult_get(self)));
}
Also aliased as: num_tuples
num_fields() click to toggle source
Alias for: nfields
num_tuples() click to toggle source
Alias for: ntuples
oid_value() → Fixnum click to toggle source

Returns the oid of the inserted row if applicable, otherwise nil.

static VALUE
pgresult_oid_value(VALUE self)
{
        Oid n = PQoidValue(pgresult_get(self));
        if (n == InvalidOid)
                return Qnil;
        else
                return INT2FIX(n);
}
paramtype( param_number ) → Oid click to toggle source

Returns the Oid of the data type of parameter param_number. Only useful for the result returned by conn.describePrepared

static VALUE
pgresult_paramtype(VALUE self, VALUE param_number)
{
        PGresult *result;

        result = pgresult_get(self);
        return INT2FIX(PQparamtype(result,NUM2INT(param_number)));
}
res_status( status ) → String click to toggle source

Returns the string representation of status status.

static VALUE
pgresult_res_status(VALUE self, VALUE status)
{
        VALUE ret = rb_tainted_str_new2(PQresStatus(NUM2INT(status)));
        ASSOCIATE_INDEX(ret, self);
        return ret;
}
result_error_field(p1) click to toggle source
Alias for: error_field
result_error_message() click to toggle source
Alias for: error_message
result_status() → Fixnum click to toggle source

Returns the status of the query. The status value is one of:

  • PGRES_EMPTY_QUERY

  • PGRES_COMMAND_OK

  • PGRES_TUPLES_OK

  • PGRES_COPY_OUT

  • PGRES_COPY_IN

  • PGRES_BAD_RESPONSE

  • PGRES_NONFATAL_ERROR

  • PGRES_FATAL_ERROR

static VALUE
pgresult_result_status(VALUE self)
{
        return INT2FIX(PQresultStatus(pgresult_get(self)));
}
values → Array click to toggle source

Returns all tuples as an array of arrays.

static VALUE
pgresult_values(VALUE self)
{
        PGresult* result = (PGresult*) pgresult_get(self);
        int row;
        int field;
        int num_rows = PQntuples(result);
        int num_fields = PQnfields(result);
        VALUE ary = rb_ary_new2(num_rows);

        for ( row = 0; row < num_rows; row++ ) {
                /* create new row */
                VALUE new_row = rb_ary_new2(num_fields);

                /* add to return array */
                rb_ary_store( ary, row, new_row );

                /* populate it */
                for ( field = 0; field < num_fields; field++ ) {
                        if ( PQgetisnull(result, row, field) ) {
                                rb_ary_store( new_row, field, Qnil );
                        }
                        else {
                                VALUE val = rb_tainted_str_new( PQgetvalue(result, row, field), 
                                                                PQgetlength(result, row, field) );

#ifdef M17N_SUPPORTED
                                /* associate client encoding for text format only */
                                if ( 0 == PQfformat(result, field) ) {
                                        ASSOCIATE_INDEX( val, self );
                                } else {
                                        rb_enc_associate( val, rb_ascii8bit_encoding() );
                                }
#endif

                                rb_ary_store( new_row, field, val );
                        }
                }
        }
        return ary;
}