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>