Class: PG::Result

Inherits:
Object
  • Object
show all
Includes:
Enumerable, Constants
Defined in:
ext/pg_result.c,
lib/pg/result.rb,
ext/pg_result.c

Overview

******************************************************************

The class to represent the query result tuples (rows).
An instance of this class is created as the result of every query.
You may need to invoke the #clear method of the instance when finished with
the result for better memory performance.

Example:
   require 'pg'
   conn = PGconn.open(:dbname => 'test')
   res  = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
   res.getvalue(0,0) # '1'
   res[0]['b']       # '2'
   res[0]['c']       # nil

Constant Summary

Constants included from Constants

Constants::CONNECTION_AUTH_OK, Constants::CONNECTION_AWAITING_RESPONSE, Constants::CONNECTION_BAD, Constants::CONNECTION_MADE, Constants::CONNECTION_NEEDED, Constants::CONNECTION_OK, Constants::CONNECTION_SETENV, Constants::CONNECTION_SSL_STARTUP, Constants::CONNECTION_STARTED, Constants::INVALID_OID, Constants::INV_READ, Constants::INV_WRITE, Constants::InvalidOid, Constants::PGRES_BAD_RESPONSE, Constants::PGRES_COMMAND_OK, Constants::PGRES_COPY_BOTH, Constants::PGRES_COPY_IN, Constants::PGRES_COPY_OUT, Constants::PGRES_EMPTY_QUERY, Constants::PGRES_FATAL_ERROR, Constants::PGRES_NONFATAL_ERROR, Constants::PGRES_POLLING_FAILED, Constants::PGRES_POLLING_OK, Constants::PGRES_POLLING_READING, Constants::PGRES_POLLING_WRITING, Constants::PGRES_SINGLE_TUPLE, Constants::PGRES_TUPLES_OK, Constants::PG_DIAG_COLUMN_NAME, Constants::PG_DIAG_CONSTRAINT_NAME, Constants::PG_DIAG_CONTEXT, Constants::PG_DIAG_DATATYPE_NAME, Constants::PG_DIAG_INTERNAL_POSITION, Constants::PG_DIAG_INTERNAL_QUERY, Constants::PG_DIAG_MESSAGE_DETAIL, Constants::PG_DIAG_MESSAGE_HINT, Constants::PG_DIAG_MESSAGE_PRIMARY, Constants::PG_DIAG_SCHEMA_NAME, Constants::PG_DIAG_SEVERITY, Constants::PG_DIAG_SOURCE_FILE, Constants::PG_DIAG_SOURCE_FUNCTION, Constants::PG_DIAG_SOURCE_LINE, Constants::PG_DIAG_SQLSTATE, Constants::PG_DIAG_STATEMENT_POSITION, Constants::PG_DIAG_TABLE_NAME, Constants::PQERRORS_DEFAULT, Constants::PQERRORS_TERSE, Constants::PQERRORS_VERBOSE, Constants::PQPING_NO_ATTEMPT, Constants::PQPING_NO_RESPONSE, Constants::PQPING_OK, Constants::PQPING_REJECT, Constants::PQTRANS_ACTIVE, Constants::PQTRANS_IDLE, Constants::PQTRANS_INERROR, Constants::PQTRANS_INTRANS, Constants::PQTRANS_UNKNOWN, Constants::SEEK_CUR, Constants::SEEK_END, Constants::SEEK_SET

Instance Method Summary collapse

Instance Method Details

#[](n) ⇒ Hash

Returns tuple n as a hash.

Returns:

  • (Hash)

780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
# File 'ext/pg_result.c', line 780

static VALUE
pgresult_aref(VALUE self, VALUE index)
{
	t_pg_result *this = pgresult_get_this_safe(self);
	int tuple_num = NUM2INT(index);
	int field_num;
	VALUE fname;
	VALUE tuple;

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

	tuple = rb_hash_new();
	for ( field_num = 0; field_num < PQnfields(this->pgresult); field_num++ ) {
		fname = rb_tainted_str_new2( PQfname(this->pgresult,field_num) );
		PG_ENCODING_SET_NOCHECK(fname, ENCODING_GET(self));
		rb_hash_aset( tuple, fname, this->p_typemap->typecast_result_value(self, tuple_num, field_num) );
	}
	return tuple;
}

#autoclose?Boolean

Returns true if the underlying C struct will be cleared automatically by libpq. Elsewise the result is cleared by PG::Result#clear or by the GC when it's no longer in use.

Returns:

  • (Boolean)

Returns:

  • (Boolean)

171
172
173
174
175
176
# File 'ext/pg_result.c', line 171

VALUE
pgresult_autoclear_p( VALUE self )
{
	t_pg_result *this = pgresult_get_this(self);
	return this->autoclear ? Qtrue : Qfalse;
}

#checknil Also known as: check_result

Raises appropriate exception if PG::Result is in a bad state.

Returns:

  • (nil)

72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
# File 'ext/pg_result.c', line 72

VALUE
pg_result_check( VALUE self )
{
	t_pg_result *this = pgresult_get_this(self);
	VALUE error, exception, klass;
	PGconn *conn = pg_get_pgconn(this->connection);
	char * sqlstate;

	if(this->pgresult == NULL)
	{
		error = rb_str_new2( PQerrorMessage(conn) );
	}
	else
	{
		switch (PQresultStatus(this->pgresult))
		{
		case PGRES_TUPLES_OK:
		case PGRES_COPY_OUT:
		case PGRES_COPY_IN:
#ifdef HAVE_CONST_PGRES_COPY_BOTH
		case PGRES_COPY_BOTH:
#endif
#ifdef HAVE_CONST_PGRES_SINGLE_TUPLE
		case PGRES_SINGLE_TUPLE:
#endif
		case PGRES_EMPTY_QUERY:
		case PGRES_COMMAND_OK:
			return self;
		case PGRES_BAD_RESPONSE:
		case PGRES_FATAL_ERROR:
		case PGRES_NONFATAL_ERROR:
			error = rb_str_new2( PQresultErrorMessage(this->pgresult) );
			break;
		default:
			error = rb_str_new2( "internal error : unknown result status." );
		}
	}

	PG_ENCODING_SET_NOCHECK( error, ENCODING_GET(self) );

	sqlstate = PQresultErrorField( this->pgresult, PG_DIAG_SQLSTATE );
	klass = lookup_error_class( sqlstate );
	exception = rb_exc_new3( klass, error );
	rb_iv_set( exception, "@connection", this->connection );
	rb_iv_set( exception, "@result", this->pgresult ? self : Qnil );
	rb_exc_raise( exception );

	/* Not reached */
	return self;
}

#clearnil

Clears the PG::Result object as the result of the query.

If PG::Result#autoclear? is true then the result is marked as cleared and the underlying C struct will be cleared automatically by libpq.

Returns:

  • (nil)

140
141
142
143
144
145
146
147
148
# File 'ext/pg_result.c', line 140

VALUE
pg_result_clear(VALUE self)
{
	t_pg_result *this = pgresult_get_this(self);
	if( !this->autoclear )
		PQclear(pgresult_get(self));
	this->pgresult = NULL;
	return Qnil;
}

#cleared?Boolean

Returns true if the backend result memory has been free'd.

Returns:

  • (Boolean)

Returns:

  • (Boolean)

156
157
158
159
160
161
# File 'ext/pg_result.c', line 156

VALUE
pgresult_cleared_p( VALUE self )
{
	t_pg_result *this = pgresult_get_this(self);
	return this->pgresult ? Qfalse : Qtrue;
}

#cmd_statusString

Returns the status string of the last query command.

Returns:

  • (String)

725
726
727
728
729
730
731
# File 'ext/pg_result.c', line 725

static VALUE
pgresult_cmd_status(VALUE self)
{
	VALUE ret = rb_tainted_str_new2(PQcmdStatus(pgresult_get(self)));
	PG_ENCODING_SET_NOCHECK(ret, ENCODING_GET(self));
	return ret;
}

#cmd_tuplesInteger Also known as: cmdtuples

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

If the SQL command that generated the PG::Result was not one of:

  • INSERT

  • UPDATE

  • DELETE

  • MOVE

  • FETCH

or if no tuples were affected, 0 is returned.

Returns:

  • (Integer)

747
748
749
750
751
752
753
# File 'ext/pg_result.c', line 747

static VALUE
pgresult_cmd_tuples(VALUE self)
{
	long n;
	n = strtol(PQcmdTuples(pgresult_get(self)),NULL, 10);
	return INT2NUM(n);
}

#column_values(n) ⇒ Array

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

Returns:

  • (Array)

890
891
892
893
894
895
# File 'ext/pg_result.c', line 890

static VALUE
pgresult_column_values(VALUE self, VALUE index)
{
	int col = NUM2INT( index );
	return make_column_result_array( self, col );
}

#each {|tuple| ... } ⇒ Object

Invokes block for each tuple in the result set.

Yields:

  • (tuple)

925
926
927
928
929
930
931
932
933
934
935
# File 'ext/pg_result.c', line 925

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;
}

#each_row {|row| ... } ⇒ Object

Yields each row of the result. The row is a list of column values.

Yields:

  • (row)

807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
# File 'ext/pg_result.c', line 807

static VALUE
pgresult_each_row(VALUE self)
{
	t_pg_result *this = pgresult_get_this_safe(self);
	int row;
	int field;
	int num_rows = PQntuples(this->pgresult);
	int num_fields = PQnfields(this->pgresult);

	for ( row = 0; row < num_rows; row++ ) {
		VALUE new_row = rb_ary_new2(num_fields);

		/* populate the row */
		for ( field = 0; field < num_fields; field++ ) {
			rb_ary_store( new_row, field, this->p_typemap->typecast_result_value(self, row, field) );
		}
		rb_yield( new_row );
	}

	return Qnil;
}

#error_field(fieldcode) ⇒ String Also known as: result_error_field

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 PG::Error => err
    p [
        err.result.error_field( PG::Result::PG_DIAG_SEVERITY ),
        err.result.error_field( PG::Result::PG_DIAG_SQLSTATE ),
        err.result.error_field( PG::Result::PG_DIAG_MESSAGE_PRIMARY ),
        err.result.error_field( PG::Result::PG_DIAG_MESSAGE_DETAIL ),
        err.result.error_field( PG::Result::PG_DIAG_MESSAGE_HINT ),
        err.result.error_field( PG::Result::PG_DIAG_STATEMENT_POSITION ),
        err.result.error_field( PG::Result::PG_DIAG_INTERNAL_POSITION ),
        err.result.error_field( PG::Result::PG_DIAG_INTERNAL_QUERY ),
        err.result.error_field( PG::Result::PG_DIAG_CONTEXT ),
        err.result.error_field( PG::Result::PG_DIAG_SOURCE_FILE ),
        err.result.error_field( PG::Result::PG_DIAG_SOURCE_LINE ),
        err.result.error_field( PG::Result::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"]

Returns:

  • (String)

370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
# File 'ext/pg_result.c', line 370

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 );
		PG_ENCODING_SET_NOCHECK( ret, ENCODING_GET(self ));
	}

	return ret;
}

#error_messageString Also known as: result_error_message

Returns the error message of the command as a string.

Returns:

  • (String)

316
317
318
319
320
321
322
# File 'ext/pg_result.c', line 316

static VALUE
pgresult_error_message(VALUE self)
{
	VALUE ret = rb_tainted_str_new2(PQresultErrorMessage(pgresult_get(self)));
	PG_ENCODING_SET_NOCHECK(ret, ENCODING_GET(self));
	return ret;
}

#fformat(column_number) ⇒ Fixnum

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

Raises ArgumentError if column_number is out of range.

Returns:

  • (Fixnum)

527
528
529
530
531
532
533
534
535
536
537
# File 'ext/pg_result.c', line 527

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

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

Returns:

  • (Array)

905
906
907
908
909
910
911
912
913
914
915
916
# File 'ext/pg_result.c', line 905

static VALUE
pgresult_field_values( VALUE self, VALUE field )
{
	PGresult *result = pgresult_get( self );
	const char *fieldname = StringValueCStr( 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 );
}

#fieldsArray

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

Returns:

  • (Array)

943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
# File 'ext/pg_result.c', line 943

static VALUE
pgresult_fields(VALUE self)
{
	PGresult *result = pgresult_get( self );
	int n = PQnfields( result );
	VALUE fields = rb_ary_new2( n );
	int i;

	for ( i = 0; i < n; i++ ) {
		VALUE val = rb_tainted_str_new2(PQfname(result, i));
		PG_ENCODING_SET_NOCHECK(val, ENCODING_GET(self));
		rb_ary_store( fields, i, val );
	}

	return fields;
}

#fmod(column_number) ⇒ Object

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.


577
578
579
580
581
582
583
584
585
586
587
588
589
590
# File 'ext/pg_result.c', line 577

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

Returns the name of the column corresponding to index.

Returns:

  • (String)

416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
# File 'ext/pg_result.c', line 416

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));
	PG_ENCODING_SET_NOCHECK(fname, ENCODING_GET(self));
	return fname;
}

#fnumber(name) ⇒ Fixnum

Returns the index of the field specified by the string name. The given name is treated like an identifier in an SQL command, that is, it is downcased unless double-quoted. For example, given a query result generated from the SQL command:

result = conn.exec( %{SELECT 1 AS FOO, 2 AS "BAR"} )

we would have the results:

result.fname( 0 )            # => "foo"
result.fname( 1 )            # => "BAR"
result.fnumber( "FOO" )      # => 0
result.fnumber( "foo" )      # => 0
result.fnumber( "BAR" )      # => ArgumentError
result.fnumber( %{"BAR"} )   # => 1

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

Returns:

  • (Fixnum)

455
456
457
458
459
460
461
462
463
464
465
466
467
# File 'ext/pg_result.c', line 455

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

	Check_Type(name, T_STRING);

	n = PQfnumber(pgresult_get(self), StringValueCStr(name));
	if (n == -1) {
		rb_raise(rb_eArgError,"Unknown field: %s", StringValueCStr(name));
	}
	return INT2FIX(n);
}

#fsize(index) ⇒ Object

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

602
603
604
605
606
607
608
609
610
611
612
613
# File 'ext/pg_result.c', line 602

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) ⇒ Integer

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.

Returns:

  • (Integer)

479
480
481
482
483
484
485
486
487
488
489
490
491
# File 'ext/pg_result.c', line 479

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 UINT2NUM(n);
}

#ftablecol(column_number) ⇒ Fixnum

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.

Returns:

  • (Fixnum)

503
504
505
506
507
508
509
510
511
512
513
514
515
516
# File 'ext/pg_result.c', line 503

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) ⇒ Integer

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.

Returns:

  • (Integer)

557
558
559
560
561
562
563
564
565
566
# File 'ext/pg_result.c', line 557

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 UINT2NUM(PQftype(result, i));
}

#getisnull(tuple_position, field_position) ⇒ Boolean

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

Returns:

  • (Boolean)

645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
# File 'ext/pg_result.c', line 645

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

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

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

Returns:

  • (Fixnum)

670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
# File 'ext/pg_result.c', line 670

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) ⇒ Object

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


623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
# File 'ext/pg_result.c', line 623

static VALUE
pgresult_getvalue(VALUE self, VALUE tup_num, VALUE field_num)
{
	t_pg_result *this = pgresult_get_this_safe(self);
	int i = NUM2INT(tup_num);
	int j = NUM2INT(field_num);

	if(i < 0 || i >= PQntuples(this->pgresult)) {
		rb_raise(rb_eArgError,"invalid tuple number %d", i);
	}
	if(j < 0 || j >= PQnfields(this->pgresult)) {
		rb_raise(rb_eArgError,"invalid field number %d", j);
	}
	return this->p_typemap->typecast_result_value(self, i, j);
}

#inspectObject


18
19
20
21
22
# File 'lib/pg/result.rb', line 18

def inspect
	str = self.to_s
	str[-1,0] = " status=#{res_status(result_status)} ntuples=#{ntuples} nfields=#{nfields} cmd_tuples=#{cmd_tuples}"
	str
end

#map_types!(type_map) ⇒ Object

Apply a type map for all value retrieving methods.

type_map: a PG::TypeMap instance.

See PG::BasicTypeMapForResults


13
14
15
16
# File 'lib/pg/result.rb', line 13

def map_types!(type_map)
	self.type_map = type_map
	self
end

#nfieldsInteger Also known as: num_fields

Returns the number of columns in the query result.

Returns:

  • (Integer)

404
405
406
407
408
# File 'ext/pg_result.c', line 404

static VALUE
pgresult_nfields(VALUE self)
{
	return INT2NUM(PQnfields(pgresult_get(self)));
}

#nparamsFixnum

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

Returns:

  • (Fixnum)

694
695
696
697
698
699
700
701
# File 'ext/pg_result.c', line 694

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

	result = pgresult_get(self);
	return INT2FIX(PQnparams(result));
}

#ntuplesFixnum Also known as: num_tuples

Returns the number of tuples in the query result.

Returns:

  • (Fixnum)

392
393
394
395
396
# File 'ext/pg_result.c', line 392

static VALUE
pgresult_ntuples(VALUE self)
{
	return INT2FIX(PQntuples(pgresult_get(self)));
}

#oid_valueInteger

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

Returns:

  • (Integer)

762
763
764
765
766
767
768
769
770
# File 'ext/pg_result.c', line 762

static VALUE
pgresult_oid_value(VALUE self)
{
	Oid n = PQoidValue(pgresult_get(self));
	if (n == InvalidOid)
		return Qnil;
	else
		return UINT2NUM(n);
}

#paramtype(param_number) ⇒ Oid

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

Returns:

  • (Oid)

710
711
712
713
714
715
716
717
# File 'ext/pg_result.c', line 710

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

	result = pgresult_get(self);
	return UINT2NUM(PQparamtype(result,NUM2INT(param_number)));
}

#res_status(status) ⇒ String

Returns the string representation of status status.

Returns:

  • (String)

302
303
304
305
306
307
308
# File 'ext/pg_result.c', line 302

static VALUE
pgresult_res_status(VALUE self, VALUE status)
{
	VALUE ret = rb_tainted_str_new2(PQresStatus(NUM2INT(status)));
	PG_ENCODING_SET_NOCHECK(ret, ENCODING_GET(self));
	return ret;
}

#result_statusFixnum

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

  • PGRES_COPY_BOTH

Returns:

  • (Fixnum)

289
290
291
292
293
# File 'ext/pg_result.c', line 289

static VALUE
pgresult_result_status(VALUE self)
{
	return INT2FIX(PQresultStatus(pgresult_get(self)));
}

#type_mapObject

Returns the TypeMap that is currently set for type casts of result values to ruby objects.

Returns either:

  • a kind of PG::TypeMap or

  • nil - when no type map is set.


1011
1012
1013
1014
1015
1016
1017
# File 'ext/pg_result.c', line 1011

static VALUE
pgresult_type_map_get(VALUE self)
{
	t_pg_result *this = pgresult_get_this(self);

	return this->typemap;
}

#type_map=(typemap) ⇒ Object

Set the TypeMap that is used for type casts of result values to ruby objects.

All value retrieval methods will respect the type map and will do the type casts from PostgreSQL's wire format to Ruby objects on the fly, according to the rules and decoders defined in the given typemap.

typemap can be:

  • a kind of PG::TypeMap

  • nil - to type cast all result values to String.


975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
# File 'ext/pg_result.c', line 975

static VALUE
pgresult_type_map_set(VALUE self, VALUE typemap)
{
	t_pg_result *this = pgresult_get_this(self);

	if( NIL_P(typemap) ){
		this->p_typemap = DATA_PTR( pg_default_typemap );
	} else {
		t_typemap *p_typemap;

		if ( !rb_obj_is_kind_of(typemap, rb_cTypeMap) ) {
			rb_raise( rb_eTypeError, "wrong argument type %s (expected kind of PG::TypeMap)",
					rb_obj_classname( typemap ) );
		}
		Data_Get_Struct(typemap, t_typemap, p_typemap);

		typemap = p_typemap->fit_to_result( typemap, self );
		this->p_typemap = DATA_PTR( typemap );
	}

	this->typemap = typemap;

	return typemap;
}

#valuesArray

Returns all tuples as an array of arrays.

Returns:

  • (Array)

835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
# File 'ext/pg_result.c', line 835

static VALUE
pgresult_values(VALUE self)
{
	t_pg_result *this = pgresult_get_this_safe(self);
	int row;
	int field;
	int num_rows = PQntuples(this->pgresult);
	int num_fields = PQnfields(this->pgresult);
	VALUE results = rb_ary_new2( num_rows );

	for ( row = 0; row < num_rows; row++ ) {
		VALUE new_row = rb_ary_new2(num_fields);

		/* populate the row */
		for ( field = 0; field < num_fields; field++ ) {
			rb_ary_store( new_row, field, this->p_typemap->typecast_result_value(self, row, field) );
		}
		rb_ary_store( results, row, new_row );
	}

	return results;
}