NAME

DateTime::Span - Datetime spans

SYNOPSIS

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

DESCRIPTION

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

METHODS

• from_datetimes

  Creates a new span based on a starting and ending datetime.

  A 'closed' span includes its end-dates:

  $dates = DateTime::Set->new( start => $dt1, end => $dt2 );

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

  $dates = DateTime::Set->new( after => $dt1, before => $dt2 );

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

  $dates = DateTime::Set->new( start => $dt1, before => $dt2 );
  $dates = DateTime::Set->new( 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:

  $dates = DateTime::Set->new( start => $dt1 );
  $dates = DateTime::Set->new( end => $dt2 );
  $dates = DateTime::Set->new( after => $dt1 );
  $dates = DateTime::Set->new( 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 cause will cause the new() method to die.

• from_datetime_and_duration

  Creates a new span.

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

  The new "end of the set" is open by default.

• duration

  The total size of the set, as a DateTime::Duration object, or as a scalar containing infinity.

  Also available as size().

• start / end

  First or last dates in the span. It is possible that the return value from these methods may be a scalar containing either negative infinity or positive infinity.

• 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 DateTime::Span objects, but also with DateTime::Set and DateTime::SpanSet objects. These set operations always return a DateTime::SpanSet object.

  $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"

• intersects / contains

  These set functions return a boolean value.

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

SUPPORT

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

Please report bugs using rt.cpan.org

AUTHOR

Flavio Soibelmann Glock <fglock@pucrs.br>

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

COPYRIGHT

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.

SEE ALSO

Set::Infinite

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