NAME

Data::Range::Compare - Framework for calculating range intersections

SYNOPSIS

  use Data::Range::Compare qw(HELPER_CB);

  my %helper=HELPER_CB;

  my @tom;
  my @harry;
  my @sally;

  push @tom,Data::Range::Compare->new(\%helper,0,1);
  push @tom,Data::Range::Compare->new(\%helper,3,7);

  push @harry,Data::Range::Compare->new(\%helper,9,11);

  push @sally,Data::Range::Compare->new(\%helper,6,7);

  my @cmp=(\@tom,\@harry,\@sally);

  my $sub=Data::Range::Compare->range_compare(\%helper,\@cmp);
  while(my @row=$sub->()) {
    my $common_range=
      Data::Range::Compare->get_common_range(\%helper,\@row);
    print "Common Range: $common_range\n";
    my ($tom,$harry,$sally)=@row;
    print "tom:   $tom\n";
    print "harry: $harry\n";
    print "sally: $sally\n";
  }

DESCRIPTION

This package is a universal framework for finding intersections in data representing ranges. The Ranges simply need to be two dimensional.

Data::Range::Compare is not intended to be used directly although it can be. For the most part Data::Range::Compare is intended to be subclassed by other packages.

For a list of more detailed examples, check out the cookbook.

Export list

:KEYS

  key_helper
  key_start
  key_end
  key_generated
  key_missing
  key_data

:HELPER_CB

  HELPER_CB

:HELPER

  add_one
  sub_one
  cmp_values

:SORT

  sort_largest_range_end_first
  sort_largest_range_start_first
  sort_smallest_range_start_first
  sort_smallest_range_end_first
  sort_in_consolidate_order
  sort_in_presentation_order

%helper

%helper is the primary driver for this framework.

Data::Range::Compare relies on %helper to do its internal work. So this section explains how to populate %helper.

  # to import the default %helper functions into your package
  use Data::Range::Compare qw(:HELPER);

  my %helper=(
    add_one=>\&add_one
    sub_one=>\&sub_one
    cmp_values=>\&cmp_values
  );

add_one

This function accepts one argument and returns the next thing. If you are implementing your own add_one, just make sure it returns the correct next value for your data.

  Example:

  $helper{add_one}=sub {$_[0] + 1};
  my $next=$helper{add_one}->(1);
  $next==2;

  Same as

  %helper=HELPER_CB;

  Or Write your own

  # a-z example
  my @list=('a' .. 'z');
  my $id=-1; 
  my %ids=map { ($_,++$id) } @list;

  sub my_add_one {
    my $here=$ids{$_[0]};
    ++$here;
    return 'z' if $#list<$here;
    $list[$here]
  }

  $helper{add_one}=\&my_add_one;
  my $next=$helper{add_one}->('a');
  $next eq 'b';

sub_one

This function accepts one argument and returns the next thing. If you are implementing your own sub_one, just make sure it returns the correct previous value for your data.

  Example:

  $helper{sub_one}=sub {$_[0] - 1};
  my $next=$helper{sub_one}->(1);
  $next==0;

  Same as

  %helper=HELPER_CB;

  Or Write your own

  # a-z example
  my @list=('a' .. 'z');
  my $id=-1; 
  my %ids=map { ($_,++$id) } @list;

  sub my_sub_one {
    my $here=$ids{$_[0]};
    --$here;
    return 'z' if 0>$here;
    $list[$here]
  }

  $helper{sub_one}=\&my_sub_one;
  my $next=$helper{sub_one}->('a');
  $next eq 'b';

cmp_values

This function accepts 2 arguments and should return one of the following values: 0,-1,1

Examples:

  $helper{cmp_values}=sub {$_[0] <=> $_[1] };
  my $cmp=$helper{cmp_values}->(0,1);
  $cmp==-1;

  Same as

  %helper=HELPER_CB;

  Or Write your own

  # a-z example
  $helper{cmp_values}=sub {$_[0] cmp $_[1] };
  my $cmp=$helper{cmp_values}->(qw(a b));
  $cmp==-1;

OO Methods

This section covers the OO Methods in the package

my $range=new Data::Range::Compare(\%helper,0,1);
my $range=new Data::Range::Compare(\%helper,0,1,$generated);
my $range=new Data::Range::Compare(\%helper,0,1,$generated,$missing);
my $range=Data::Range::Compare->new(\%helper,0,1);
my $range=Data::Range::Compare->new(\%helper,0,1,$generated);
my $range=Data::Range::Compare->new(\%helper,0,1,$generated,$missing);

This function acts as the general package constructor. "$generated" represents the $range->generated state. "$missing" represents the $range->missing state.

%helper is what drives the internals of our instance.
my $value=$range->helper_cb('add_one',1)
my $value=$range->helper_cb('sub_one',1)
my $value=$range->helper_cb('cmp_values',1,1)

Grants access to this range's \%helper.
my $range_end=$range->range_end;

Returns the "thing" that is denoted as the end of this range.
my $range_start=$range->range_start;

Returns the "thing" that is denoted as the start of this range.
my $notation=$range->notation;

Returns a string representing "range_start - range_end". This is the same as print $range.
my $helper_hash=$range->helper_hash;

Gets the \%helper for this instance.
if($range->missing) { .. }

Returns the missing state
if($range->generated) { .. }

Returns the generated state
$range->data->{some_lable}='some value'
my $value=$range->data->{some_lable};
my $hash_ref=$range->data;

Lets you tag this block with your data.
if($range->overlap($another_range);

Returns true if either of these ranges overlap.
my $next_start=$range->next_range_start;

Gets the thing that represents the start of the next range.
my $previous_end=$range->previous_range_end;

Gets the thing that represents the end of the previous range.

my $cmp=$range->cmp_range_start($range_b);

Wrapper function does the same as the following.

  my $cmp=$range->helper_cb(
    'cmp_values'
    ,$range->range_start
    ,$range_b->range_start
  );

my $cmp=$range->cmp_range_end($range_b);

Wrapper function does the same as the following.

  my $cmp=$range->helper_cb(
    'cmp_values'
    ,$range->range_end
    ,$range_b->range_end
  );

if($range_a->contiguous_check($range_b) { ... }

Returns true if $range_b immediately follows $range_a
my $cmp=$range->cmp_ranges($range_b);

Does an an ascending order style comparison.
my $common=Data::Range::Compare->get_common_range(\%helper,\@list)

Returns a new Data::Range::Compare object representing the intersecting ranges ranges found in \@list.
my $range=Data::Range::Compare->get_overlapping_range( \%helper, \@list );

Returns a new Data::Range::Compare object representing the outer most start and end found in \@list.
my $ref=Data::Range::Compare->consolidate_ranges(\%helper,\@list);

Returns a list reference of sorted and consolidated Data::Range::Compare objects .
my $ref=Data::Range::Compare->fill_missing_ranges(\%helper,\@list);
my $ref=Data::Range::Compare->fill_missing_ranges(\%helper, \@list, consolidate_ranges=>0);
my $ref=Data::Range::Compare->fill_missing_ranges(\%helper, \@list, consolidate_ranges=>1);

Returns a sorted contiguous list of Data::Range::Compare objects. All objects generated by fill_missing_ranges are created as missing and generated.

Optional argument consolidate_ranges=>(0||1)
```
  consolidate_ranges=>1 
    calls Data::Range::Compare->consolidate_ranges(\%helper,\@list)
    before processing ranges

  consolidate_ranges=>0 ( Default )
    Skips the consolidate pass
```
my $ref=Data::Range::Compare->range_start_end_fill( \%helper, \@list_of_lists);

Creates filler ranges ensuring each list of ranges starts and ends with the same value. All ranges created by range_start_end_fill are missing and generated.
my $sub=Data::Range::Compare->range_compare( \%helper, \@list_of_lists );
my $sub=Data::Range::Compare->range_compare(\%helper, \@list_of_lists, consolidate_ranges=>0);
my $sub=Data::Range::Compare->range_compare( \%helper, \@list_of_lists, consolidate_ranges=>1);

Returns an anonymous function. The function can be used to iterate through the list of lists at intersecting points.

Optional argument consolidate_ranges>(0||1)
```
  consolidate_ranges=>1 ( Default )
    calls Data::Range::Compare->consolidate_ranges(\%helper,\@list)
    on each \@list in \@list_of_lists
    before entering the compare process

  consolidate_ranges=>0 
    Skips the consolidate pass
```
my ($row,$cols,$next)=Data::Range::Compare->init_compare_row(\%helper, \@list_of_lists);

This initializes the values for compare_row, producing the first row. See range_compare for a more practical iterator interface.
($row,$cols,$next)=Data::Range::Compare->compare_row( \%helper, \@list_of_lists, $row, $cols ) if $next;

Used to continue iteration through @list_of_lists while $next;

Sort Methods

This section documents the export-able sort functions. These are low level sort functions and must be used in a call to "sort".

Example:

  @list=sort sort_in_presentation_order @list;

@list=sort sort_in_presentation_order @unsorted_list;

Sorts a list of Data::Range::Compare objects in presentation order.
@list=sort sort_in_consolidate_order @unsorted_list;

Sorts a list of Data::Range::Compare objects in the order required for range consolidation.
@list=sort sort_largest_range_end_first @unsorted_list;

Sorts a list Data::Range::Compare objects by range_end in descending order.
@list=sort sort_smallest_range_start_first @unsorted_list;

Sorts a list Data::Range::Compare objects by range_start in ascending order.
@list=sort sort_smallest_range_end_first @unsorted_list;

Sorts a list Data::Range::Compare objects by range_end in ascending order.
@list=sort sort_largest_range_start_first @unsorted_list;

Sorts a list Data::Range::Compare objects by range_start in descending order.

AUTHOR

Michael Shipper

SourceForge Project

As of version 1.026 the Project has been moved to SourceForge.net

Data Range Compare https://sourceforge.net/projects/data-range-comp/

COPYRIGHT

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

To install Data::Range::Compare, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Data::Range::Compare

CPAN shell

perl -MCPAN -e shell
install Data::Range::Compare

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)