DateTime::Span - Datetime spans

    use DateTime;
    use DateTime::Span;

    $date1 = DateTime->new( year => 2002, month => 3, day => 11 );
    $date2 = DateTime->new( year => 2003, month => 4, day => 12 );
    $set2 = DateTime::Span->from_datetimes( start => $date1, end => $date2 );
    #  set2 = 2002-03-11 until 2003-04-12

    $set = $set1->union( $set2 );         # like "OR", "insert", "both"
    $set = $set1->complement( $set2 );    # like "delete", "remove"
    $set = $set1->intersection( $set2 );  # like "AND", "while"
    $set = $set1->complement;             # like "NOT", "negate", "invert"

    if ( $set1->intersects( $set2 ) ) { ...  # like "touches", "interferes"
    if ( $set1->contains( $set2 ) ) { ...    # like "is-fully-inside"

    # data extraction 
    $date = $set1->start;           # first date of the span
    $date = $set1->end;             # last date of the span

DateTime::Span is a module for date/time spans or time-ranges.

* from_datetimes

Creates a new span based on a starting and ending datetime. A 'closed' span includes its end-dates:

   $span = DateTime::Span->from_datetimes( start => $dt1, end => $dt2 );

An 'open' span does not include its end-dates:

   $span = DateTime::Span->from_datetimes( after => $dt1, before => $dt2 );

A 'semi-open' span includes one of its end-dates:

   $span = DateTime::Span->from_datetimes( start => $dt1, before => $dt2 );
   $span = DateTime::Span->from_datetimes( after => $dt1, end => $dt2 );

A span might have just a beginning date, or just an ending date. These spans end, or start, in an imaginary 'forever' date:

   $span = DateTime::Span->from_datetimes( start => $dt1 );
   $span = DateTime::Span->from_datetimes( end => $dt2 );
   $span = DateTime::Span->from_datetimes( after => $dt1 );
   $span = DateTime::Span->from_datetimes( before => $dt2 );

You cannot give both a start and after argument, nor can you give both an end and before argument. Either of these conditions will cause the CWfrom_datetimes() method to die.

* from_datetime_and_duration

Creates a new span.

   $span = DateTime::Span->from_datetime_and_duration( 
       start => $dt1, duration => $dt_dur1 );
   $span = DateTime::Span->from_datetime_and_duration( 
       after => $dt1, hours => 12 );

The new end of the set is open by default.

* clone

This object method returns a replica of the given object. This method accepts either a time zone object or a string that can be passed as the name parameter to CWDateTime::TimeZone->new(). If the new time zone's offset is different from the old time zone, then the local time is adjusted accordingly. If the old time zone was a floating time zone, then no adjustments to the local time are made, except to account for leap seconds. If the new time zone is floating, then the UTC time is adjusted in order to leave the local time untouched.

* duration

The total size of the set, as a CWDateTime::Duration object, or as a scalar containing infinity. Also available as CWsize().

* start

* end

First or last dates in the span. It is possible that the return value from these methods may be a DateTime::Infinite::Future or a DateTime::Infinite::Past object. If the set ends CWbefore a date CW$dt, it returns CW$dt. Note that in this case CW$dt is not a set element - but it is a set boundary.

* start_is_closed

* end_is_closed

Returns true if the first or last dates belong to the span ( begin <= x <= end ).

* start_is_open

* end_is_open

Returns true if the first or last dates are excluded from the span ( begin < x < end ).

* union

* intersection

* complement

Set operations may be performed not only with CWDateTime::Span objects, but also with CWDateTime::Set and CWDateTime::SpanSet objects. These set operations always return a CWDateTime::SpanSet object.

    $set = $span->union( $set2 );         # like "OR", "insert", "both"
    $set = $span->complement( $set2 );    # like "delete", "remove"
    $set = $span->intersection( $set2 );  # like "AND", "while"
    $set = $span->complement;             # like "NOT", "negate", "invert"

* intersects

* contains

These set functions return a boolean value.

    if ( $span->intersects( $set2 ) ) { ...  # like "touches", "interferes"
    if ( $span->contains( $dt ) ) { ...    # like "is-fully-inside"

These methods can accept a CWDateTime, CWDateTime::Set, CWDateTime::Span, or CWDateTime::SpanSet object as an argument.

Support is offered through the CWdatetime@perl.org mailing list.

Please report bugs using rt.cpan.org

Flavio Soibelmann Glock <fglock@pucrs.br>

The API was developed together with Dave Rolsky and the DateTime Community.

Copyright (c) 2003 Flavio Soibelmann Glock. All rights reserved. This program is free software; you can distribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

Set::Infinite

For details on the Perl DateTime Suite project please see <http://datetime.perl.org>.