DBIx::DBO2::RecordSet - A sequential group of Record objects

  $rs = DBIx::DBO2::RecordSet->new( @records );

  print "Found " . $rs->count() . " records";

  $rs->filter( { 'status' => 'New' } );
  $rs->sort( 'creation_date' );

  foreach ( 0 .. $rs->count() ) { 
    print $rs->record( $_ )->name();
  }

  foreach ( $rs->range_records( 11, 20 ) ) { 
    print $_->name();
  }

package DBIx::DBO2::RecordSet;

use strict;
use Carp;

# use Data::Sorting 'sort_array';
use DBIx::SQLEngine::Criteria qw( match_criteria new_group_from_values );

# $rs = DBIx::DBO2::RecordSet->new( @records );
sub new {
  my $callee = shift;
  my $package = ref $callee || $callee;
  
  my $self = [];
  bless $self, $package;
  $self->init( @_ );
  return $self;
}

# $rs->init( @records );
sub init {
  my $self = shift;
  
  if ( scalar @_ == 1 and ref($_[0]) eq 'ARRAY' ) {
    @_ = @{ $_[0] };
  }
  
  @$self = @_;
}

# @records = $rs->records();
sub records {
  my $self = shift;
  @$self;
}

###

# $rs = DBIx::DBO2::RecordSet->new_class_ids( $class, @ids );
sub new_ids {
  my $callee = shift;
  my $package = ref $callee || $callee;
  
  my $self = [];
  bless $self, $package;
  $self->init_class_ids( @_ );
  return $self;
}

# $rs->init_ids( $class, @ids );
sub init_ids {
  my $self = shift;
  my $class = shift;
  
  @$self = map { $class->fetch_id( $_ ) } @_;
}

# @records = $rs->class_ids();
sub class_ids {
  my $self = shift;
  my $class = ref( $self->[0] );
  return $class, map { $_->{id} } @$self;
}

###

sub raw {
  my $self = shift;
  if ( scalar @_ ) {
    @$self = @_;
  } else {
    @$self;
  }
}
# 
# sub as_RecordArray {
#   my $self = shift;
# }
# 
# sub as_IDArray {
#   my $self = shift;
#   EBiz::Database::RecordSet::IDArray->new( $self->records );
# }
# 
# sub as_IDString {
#   my $self = shift;
#   EBiz::Database::RecordSet::IDString->new( $self->records );
# }

###

# $count = $rs->count();
sub count {
  my $self = shift;
  scalar @$self;
}

# $record = $rs->record( $position );
sub record {
  my $self = shift;
  my $position = shift;
  return unless ( length $position and $position !~ /\D/ and $position <= $#$self);
  $self->[ $position ];
}

# $record = $rs->last_record();
sub last_record {
  my $self = shift;
  return unless $self->count;
  $self->record( $self->count - 1 );
}

# $clone = $rs->range_set( $start_pos, $stop_pos );
sub range_set {
  my $self = shift;
  my ( $start, $end ) = @_;
  if ( $start < 0 ) { $start = 0 }
  if ( $end > $#$self ) { $end = $#$self }
   
  $self->new( @{$self}[ $start .. $end ] );
}

# @records = $rs->range_records( $start_pos, $stop_pos );
sub range_records {
  my $self = shift;
  my ( $start, $end ) = @_;
  if ( $start < 0 ) { $start = 0 }
  if ( $end > $#$self ) { $end = $#$self }
   
  @{$self}[ $start .. $end ];
}

###

# $rs->sort( @fieldnames );
sub sort {
  my $self = shift;
  local @_ = @{ $_[0] } if ( scalar @_ == 1 and ref $_[0] eq 'ARRAY' );
  sort_array(@$self, @_);
}

# $clone = $rs->sorted_set( @fieldnames );
sub sorted_set {
  my $self = shift;
  my $clone = $self->new( @$self );
  $clone->sort( @_ );
  return $clone;
}

# @records = $rs->sorted_records( @fieldnames );
sub sorted_records {
  my $self = shift;
  my $clone = $self->new( @$self );
  $clone->sort( @_ );
  $clone->records();
}

###


# $rs->filter( $criteria );
sub filter {
  my $self = shift;
  
  my $criteria = shift
	or return;
  if (ref $criteria eq 'ARRAY') { 
    $criteria = new_group_from_values(@$criteria);
  } elsif (ref $criteria eq 'HASH') {
    $criteria = DBO::Criteria->new_from_hashref($criteria);
  } elsif (ref $criteria eq 'CODE') {
    @$self = grep { $criteria->( $_ ) } @$self;
    return;
  } 
  
  @$self = $criteria->matchers($self);
}

# $clone = $rs->filtered_set( $criteria );
sub filtered_set {
  my $self = shift;
  my $clone = $self->new( @$self );
  $clone->filter( @_ );
  return $clone;
}

# @records = $rs->filtered_records( $criteria );
sub filtered_records {
  my $self = shift;
  my $clone = $self->new( @$self );
  $clone->filter( @_ );
  $clone->records();
}

###

# $rs->push_unique_records( @records );
sub push_unique_records {
  my $rs = shift;
  my %record_ids = map { $_->id => 1 } $rs->records;
  push @$rs, grep { ! ( $record_ids{ $_->id } ++ ) } @_
}

###

sub reverse {
  my $rs = shift;
  @$rs = reverse @$rs;
}

# $numeric = $rs->sum( $fieldname );
sub sum {
  my $rs = shift;  
  my $field = shift;
  my $sum = 0;
  foreach ( $rs->records ) {
    $sum += $_->$field();
  }
  return $sum;
}

1;