Net::ICal::Period - represent a period of time

Net-ICal documentation Contained in the Net-ICal distribution.

Index

Code Index:

NAME

Top

Net::ICal::Period -- represent a period of time

SYNOPSIS

Top

  use Net::ICal;
  $p = new Net::ICal::Period("19970101T120000","19970101T123000");
  $p = new Net::ICal::Period("19970101T120000","PT3W2D40S");
  $p = new Net::ICal::Period(time(),3600);
  $p =   new Net::ICal::Period(
		      new Net::ICal::Time("19970101T120000",
					  "America/Los_Angeles"),
		      new Net::ICal::Duration("2h"));

DESCRIPTION

Top

Use this to make an object representing a block of time on a real schedule. You can either say, "This event starts at 12 and ends at 2" or "This event starts at 12 and lasts 2 hours."

These two ways of specifying events can be treated differently in schedules. If you say, "The meeting is from 12 to 2, but I have to leave at 2," you are implying that the start date and end date are fixed. If you say, "I have a 2-hour drive to Chicago, and I need to leave at 4," you are saying that it will take 2 hours no matter when you leave, and that moving the start time will slide the end time correspondingly.

BASIC METHODS

Top

new($time, $time|$duration)

Creates a new period object given to parameters: The first must be a Time object or valid argument to Net::ICal::Time::new.

The second can be either:

* a Time object
* a valid argument to Net::ICal::Time::new.
* a Duration object
* a valid argument to Net::ICal::Duration::new.

Either give a start time and an end time, or a start time and a duration.

new($time, $time|$duration)

Creates a new period object given to parameters: The first must be a Time object or valid argument to Net::ICal::Time::new.

The second can be either:

* a Time object
* a valid argument to Net::ICal::Time::new.
* a Duration object
* a valid argument to Net::ICal::Duration::new.

Either give a start time and an end time, or a start time and a duration.

Create a copy of this component

is_valid()

Return true if: There is an end time and: Both start and end times have no timezone ( Floating time) or Both start and end time have (possibly different) timezones or Both start and end times are in UTC and The end time is after the start time. 

  There is a duration and the duration is positive

Accessor for the start time of the event as a Time object. Can also take a valid time string or an integer (number of seconds since the epoch) as a parameter. If a second parameter is given, it'll set this Duration's start time.

Accessor for the end time. Takes a Time object, a valid time string, or an integer and returns a time object. This routine is coupled to the duration accessor. See duration below for more imformation.

Accessor for the duration of the event. Takes a duration object and returns a Duration object.

Since the end time and the duration both specify the end time, the object will store one and access to the other will be computed. So,

if you create:

   $p = new Net::ICal::Period("19970101T120000","19970101T123000")

And then execute:

   $p->duration(45*60);

The period object will adjust the end time to be 45 minutes after the start time. It will not replace the end time with a duration. This is required so that a CUA can take an incoming component from a server, modify it, and send it back out in the same basic form.

as_ical_value

Another name for as_ical.

compare([$time])

Takes a Net::ICal::Time as a parameter. If the parameter is a Time, returns 0 if time is in the period, -1 if the time is before the period and 1 if the time is after the period.

union([$period])

Takes another Period as a parameter. Returns 0 if the given period overlaps this period, -1 if the given Period is before this one, and 1 if the given Period is after this one.

SEE ALSO

Top

More documentation pointers can be found in Net::ICal.

Net-ICal documentation Contained in the Net-ICal distribution. 
#!/usr/bin/perl -w
# -*- Mode: perl -*-
#======================================================================
#
# This package is free software and is provided "as is" without
# express or implied warranty.  It may be used, redistributed and/or
# modified under the same terms as perl itself. ( Either the Artistic
# License or the GPL. )
#
# $Id: Period.pm,v 1.19 2001/08/04 04:59:36 srl Exp $
#
# (C) COPYRIGHT 2000-2001, Reefknot developers.
#
# See the AUTHORS file included in the distribution for a full list.
#======================================================================


package Net::ICal::Period;
use strict;

use UNIVERSAL;
use base qw(Net::ICal::Property);

use Data::Dumper;
use Net::ICal::Duration;
use Net::ICal::Time;



#-------------------------------------------------------------------------


sub new{
  my ($package, $arg1, $arg2) = @_;
  
  return undef unless (defined($arg1) && defined($arg2) );
  
  my $self = {};

  # Is the string in RFC2445 Format?
  if(!$arg2 and $arg1 =~ /\//){
    my $tmp = $arg1;
    ($arg1,$arg2) = split(/\//,$tmp);
  }


  if( ref($arg1) eq 'Net::ICal::Time'){
    $self->{START} = $arg1->clone();
  } else  {
    $self->{START} = new Net::ICal::Time(ical => $arg1);
  } 
    

  if(UNIVERSAL::isa($arg2,'Net::ICal::Time')){ 
    $self->{END} = $arg2->clone();
  } elsif (UNIVERSAL::isa($arg2,'Net::ICal::Duration')) {
    $self->{DURATION} = $arg2->clone();
  } elsif ($arg2 =~ /^P/) {
    $self->{DURATION} = new Net::ICal::Duration($arg2);
  } else {
    # Hope that it is a time string
    $self->{END} = new Net::ICal::Time(ical => $arg2);
  }

  return bless($self,$package);
}

#--------------------------------------------------------------------------

sub clone {
    my $self = shift;

    my $class = ref($self);
    return bless( {%$self}, $class );

}

#----------------------------------------------------------------------------


# XXX implement this

sub is_valid {
    return "Not implemented";
}

#---------------------------------------------------------------------------

sub start{
  my $self = shift;
  my $t = shift;

  if($t){
    if(UNIVERSAL::isa($t,'Net::ICal::Time')){ 
      $self->{START} = $t->clone();
    } else {
      $self->{START} = new Net::ICal::Time($t);
    }
  }

  return $self->{START};
} 

#-----------------------------------------------------------------

sub end{

  my $self = shift;
  my $t = shift;
  my $end;

  if($t){
    if(UNIVERSAL::isa($t,'Net::ICal::Time')){
      $end = $t->clone();
    } else {
      $end = new Net::ICal::Time($t);
    }
    
    # If duration exists, use the time to compute a new duration
    if ($self->{DURATION}){
      $self->{DURATION} = $end->subtract($self->{START}); 
    } else {
      $self->{END} = $end;
    }    
  }

  # Return end time, possibly computing it from DURATION
  if($self->{DURATION}){
    return $self->{START}->add($self->{DURATION});
  } else {
    return $self->{END};
  }

} 

#----------------------------------------------------------------------

sub duration{
  my $self = shift;
  my $d = shift;
  my $dur;

  if($d){
    if(UNIVERSAL::isa($d,'Net::ICal::Duration')){ 
      $dur = $d->clone();
    } else {
      $dur = new Net::ICal::Duration($d);
    }
    
    # If end exists, use the duration to compute a new end
    # otherwise, set the duration. 
    if ($self->{END}){
      $self->{END} = $self->{START}->add($dur); 
    } else {
      $self->{DURATION} = $dur;
    }    
  }

  # Return duration, possibly computing it from END
  if($self->{END}){
    return $self->{END}->subtract($self->{START});
  } else {
    return $self->{DURATION};
  }

}

#------------------------------------------------------------------------


sub as_ical {
  my $self = shift;
  my $out;

  my $colon_clipped_date = $self->{START}->as_ical_value();
  $out = $colon_clipped_date ."/";

  if($self->{DURATION}){
    $out .= $self->{DURATION}->as_ical_value(); 
  } else {
    $colon_clipped_date = $self->{END}->as_ical_value();
    $out .= $colon_clipped_date;
  }
 
  return $out;
 
}


sub as_ical_value {
  my $self = shift;

  return $self->as_ical();
}




sub compare {
    my ($self, $t) = @_;
    my $time;

    if($t){
        
        if(UNIVERSAL::isa($t,'Net::ICal::Time')){
            $time = $t->clone();
        } else {
            $time = new Net::ICal::Time(ical => $t);
        }
        
        # If the time is before the start of the duration
        if($self->start->compare($time) < 0) {
            return -1;
        }
        # If the time is after the end of the duration
        if($self->end->compare($time) >= 0) {
            return 1;
        }

        return 0;
    }

  return undef;
}





# XXX: Perhaps this should return a Period if the two periods overlap.
# Or maybe that's a separate function.
sub union {

  my ($self, $period2) = @_;

  # does $period2 overlap with this period?
  if($period2){

    # If the start of the parameter period is after this period:
    if($self->end->compare($period2->start) >= 0) {
      return 1;
    }
    # If the end of this period is before the end of the parameter period
    if($self->start->compare($period2->end) <= 0) {
      return -1;
    }
    return 0;
  }

  return undef;
}

1;