# ######################################################################
# Voter::Base Object methods
# ######################################################################

sub populate
  {
    # This function is normally used only by object methods. It takes
    # no arguments and returns a boolean value. It returns false
    # if the object doesn't actually exist.
    # 1 / 0 = $object->populate
    
    # Object method
    # 
    # $_[0] = Voter::...=HASH( ... )
    $_[0]->ERR_PARAMC unless
      ( @_ == 1 and
	ref( $_[0] ) );
    
    # The additional attributes tableoid, oid, xmin, cmin, xmax, cmax, ctid are
    # PostgreSQL specific and exist on every row in every table. They might be
    # interesting so I'm fetching them as well though any actual use of them
    # should take care to use the values correctly upon consultation with
    # the PostgreSQL documentation.
    my $identity = $_[0]->identity_sql('SELECT');
    
    # Don't just execute this inline - I want to keep the $sth handle around
    my $sth = $_[0]->dbh->prepare( "SELECT tableoid, oid, xmin, cmin, xmax, cmax, ctid, * FROM " .
				   $_[0]->CLASS .
				   " WHERE " .
				   $identity->{exp} );
    $sth->execute( $identity->{val} );
    my $ary = $sth->fetchrow_arrayref;
    
    # Return nothing if the object doesn't exist
    return 0 unless $ary;
    
    # Get the list of attribute names and assign their values as a hash slice
    @{$_[0]}{ @{$sth->{NAME_lc}} } = @$ary;
    # that's just assigning an array to a hash slice - except all through
    # references. More prosaicly it might look like
    # @_{ @attributes } = @values
    
    return 1;
  }