# class PG::Coder

This is the base class for all type cast encoder and decoder classes.

It can be used for implicit type casts by a `PG::TypeMap` or to convert single values to/from their string representation by `encode` and `decode`.

Ruby `nil` values are not handled by encoders, but are always transmitted as SQL `NULL` value. Vice versa SQL `NULL` values are not handled by decoders, but are always returned as a `nil` value.

### Constants

FORMAT_ERROR_MASK
FORMAT_ERROR_TO_PARTIAL
FORMAT_ERROR_TO_RAISE
FORMAT_ERROR_TO_STRING
TIMESTAMP_APP_LOCAL
TIMESTAMP_APP_UTC
TIMESTAMP_DB_LOCAL
TIMESTAMP_DB_UTC

  `Coder#flags=`

### Attributes

name[RW]

Name of the coder or the corresponding data type.

This accessor is only used in `PG::Coder#inspect` .

### Public Class Methods

new(params={}) click to toggle source

Create a new coder object based on the attribute Hash.

    # File lib/pg/coder.rb, line 15
    def initialize(params={})
            params.each do |key, val|
                    send("#{key}=", val)
            end
    end

### Public Instance Methods

==(v) click to toggle source

    # File lib/pg/coder.rb, line 34
    def ==(v)
            self.class == v.class && to_h == v.to_h
    end

decode( string, tuple=nil, field=nil ) click to toggle source

Decodes the given string representation into a Ruby object, without sending data to/from the database server.

A nil value is passed through and non String values are expected to have to_str defined.

    static VALUE
    pg_coder_decode(int argc, VALUE *argv, VALUE self)
    {
            char *val;
            int tuple = -1;
            int field = -1;
            VALUE res;
            t_pg_coder *this = DATA_PTR(self);

            if(argc < 1 || argc > 3){
                    rb_raise(rb_eArgError, "wrong number of arguments (%i for 1..3)", argc);
            }else if(argc >= 3){
                    tuple = NUM2INT(argv[1]);
                    field = NUM2INT(argv[2]);
            }

            if( NIL_P(argv[0]) )
                    return Qnil;

            if( this->format == 0 ){
                    val = StringValueCStr(argv[0]);
            }else{
                    val = StringValuePtr(argv[0]);
            }
            if( !this->dec_func ){
                    rb_raise(rb_eRuntimeError, "no decoder function defined");
            }

            res = this->dec_func(this, val, RSTRING_LEN(argv[0]), tuple, field, ENCODING_GET(argv[0]));
            OBJ_INFECT(res, argv[0]);

            return res;
    }

dup() click to toggle source

    # File lib/pg/coder.rb, line 21
    def dup
            self.class.new(to_h)
    end

encode( value [, encoding] ) click to toggle source

Encodes the given Ruby object into string representation, without sending data to/from the database server.

A nil value is passed through.

    static VALUE
    pg_coder_encode(int argc, VALUE *argv, VALUE self)
    {
            VALUE res;
            VALUE intermediate;
            VALUE value;
            int len, len2;
            int enc_idx;
            t_pg_coder *this = DATA_PTR(self);

            if(argc < 1 || argc > 2){
                    rb_raise(rb_eArgError, "wrong number of arguments (%i for 1..2)", argc);
            }else if(argc == 1){
                    enc_idx = rb_ascii8bit_encindex();
            }else{
                    enc_idx = rb_to_encoding_index(argv[1]);
            }
            value = argv[0];

            if( NIL_P(value) )
                    return Qnil;

            if( !this->enc_func ){
                    rb_raise(rb_eRuntimeError, "no encoder function defined");
            }

            len = this->enc_func( this, value, NULL, &intermediate, enc_idx );

            if( len == -1 ){
                    /* The intermediate value is a String that can be used directly. */
                    OBJ_INFECT(intermediate, value);
                    return intermediate;
            }

            res = rb_str_new(NULL, len);
            PG_ENCODING_SET_NOCHECK(res, enc_idx);
            len2 = this->enc_func( this, value, RSTRING_PTR(res), &intermediate, enc_idx );
            if( len < len2 ){
                    rb_bug("%s: result length of first encoder run (%i) is less than second run (%i)",
                            rb_obj_classname( self ), len, len2 );
            }
            rb_str_set_len( res, len2 );
            OBJ_INFECT(res, value);

            RB_GC_GUARD(intermediate);

            return res;
    }

flags → Integer click to toggle source

Get current bitwise OR-ed coder flags.

    static VALUE
    pg_coder_flags_get(VALUE self)
    {
            t_pg_coder *this = DATA_PTR(self);
            return INT2NUM(this->flags);
    }

flags = Integer click to toggle source

Set coder specific bitwise OR-ed flags. See the particular en- or decoder description for available flags.

The default is `0`.

    static VALUE
    pg_coder_flags_set(VALUE self, VALUE flags)
    {
            t_pg_coder *this = DATA_PTR(self);
            this->flags = NUM2INT(flags);
            return flags;
    }

format → Integer click to toggle source

The format code that is sent alongside with an encoded query parameter value.

    static VALUE
    pg_coder_format_get(VALUE self)
    {
            t_pg_coder *this = DATA_PTR(self);
            return INT2NUM(this->format);
    }

format = Integer click to toggle source

Specifies the format code that is sent alongside with an encoded query parameter value.

The default is `0`.

    static VALUE
    pg_coder_format_set(VALUE self, VALUE format)
    {
            t_pg_coder *this = DATA_PTR(self);
            this->format = NUM2INT(format);
            return format;
    }

inspect() click to toggle source

    # File lib/pg/coder.rb, line 46
    def inspect
            str = self.to_s
            oid_str = " oid=#{oid}" unless oid==0
            format_str = " format=#{format}" unless format==0
            name_str = " #{name.inspect}" if name
            str[-1,0] = "#{name_str} #{oid_str}#{format_str}"
            str
    end

marshal_dump() click to toggle source

    # File lib/pg/coder.rb, line 38
    def marshal_dump
            Marshal.dump(to_h)
    end

marshal_load(str) click to toggle source

    # File lib/pg/coder.rb, line 42
    def marshal_load(str)
            initialize Marshal.load(str)
    end

oid → Integer click to toggle source

The type OID that is sent alongside with an encoded query parameter value.

    static VALUE
    pg_coder_oid_get(VALUE self)
    {
            t_pg_coder *this = DATA_PTR(self);
            return UINT2NUM(this->oid);
    }

oid = Integer click to toggle source

Specifies the type OID that is sent alongside with an encoded query parameter value.

The default is `0`.

    static VALUE
    pg_coder_oid_set(VALUE self, VALUE oid)
    {
            t_pg_coder *this = DATA_PTR(self);
            this->oid = NUM2UINT(oid);
            return oid;
    }

to_h() click to toggle source

Returns coder attributes as Hash.

    # File lib/pg/coder.rb, line 26
    def to_h
            {
                    oid: oid,
                    format: format,
                    name: name,
            }
    end