pg 1.6.1 → 1.6.3

data/ext/pg_result.c

@@ -12,6 +12,7 @@ static VALUE sym_symbol, sym_string, sym_static_symbol;
 static VALUE pgresult_type_map_set( VALUE, VALUE );
 static t_pg_result *pgresult_get_this( VALUE );
 static t_pg_result *pgresult_get_this_safe( VALUE );
+static void ensure_init_for_tuple(VALUE self);
 
 #if defined(HAVE_PQRESULTMEMORYSIZE)
 
@@ -114,7 +115,6 @@ pgresult_gc_mark( void *_this )
 
 	rb_gc_mark_movable( this->connection );
 	rb_gc_mark_movable( this->typemap );
-	rb_gc_mark_movable( this->tuple_hash );
 	rb_gc_mark_movable( this->field_map );
 
 	for( i=0; i < this->nfields; i++ ){
@@ -130,7 +130,6 @@ pgresult_gc_compact( void *_this )
 
 	pg_gc_location( this->connection );
 	pg_gc_location( this->typemap );
-	pg_gc_location( this->tuple_hash );
 	pg_gc_location( this->field_map );
 
 	for( i=0; i < this->nfields; i++ ){
@@ -212,7 +211,6 @@ pg_new_result2(PGresult *result, VALUE rb_pgconn)
 	this->typemap = pg_typemap_all_strings;
 	this->p_typemap = RTYPEDDATA_DATA( this->typemap );
 	this->nfields = -1;
-	this->tuple_hash = Qnil;
 	this->field_map = Qnil;
 	this->flags = 0;
 	self = TypedData_Wrap_Struct(rb_cPGresult, &pgresult_type, this);
@@ -396,6 +394,7 @@ pg_result_freeze(VALUE self)
 {
 	t_pg_result *this = pgresult_get_this(self);
 
+	ensure_init_for_tuple(self);
 	RB_OBJ_WRITE(self, &this->connection, Qnil);
 	return rb_call_super(0, NULL);
 }
@@ -513,20 +512,46 @@ static void pgresult_init_fnames(VALUE self)
  *
  * The class to represent the query result tuples (rows).
  * An instance of this class is created as the result of every query.
- * All result rows and columns are stored in a memory block attached to the PG::Result object.
- * Whenever a value is accessed it is casted to a Ruby object by the assigned #type_map .
+ * All result rows and columns are stored in an immutable memory block attached to the PG::Result object unless streaming is used.
  *
- * Since pg-1.1 the amount of memory in use by a PG::Result object is estimated and passed to ruby's garbage collector.
- * You can invoke the #clear method to force deallocation of memory of the instance when finished with the result for better memory performance.
- *
- * Example:
+ * A PG::Result has various ways to retrieve the result data:
  *    require 'pg'
- *    conn = PG.connect(: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
+ *    conn = PG.connect(dbname: 'test')
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.num_fields       # 3
+ *    res.num_tuples       # 1
+ *    res.fname(2)         # "c"
+ *    res.fields           # ["a", "b", "c"]
+ *    res.getvalue(0,0)    # '1'
+ *    res[0]               # {"a" => "1", "b" => "2", "c" => "3"}
+ *    res.tuple_values(0)  # ["1", "2", nil]
+ *    res.tuple(0)         # #<PG::Tuple a: "1", b: "2", c: nil>
+ *    res.values           # [["1", "2", nil]]
+ *    res.field_values(:a) # ["1"]
+ *    res.column_values(1) # ["2"]
+ *    res.each.first       # {"a" => "1", "b" => "2", "c" => nil}
+ *    res.each_row.first   # ["1", "2", nil]
+ *
+ * Whenever a value is accessed it is casted to a Ruby object by the assigned #type_map which is PG::TypeMapAllStrings by default.
+ * Similarly field names can be retrieved either as strings (default) or as symbols which can be switched per #field_name_type= .
+ *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.type_map = PG::TypeMapByColumn.new([PG::TextDecoder::Integer.new]*3)
+ *    res.field_name_type = :symbol
+ *    res.fname(2)         # :c
+ *    res.fields           # [:a, :b, :c]
+ *    res.getvalue(0,0)    # 1
+ *    res[0]               # {a: 1, b: 2, c: nil}
+ *    res.tuple_values(0)  # [1, 2, nil]
+ *    res.tuple(0)         # #<PG::Tuple a: 1, b: 2, c: nil>
+ *    res.values           # [[1, 2, nil]]
+ *    res.field_values(:a) # [1]
+ *    res.column_values(1) # [2]
+ *    res.each.first       # {a: 1, b: 2, c: nil}
+ *    res.each_row.first   # [1, 2, nil]
  *
+ * Since pg-1.1 the amount of memory in use by a PG::Result object is estimated and passed to ruby's garbage collector.
+ * You can invoke the #clear method to force deallocation of memory of the instance when finished with the result for better memory performance.
  */
 
 /**************************************************************************
@@ -617,7 +642,7 @@ pgresult_error_message(VALUE self)
  * call-seq:
  *    res.verbose_error_message( verbosity, show_context ) -> String
  *
- * Returns a reformatted version of the error message associated with a PGresult object.
+ * Returns a reformatted version of the error message associated with the PG::Result object.
  *
  */
 static VALUE
@@ -705,6 +730,10 @@ pgresult_error_field(VALUE self, VALUE field)
  *    res.ntuples() -> Integer
  *
  * Returns the number of tuples in the query result.
+ *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.ntuples          # 1
+ *    res.num_tuples       # 1
  */
 static VALUE
 pgresult_ntuples(VALUE self)
@@ -723,6 +752,9 @@ pgresult_ntuples_for_enum(VALUE self, VALUE args, VALUE eobj)
  *    res.nfields() -> Integer
  *
  * Returns the number of columns in the query result.
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.nfields          # 3
+ *    res.num_fields       # 3
  */
 static VALUE
 pgresult_nfields(VALUE self)
@@ -734,9 +766,9 @@ pgresult_nfields(VALUE self)
  * call-seq:
  *    res.binary_tuples() -> Integer
  *
- * Returns 1 if the PGresult contains binary data and 0 if it contains text data.
+ * Returns 1 if the PG::Result contains binary data and 0 if it contains text data.
  *
- * This function is deprecated (except for its use in connection with COPY), because it is possible for a single PGresult to contain text data in some columns and binary data in others.
+ * This function is deprecated (except for its use in connection with COPY), because it is possible for a single PG::Result to contain text data in some columns and binary data in others.
  * Result#fformat is preferred. binary_tuples returns 1 only if all columns of the result are binary (format 1).
  */
 static VALUE
@@ -752,6 +784,8 @@ pgresult_binary_tuples(VALUE self)
  * Returns the name of the column corresponding to _index_.
  * Depending on #field_name_type= it's a String or Symbol.
  *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.fname(2)       # "c"
  */
 static VALUE
 pgresult_fname(VALUE self, VALUE index)
@@ -1122,6 +1156,9 @@ pgresult_oid_value(VALUE self)
  *    res[ n ] -> Hash
  *
  * Returns tuple _n_ as a hash.
+ *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res[0]               # {"a" => "1", "b" => "2", "c" => "3"}
  */
 static VALUE
 pgresult_aref(VALUE self, VALUE index)
@@ -1138,16 +1175,11 @@ pgresult_aref(VALUE self, VALUE index)
 	if ( tuple_num < 0 || tuple_num >= num_tuples )
 		rb_raise( rb_eIndexError, "Index %d is out of range", tuple_num );
 
-	/* We reuse the Hash of the previous output for larger row counts.
-	 * This is somewhat faster than populating an empty Hash object. */
-	tuple = NIL_P(this->tuple_hash) ? rb_hash_new() : this->tuple_hash;
+	tuple = rb_hash_new_capa(this->nfields);
 	for ( field_num = 0; field_num < this->nfields; field_num++ ) {
 		VALUE val = this->p_typemap->funcs.typecast_result_value(this->p_typemap, self, tuple_num, field_num);
 		rb_hash_aset( tuple, this->fnames[field_num], val );
 	}
-	/* Store a copy of the filled hash for use at the next row. */
-	if( num_tuples > 10 )
-		RB_OBJ_WRITE(self, &this->tuple_hash, rb_hash_dup(tuple));
 
 	return tuple;
 }
@@ -1156,7 +1188,10 @@ pgresult_aref(VALUE self, VALUE index)
  * call-seq:
  *    res.each_row { |row| ... }
  *
- * Yields each row of the result. The row is a list of column values.
+ * Yields an Array object for each row in the result.
+ *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.each_row.first   # ["1", "2", nil]
  */
 static VALUE
 pgresult_each_row(VALUE self)
@@ -1191,6 +1226,9 @@ pgresult_each_row(VALUE self)
  *    res.values -> Array
  *
  * Returns all tuples as an array of arrays.
+ *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.values           # [["1", "2", nil]]
  */
 static VALUE
 pgresult_values(VALUE self)
@@ -1240,12 +1278,13 @@ make_column_result_array( VALUE self, int col )
 
 
 /*
- *  call-seq:
- *     res.column_values( n )   -> array
+ * call-seq:
+ *    res.column_values( n )   -> array
  *
- *  Returns an Array of the values from the nth column of each
- *  tuple in the result.
+ * Returns an Array of the values from the nth column of each tuple in the result.
  *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.column_values(1) # ["2"]
  */
 static VALUE
 pgresult_column_values(VALUE self, VALUE index)
@@ -1256,11 +1295,13 @@ pgresult_column_values(VALUE self, VALUE index)
 
 
 /*
- *  call-seq:
+ * call-seq:
  *     res.field_values( field )   -> array
  *
- *  Returns an Array of the values from the given _field_ of each tuple in the result.
+ * Returns an Array of the values from the given _field_ of each tuple in the result.
  *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.field_values(:a) # ["1"]
  */
 static VALUE
 pgresult_field_values( VALUE self, VALUE field )
@@ -1281,11 +1322,13 @@ pgresult_field_values( VALUE self, VALUE field )
 
 
 /*
- *  call-seq:
- *     res.tuple_values( n )   -> array
+ * call-seq:
+ *    res.tuple_values( n )   -> array
  *
- *  Returns an Array of the field values from the nth row of the result.
+ * Returns an Array of the field values from the nth row of the result.
  *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.tuple_values(0)  # ["1", "2", nil]
  */
 static VALUE
 pgresult_tuple_values(VALUE self, VALUE index)
@@ -1320,11 +1363,12 @@ static void ensure_init_for_tuple(VALUE self)
 
 	if( this->field_map == Qnil ){
 		int i;
-		VALUE field_map = rb_hash_new();
+		VALUE field_map;
 
 		if( this->nfields == -1 )
 			pgresult_init_fnames( self );
 
+		field_map = rb_hash_new_capa(this->nfields);
 		for( i = 0; i < this->nfields; i++ ){
 			rb_hash_aset(field_map, this->fnames[i], INT2FIX(i));
 		}
@@ -1334,11 +1378,13 @@ static void ensure_init_for_tuple(VALUE self)
 }
 
 /*
- *  call-seq:
- *     res.tuple( n )   -> PG::Tuple
+ * call-seq:
+ *    res.tuple( n )   -> PG::Tuple
  *
- *  Returns a PG::Tuple from the nth row of the result.
+ * Returns a PG::Tuple from the nth row of the result.
  *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.tuple(0)         # #<PG::Tuple a: "1", b: "2", c: nil>
  */
 static VALUE
 pgresult_tuple(VALUE self, VALUE index)
@@ -1363,7 +1409,10 @@ pgresult_tuple(VALUE self, VALUE index)
  * call-seq:
  *    res.each{ |tuple| ... }
  *
- * Invokes block for each tuple in the result set.
+ * Yields a Hash object for each row in the result.
+ *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.each.first       # {"a" => "1", "b" => "2", "c" => nil}
  */
 static VALUE
 pgresult_each(VALUE self)
@@ -1386,6 +1435,9 @@ pgresult_each(VALUE self)
  *    res.fields() -> Array
  *
  * Depending on #field_name_type= returns an array of strings or symbols representing the names of the fields in the result.
+ *
+ *    res = conn.exec('SELECT 1 AS a, 2 AS b, NULL AS c')
+ *    res.fields           # ["a", "b", "c"]
  */
 static VALUE
 pgresult_fields(VALUE self)
@@ -1402,7 +1454,7 @@ pgresult_fields(VALUE self)
  * call-seq:
  *    res.type_map = typemap
  *
- * Set the TypeMap that is used for type casts of result values to ruby objects.
+ * Set the PG::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,
@@ -1410,6 +1462,7 @@ pgresult_fields(VALUE self)
  *
  * +typemap+ must be a kind of PG::TypeMap .
  *
+ * See also #map_types! and PG::BasicTypeMapForResults
  */
 static VALUE
 pgresult_type_map_set(VALUE self, VALUE typemap)
@@ -1432,7 +1485,8 @@ pgresult_type_map_set(VALUE self, VALUE typemap)
  * call-seq:
  *    res.type_map -> value
  *
- * Returns the TypeMap that is currently set for type casts of result values to ruby objects.
+ * Returns the PG::TypeMap that is currently set for type casts of result values to ruby objects.
+ * The default is retrieved from PG::Connection#type_map_for_results , which defaults to PG::TypeMapAllStrings .
  *
  */
 static VALUE
@@ -1572,8 +1626,8 @@ pgresult_stream_any(VALUE self, int (*yielder)(VALUE, int, int, void*), void* da
  * wrapping each row into a dedicated result object, it delivers data in nearly
  * the same speed as with ordinary results.
  *
- * The base result must be in status PGRES_SINGLE_TUPLE or PGRES_TUPLES_CHUNK.
- * It iterates over all tuples until the status changes to PGRES_TUPLES_OK.
+ * The base result must be in status +PGRES_SINGLE_TUPLE+ or +PGRES_TUPLES_CHUNK+.
+ * It iterates over all tuples until the status changes to +PGRES_TUPLES_OK+.
  * A PG::Error is raised for any errors from the server.
  *
  * Row description data does not change while the iteration. All value retrieval

data/ext/pg_text_decoder.c

@@ -579,7 +579,7 @@ pg_text_dec_from_base64(t_pg_coder *conv, const char *val, int len, int tuple, i
 	/* create a buffer of the expected decoded length */
 	VALUE out_value = rb_str_new(NULL, BASE64_DECODED_SIZE(len));
 
-	decoded_len = base64_decode( RSTRING_PTR(out_value), val, len );
+	decoded_len = rbpg_base64_decode( RSTRING_PTR(out_value), val, len );
 	rb_str_set_len(out_value, decoded_len);
 
 	/* Is it a pure String conversion? Then we can directly send out_value to the user. */

data/ext/pg_text_encoder.c

@@ -784,7 +784,7 @@ pg_text_enc_to_base64(t_pg_coder *conv, VALUE value, char *out, VALUE *intermedi
 	if(out){
 		/* Second encoder pass, if required */
 		strlen = enc_func(this->elem, value, out, intermediate, enc_idx);
-		base64_encode( out, out, strlen );
+		rbpg_base64_encode( out, out, strlen );
 
 		return BASE64_ENCODED_SIZE(strlen);
 	} else {
@@ -799,7 +799,7 @@ pg_text_enc_to_base64(t_pg_coder *conv, VALUE value, char *out, VALUE *intermedi
 			out_str = rb_str_new(NULL, BASE64_ENCODED_SIZE(strlen));
 			PG_ENCODING_SET_NOCHECK(out_str, enc_idx);
 
-			base64_encode( RSTRING_PTR(out_str), RSTRING_PTR(subint), strlen);
+			rbpg_base64_encode( RSTRING_PTR(out_str), RSTRING_PTR(subint), strlen);
 			*intermediate = out_str;
 
 			return -1;

data/ext/pg_tuple.c

@@ -242,10 +242,10 @@ pg_tuple_materialize(VALUE self)
  * 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.
+ * Depending on PG::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;
+ * 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.
  */
@@ -302,7 +302,7 @@ pg_tuple_fetch(int argc, VALUE *argv, VALUE self)
  * 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.
+ * Depending on PG::Result#field_name_type= a string or symbol +key+ is interpreted as column name.
  *
  * If the key can't be found, it returns +nil+ .
  */
@@ -405,7 +405,7 @@ pg_tuple_each_value(VALUE self)
  *    tup.values  -> Array
  *
  * Returns the values of this tuple as Array.
- * +res.tuple(i).values+ is equal to +res.tuple_values(i)+ .
+ * <tt>res.tuple(i).values</tt> is equal to <tt>res.tuple_values(i)</tt> .
  */
 static VALUE
 pg_tuple_values(VALUE self)
@@ -474,7 +474,7 @@ pg_tuple_dump(VALUE self)
 	values = rb_ary_new4(this->num_fields, &this->values[0]);
 	a = rb_ary_new3(2, field_names, values);
 
-        rb_copy_generic_ivar(a, self);
+	rb_copy_generic_ivar(a, self);
 
 	return a;
 }
@@ -510,7 +510,7 @@ pg_tuple_load(VALUE self, VALUE a)
 	if (RARRAY_LENINT(field_names) != num_fields)
 		rb_raise(rb_eTypeError, "different number of fields and values");
 
-	field_map = rb_hash_new();
+	field_map = rb_hash_new_capa(num_fields);
 	for( i = 0; i < num_fields; i++ ){
 		rb_hash_aset(field_map, RARRAY_AREF(field_names, i), INT2FIX(i));
 	}

data/ext/pg_type_map.c

@@ -187,7 +187,9 @@ init_pg_type_map(void)
 	 *
 	 * This is the base class for type maps.
 	 * See derived classes for implementations of different type cast strategies
-	 * ( PG::TypeMapByColumn, PG::TypeMapByOid ).
+	 * ( PG::TypeMapByColumn, PG::TypeMapByOid, etc.).
+	 *
+	 * Find more type maps in the {README}[rdoc-ref:README.md@Type+Casts].
 	 *
 	 */
 	rb_cTypeMap = rb_define_class_under( rb_mPG, "TypeMap", rb_cObject );

data/ext/pg_util.c

@@ -15,7 +15,7 @@ static const char base64_encode_table[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijk
  * in-place (with _out_ == _in_).
  */
 void
-base64_encode( char *out, const char *in, int len)
+rbpg_base64_encode( char *out, const char *in, int len)
 {
 	const unsigned char *in_ptr = (const unsigned char *)in + len;
 	char *out_ptr = out + BASE64_ENCODED_SIZE(len);
@@ -72,7 +72,7 @@ static const unsigned char base64_decode_table[] =
  * It is possible to decode a string in-place (with _out_ == _in_).
  */
 int
-base64_decode( char *out, const char *in, unsigned int len)
+rbpg_base64_decode( char *out, const char *in, unsigned int len)
 {
 	unsigned char a, b, c, d;
 	const unsigned char *in_ptr = (const unsigned char *)in;

data/ext/pg_util.h

@@ -57,8 +57,8 @@
 #define BASE64_ENCODED_SIZE(strlen) (((strlen) + 2) / 3 * 4)
 #define BASE64_DECODED_SIZE(base64len) (((base64len) + 3) / 4 * 3)
 
-void base64_encode( char *out, const char *in, int len);
-int base64_decode( char *out, const char *in, unsigned int len);
+void rbpg_base64_encode( char *out, const char *in, int len);
+int rbpg_base64_decode( char *out, const char *in, unsigned int len);
 
 int rbpg_strncasecmp(const char *s1, const char *s2, size_t n);
 

data/lib/pg/version.rb

@@ -1,4 +1,5 @@
+# frozen_string_literal: true
 module PG
 	# Library version
-	VERSION = '1.6.1'
+	VERSION = '1.6.3'
 end