view release on metacpan or  search on metacpan

Interval.pm  view on Meta::CPAN

=head1 NAME

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

=head1 COPYRIGHT

Copyright (C) 1997 by Kristian Torp, <F<torp@cs.auc.dk>>

This program is free software. You can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.

This program is distributed AS IS in the hope that it will be useful,
but WITHOUT ANY WARRANTY. See the GNU General Public License for more
details.

=cut

package Date::Interval;

use Exporter;
use strict;
use vars qw (@ISA @EXPORT @EXPORT_OK $VERSION
	     $FALSE $TRUE $ABSOLUTE $RELATIVE
	     $OPEN $CLOSED $LEFT_CLOSED $RIGHT_CLOSED $LEFT_OPEN $RIGHT_OPEN 
	     $CLOSED_INT $RIGHT_OPEN_INT $LEFT_OPEN_INT $OPEN_INT
	     $BEFORE $MEETS $LEFT_OVERLAPS $RIGHT_OVERLAPS
	     $TOTALLY_OVERLAPS $DURING $EXTENDS $AFTER
	     $ALLEN_BEFORE $ALLEN_MEETS $ALLEN_LEFT_OVERLAPS $ALLEN_LEFT_COVERS
	     $ALLEN_COVERS $ALLEN_STARTS $ALLEN_EQUALS $ALLEN_RIGHT_COVERS 
	     $ALLEN_DURING $ALLEN_FINISHES $ALLEN_RIGHT_OVERLAPS
	     $ALLEN_EXTENDS $ALLEN_AFTER
	     $DisplayFormat $DefaultType $Now); 
@ISA       = qw (Exporter);
@EXPORT    = qw ();
@EXPORT_OK = qw ($CLOSED_INT $RIGHT_OPEN_INT $LEFT_OPEN_INT $OPEN_INT
		 $BEFORE $MEETS $LEFT_OVERLAPS $RIGHT_OVERLAPS
		 $TOTALLY_OVERLAPS $DURING $EXTENDS $AFTER
		 $ALLEN_BEFORE $ALLEN_MEETS $ALLEN_LEFT_OVERLAPS 
		 $ALLEN_LEFT_COVERS $ALLEN_COVERS $ALLEN_STARTS 
		 $ALLEN_EQUALS $ALLEN_RIGHT_COVERS 
		 $ALLEN_DURING $ALLEN_FINISHES $ALLEN_RIGHT_OVERLAPS
		 $ALLEN_EXTENDS $ALLEN_AFTER);
$VERSION = 0.03;

use Date::Manip; # data types of the end points in the interval
use Carp;

use overload
    '+'   => \&_plus,
    '-'   => \&_minus,
    '<'   => \&_smaller_than,
    '>'   => \&_greater_than,
    '=='  => \&_equal,
    '!='  => \&_not_equal,
    '<=>' => \&_spaceship,
    qw("" _stringify);

# Must set the time zone to use Date::Manip
BEGIN {$Date::Manip::TZ = "CET";} # Default Central European Time

##############################################################################
# Constants
##############################################################################

# Boolean values
$FALSE = 0;
$TRUE  = 1;

# <value type>
$ABSOLUTE = 0;
$RELATIVE = 1;

# For output
$LEFT_CLOSED  = '[';
$RIGHT_CLOSED = ']';
$LEFT_OPEN    = '(';
$RIGHT_OPEN   = ')';

# <interval type>
$CLOSED_INT     = 1;
$RIGHT_OPEN_INT = 2;
$LEFT_OPEN_INT  = 3;
$OPEN_INT       = 4;

# <interval end>
$OPEN   = 1;
$CLOSED = 2;

# <overlap type>
$BEFORE           = 1;
$MEETS            = 2;
$LEFT_OVERLAPS    = 3;
$RIGHT_OVERLAPS   = 4;
$TOTALLY_OVERLAPS = 5;
$DURING           = 6;
$EXTENDS          = 7;
$AFTER            = 8;

# <Allen overlap type>
$ALLEN_BEFORE         = 1;
$ALLEN_MEETS          = 2;
$ALLEN_LEFT_OVERLAPS  = 3;
$ALLEN_LEFT_COVERS    = 4;
$ALLEN_COVERS         = 5;
$ALLEN_STARTS         = 6;
$ALLEN_EQUALS         = 7;
$ALLEN_RIGHT_COVERS   = 8;
$ALLEN_DURING         = 9;
$ALLEN_FINISHES       = 10;
$ALLEN_RIGHT_OVERLAPS = 11;
$ALLEN_EXTENDS        = 12;
$ALLEN_AFTER          = 13;

##############################################################################
# Class variables
##############################################################################

$DisplayFormat = "%d/%m/%Y";                 # Default <display format>
$DefaultType   = $RIGHT_OPEN_INT;            # Default <interval type>

Interval.pm  view on Meta::CPAN

    can be used to create an Interval. However, the start date must be
    greater than the stop date. Because Date::Manip both handles dates
    and times this module can also handle both dates and times.

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

=head2 Open and Closed Intervals

    A closed interval is closed in an interval where both the start
    and the stop values are included in the interval. As an example
    [10-10-1997, 10-30-1997] both the 10th and the 30th of November is
    a part of the interval.

    An open interval is an interval where the start value or the stop
    value are not included in the interval. In the right open interval
    [10-10-1997, 10-30-1997) the 10th of November is a part of the
    interval but the 30th of November is not. 

    There are three types of open intervals
    - right open intervals, e.g., [10-10-1997, 10-30-1997)
    - left open intervals, e.g., (10-10-1997, 10-30-1997]
    - open intervals, e.g., (10-10-1997, 10-30-1997)

=head2 Absolute and Relative Intervals 

    An absolute interval is an interval where the start and the stop
    values of the inteval are anchored on the time line, i.e., they
    are specific dates as 04-30-1994.

    A relative interval is an interval where the start or the stop
    value is not anchored on the time line, e.g., 'tomorrow'. When
    'tomorrow' evaluated now it has one value when evaluated a month
    from now it has a different values.

    Date::Interval fully supports absolute intervals and to a limited
    degree relative intervals. 

    The relative intervals supported currently (NOW :-)) are of the
    following type.

    $int1 = new Date::Interval("10-21-1997", 'NOBIND NOW');

    Relative start and stop values are prefixed with the word
    'NOBIND'. In the example 'NOBIND NOW' means that the current time
    (now) whenever it asked for. So if you ask for the length of $int1
    at the 24th of October you get 3 days. If you ask for the length
    of $int1 again at the 28th of October you get 7 days.

    I am working on additional support for relative Intervals.

=head2 Defaults 

    The default interval type is right open intervals. Stick to this
    interval type if you want to keep life simple.

    To use Date::Manip the time zone variable must be set. It is
    default set to Central European Time (CET). For Americans, this is
    the Capital of Stockholm :-).

    To change the time zone, e.g., to Eastern Standard Time (EST) put
    in our script $Date::Manip::TZ = 'EST'; (As an European I assume
    this must be close to Atlanta, New Mexico).

    The default input format is default of Date::Manip, that is
    "10-12-1997" is the 12th of October 1997 not the 10th of December
    1997. To change the input format, e.g., put in our script
    &Date::Manip::Date_Init("DateFormat=non-US");

    The default output format is MM-DD-YYY. It Can be changed by
    calling Interval->setDisplayFormat(<string>). Where <string> is
    a UnixDate format in Date::Manip.

    The default separator when an interval is printed is the special
    variable $, $OUTPUT_FIELD_SEPARATOR. If this value is not defined
    ',' is used.

=head2 The "Fixed" Clock

    The module has a class variable $NOW which contains the current
    time. The current time must be fixed when relative intervals are
    compared, otherwise the comparison may return the wrong result. As
    an example if the two intervals [NOBIND NOW, NOBIND NOW) [NOBIND
    NOW, NOBIND NOW) are compared for equality the result is
    true. However, if the equality comparison is implemented by asking
    four time for the current time the times returned may be different
    because the *real world clock* ticks between the invocations of
    getting the current time. If the clock ticks the equality
    predicate in the example returns false.

    Because different interval objects must be compared with the same
    clock the variable must be a class variable and not an instance
    variable. $NOW is used in the method _to_date.

=head2 "Non-terminals" used in the Source Code

=over 4

=item   
    <delta>              ::= Date::Manip delta data type

=item 
    <date>               ::= Date::Manip data type

=item 
    <interval end>       ::= CLOSE || OPEN

=item 
    <interval type>      ::= CLOSED_INT || OPEN_INT || LEFT_OPEN_INT || RIGHT_OPEN_INT

=item 
    <value type>         ::= ABSOLUTE || RELATIVE

=item 
    <overlap type>       ::= How two intervals overlaps

=item 
    <Allen overlap type> ::= How two intervals Allen overlaps

=back


=head1 BUGS

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

    Note, the module cannot handle subtract intervals which overlap
    with "during" overlaps, this results in two intervals (currently
    results in an empty interval)

=head1 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 an error message and
      an empty interval is returned)

    - Implement getOverlap and overloaded operators for relative intervals

=head1 Change History
    ### Changes version 0.02 => 0.03 ###
    - TODO: during overlap

    - Made code to fit onto 80 columns
    - Added POD for each method/function

    ### Changes version 0.01 => 0.02 ###
    - Add overload  <, >, ==, !=, <=>. 
    - Add stringLength, to print length of interval in a more readable way.
    - Changed the default separator to the $, special variable
    - Added support for comparison of relative intervals 

    Changes thanks to Tim Bruce
    - Changed the module name from Interval to Date::Interval
    - Added methods getStart and getStop.
    - Added method lengthString to print nicely the length of the
      interval.
    - Changed the default output format to be similar to the 
      default input format
    - Taken BEGIN {$Date::Manip::TZ = "CET"; &Date_Init ("DateFormat=non-US");}
      out because it is anti-social :-)
    - Added to POD that the both dates and times can be used with intervals
    - Added to POD the description of open and closed intervals

=head1 LITTERATURE

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

=head1 AUTHORS

Kristian Torp <F<torp@cs.auc.dk>>

=cut