=pod

=head1 NAME

Data::Range::Compare::Stream::Iterator::Compare::Asc - Compares results overlapping and duplicate ranges

=head1 SYNOPSIS

  use Data::Range::Compare::Stream;
  use Data::Range::Compare::Stream::Iterator::Array;
  use Data::Range::Compare::Stream::Iterator::Consolidate;
  use Data::Range::Compare::Stream::Iterator::Compare::Asc;

  my $iterator_a=Data::Range::Compare::Stream::Iterator::Array->new(
    new_from=>'Data::Range::Compare::Stream',
  );

  # create a new range and add it to the iterator
  $iterator_a->create_range(0,0);

  my $iterator_b=Data::Range::Compare::Stream::Iterator::Array->new(
    new_from=>'Data::Range::Compare::Stream',
  );

  # create a new range and add it to the iterator
  $iterator_b->create_range(1,2);

  $iterator_a->prepare_for_consolidate_asc;
  $iterator_b->prepare_for_consolidate_asc;

  my $consolidate_a=Data::Range::Compare::Stream::Iterator::Consolidate->new($iterator_a);
  my $consolidate_b=Data::Range::Compare::Stream::Iterator::Consolidate->new($iterator_b);
  
  my $compare=new Data::Range::Compare::Stream::Iterator::Compare::Asc;

  $compare->add_consolidator($consolidate_a);
  $compare->add_consolidator($consolidate_b);

  while($compare->has_next) {
    # Result objects are instances of: Data::Range::Compare::Stream::Iterator::Compare::Result
    my $result=$compare->get_next;
  }

=head1 DESCRIPTION

This module implements Data::Range::Compare::Stream::Iterator::Compare::Base.

Data::Range::Compare::Stream::Iterator::Compare::Asc compares results from Data::Range::Compare::Stream::Iterator::Consolidate in the following order: Consolidation Asc: range_start asc,range_end desc.

=head2 OO Methods

=over 3

=item * my $compare=new Data::Range::Compare::Stream::Iterator::Compare::Asc;

Optional constructor arguments:

      factory_instance =>$obj

        # defines the object that implements the $obj->factory($start,$end,$data).
        # new ranges are constructed from the factory interfcae.  If a factory interface
        # is not created an instance of Data::Range::Compare::Stream is assumed.

=item * $compare->add_consolidator($iterator_a);

An $iterator object must implement: Data::Range::Compare::Stream::Iterator::Base. Result objects created by $iterator->has_next must implement: Data::Range::Compare::Stream::Result::Base.

=item * while($compare->has_next) { do something }

Returns true when the there are more ranges to consolidate

=item * my $result=$compare->get_next;

If $compare->has_next returns true returns a instance of Data::Range::Compare::Stream::Iterator::Compare::Result.

=item * my $count=$compare->get_column_count_human_readable;

Returns a human readable count of the columns in the comparison object.

=item * my $count=$compare->get_column_count;

Returns the last index id of the iterator column counts.

=item * my $range=$compare->get_current_row;

Returns the range object that will be used in the $compare->get_next call.

=item * my $boolean=$compare->iterators_empty;

Returns false when all iterator objects in $compare are depleted.

=item * my $result=$compare->get_next;

If $compare->has_next returns true Returns an instance of Data::Range::Compare::Stream::Iterator::Compare::Result.

=item * my $id=$compare->insert_consolidator($consolidator);

Inserts a consolidator object into a prepared and or running $compare object.  This interface can be dangerous, use with caution!

=item * my $consolidator=$compare->get_iterator_by_id($id);

Returns the consolidator identified by $id.  Fatal if $id does not exist.

=item * $compare->set_column_id($id)

Used to set the column_id for the compare object.

=item * my $id=$compare->get_column_id;

Used to fetch the column_id;

=back

=head1 SEE ALSO

Data::Range::Compare::Stream::Iterator::Compare::Result

Data::Range::Compare::Stream::Iterator::Consolidate::Result

Data::Range::Compare::Stream::Iterator::Consolidate

Data::Range::Compare::Stream::Cookbook

=head1 AUTHOR

Michael Shipper

=head1 Source-Forge Project

As of version 0.001 the Project has been moved to Source-Forge.net

L<Data Range Compare|https://sourceforge.net/projects/data-range-comp/>
L<https://sourceforge.net/projects/data-range-comp/>

=head1 COPYRIGHT

Copyright 2011 Michael Shipper.  All rights reserved.

This library is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.

=cut

