NAME

Interval - handling of temporal intervals based on Date::Manip

SYNOPSIS

    use Interval;

    ### class methods ###
    Interval->setDefaultIntervalType ($OPEN_INT); 
    $int_open = new Interval ("10/10/97", "20/10/97"); 
    print "$int_open\n"        # prints  '(1997-10-10, 1997-10-20)'

    $nDefaultType = Interval->getDefaultIntervalType;

    ### constructor ###
    $i1 = new Interval ("30/10/97", "01/12/98");
    $i2 = new Interval ("20/01/96", "01/11/97", $RIGHT_OPEN_INT);

    use Date::Manip;
    $date1 = &ParseDate ("10/10/97");
    $date2 = &ParseDate ("15/10/97");
    $int = new Interval ($d1, $d2);

    ### Overload operators ###
    $i3 = $i1 + $i2;          # + gives the sum of intervals if the overlap
    print "$i3\n";            # prints '[1997-01-20, 1998-12-01)'

    $i4 = $i1 - $i2;          # - gives difference of intervals of intervals
    print "$i4\n";            # prints '[1997-11-01, 1998-12-01)'
   
    $i5 = $i1 - $i1; 
    print "$i5\n";            # prints '<empty>'

    ### <Allen overlap type> ### 
    $X = new Interval (<parameters>);
    $Y = new Interval (<parameters>);
                              ###  relationship between intervals ###
    $Y->AllenBefore ($X);             YYYYYY XXXXXX

    $Y->AllenMeets ($X);              YYYYYYXXXXXX

    $Y->AllenLeftOverlaps ($X);          XXXXXX
                                      YYYYYY

    $Y->AllenLeftCovers ($X);            XXXXXX
                                      YYYYYYYYY

    $Y->AllenCovers ($X);                XXXXXX
                                      YYYYYYYYYYYY

    $Y->AllenStarts ($X);             XXXXXX
                                      YYY

    $Y->AllenEquals ($X);             XXXXXX
                                      YYYYYY
    
    $Y->AllenRightCovers ($X);        XXXXXX
                                      YYYYYYYYY

    $Y->AllenDuring ($X);             XXXXXX
                                       YYYY

    $Y->AllenFinishes ($X);           XXXXXX
				        YYYY 

    $Y->AllenRightOverlaps ($X);      XXXXXX
                                         YYYYYY

    $Y->AllenExtends ($X);            XXXXXXYYYYYY

    $Y->AllenAfter ($X):              XXXXXX YYYYYY

    ### <overlap type> ###
    $Y->before ($X)         same as  $Y->AllenBefore ($X)
    $Y->meets  ($X)         same as  $Y->AllenMeets ($X)

    $Y->leftOverlaps ($X)   same as  $Y->AllenLeftOverlaps ($X)  or
                                     $Y->AllenStarts ($X)

    $Y->totalOverlaps ($X)  same as  $Y->AllenCovers ($X)        or
                                     $Y->AllenLeftCovers ($X)    or
                                     $Y->AllenRightCovers ($X)   or
                                     $Y->AllenEquals ($X)

    $Y->rightOverlaps ($X)  same as  $Y->AllenFinishes ($X)      or
                                     $Y->AllenRightCovers

    $Y->during ($X)         same as  $Y->AllenDuring ($X)
    $Y->extends ($X)        same as  $Y->AllenExtends ($X)
    $Y->after ($X)          same as  $Y->AllenAfter ($X)

    ### <interval type> ###
    $closed_int = new Interval ("10/10/97", "20/10/97", $CLOSED_INT); 
    print "$closed_int\n";      # prints [1997-10-10, 1997-10-20]

    $left_open_int = new Interval ("10/10/97", "20/10/97", $LEFT_OPEN_INT); 
    print "$left_open_int\n";   # prints (1997-10-10, 1997-10-20]

    $right_open_int = new Interval ("10/10/97", "20/10/97", $RIGHT_OPEN_INT); 
    print "$right_open_int\n";  # prints [1997-10-10, 1997-10-20)

   $open_int = new Interval ("10/10/97", "20/10/97", $OPEN_INT); 
   print "$open_int\n";         # prints (1997-10-10, 1997-10-20)

   ### check and get overlapping interval ###
    $i1 = new Interval ("30/10/97", "01/12/98");
    $i2 = new Interval ("20/01/96", "01/11/97");
    $i3 = new Interval ("01/01/95", "30/04/95");

    if ($i1->overlaps ($i2)) {
        $i4 = $i1->getOverlap($i2);
        print "$i4\n";              # prints [1997-10-30, 1997-11-01)
    }
    if ($i1->overlaps ($i3)){       # tests fails, does not print anything
        $i5 = $i1->getOverlap($i2);
        print "$i5\n";
    }

DESCRIPTION

All strings which can be used to create a Date::Manip can be used
to create an Interval. However, the start date must be larger than
the stop date.

The comparison of intervals is based on the 13 ways intervals can
overlap as defined by J.F. Allen (See litteratur). Further, I have
included a small number of interval comparison which are handy if
you are only interested in getting the overlapping interval of two
intervals.

Defaults

The default input format is non-us date format "10/12/97" is the
10th of December 1997, not the 12 of October 1997. It can be
changed by calling Date::Manip::DateInit().

The default output format is YYYY-MM-DD. Can be changed by calling
Interval->setDisplayFormat(<string>).

BUGS

Tried my best to avoid them send me an email if you are bitten by
a bug 

TODO

- Cannot take references to dates as input parameters for the
  constructors

- Cannot subtract intervals which overlap with "during" overlaps,
  this results in two intervals (currently results in an empty interval)

LITTERATURE

Allen, J. F., "An Interval-Based Representation of Temporal Knowledge",
Communication of the ACM, 26(11) pp. 832-843, November 1983.

AUTHOR

Kristian Torp <torp@cs.auc.dk>