Net::ICal::Time - represent a time and date

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

Index

Code Index:

NAME

Top

Net::ICal::Time -- represent a time and date

SYNOPSIS

Top

    $t = Net::ICal::Time->new( epoch => time );
    $t = Net::ICal::Time->new( ical => '19970101' );
    $t = Net::ICal::Time->new( ical => '19970101T120000',
        timezone => 'America/Los_Angeles' );

    # Eventually ...
    $t = Net::ICal::Time-new( iso => '1997-10-14' );
    # or other time formats ...

    # Not yet implemented
    $t = Net::ICal::Time->new(
        second => 12,
        minute => 5,
        hour => 6,
        day => 10,
        month => 9,
        year => 1997,
    );

    # Not yet implemented
    $t2 = $t->add( hour => '6' );

WARNING

Top

This is ALPHA QUALITY CODE. Due to a roundoff error in Date::ICal, which it's based on, addition and subtraction is often one second off. Patches welcome. See the README that came with this module for how you can help.

DESCRIPTION

Top

Time represents a time, but can also hold the time zone for the time and indicate if the time should be treated as a date. The time can be constructed from a variey of formats.

METHODS

Top

new

Creates a new time object given one of:

* epoch => integer seconds past the POSIX epoch.
* ical => iCalendar date-time string

If neither of these arguments is supplied, the value will default to the current date.

WARNING: Timezone handling is currently in flux in Net::ICal, pending Date::ICal awareness of timezones. This may change the call syntax slightly.

clone()

Create a new copy of this time.

zone

Accessor to the timezone. Takes & Returns an Olsen place name ("America/Los_Angeles", etc. ) , an Abbreviation, 'UTC', or 'float' if no zone was specified.

THIS IS NOT YET IMPLEMENTED. Date::ICal does not yet support timezones.

add($duration)

Takes a duration string or Duration and returns a Time that is the sum of the time and the duration. Does not modify this time.

subtract($time)

Subtract out a time of type Time and return a Duration. Does not modify this time.

move_to_zone($zone);

Change the time to what it would be in the named timezone. The zone can be an Olsen placename or "UTC".

THIS FUNCTION IS NOT YET IMPLEMENTED. We're waiting on Date::ICal to provide this function.

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. ) 
#
# (C) COPYRIGHT 2000-2001, Reefknot developers.
#
# See the AUTHORS file included in the distribution for a full list. 
#======================================================================


package Net::ICal::Time;
use strict;

use base qw(Date::ICal);

use Net::ICal::Duration;
use Time::Local;
use POSIX;
use Carp qw(confess cluck);
use UNIVERSAL;


# clone a Time object. 
sub clone {
  my $self = shift;

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

}



# XXX This needs to be defined. 
sub zone {}


sub add {
  my ($self, $param) = @_;
  
  # FIXME: need input validation here
  my $duration = $param;
  
  # be backwards-compatible for now. 
  if (UNIVERSAL::isa($param,'Net::ICal::Duration')) {
    #probably the Wrong Way, but it works for now. 
    $duration = $param->as_ical_value;   
  };

  # at this point, assume that duration is an iCalendar string.
  return $self->SUPER::add(duration=>$duration);

}


sub subtract {
  my $self = shift;
  my $param = shift;

  my $duration = $param;
  
  # be backwards-compatible for now. 
  if (UNIVERSAL::isa($param,'Net::ICal::Duration')) {
    # probably the Wrong Way, but it works for now. 
    $duration = $param->as_ical_value();   
  };

  $duration = "-" . $duration;  # negate the duration they gave, so we can subtract

  return $self->add($duration);

}


# XXX this needs implementing, possibly by Date::ICal. 
sub move_to_zone {
  confess "Not Implemented\n";
} 



sub as_ical {
  my $self = shift;
  
  # fallback to Date::ICal here
  return ":" . $self->ical; 
}

sub as_ical_value {
    my ($self) = @_;
    return $self->ical;
}


sub as_localtime {
  my $self = shift;

  return localtime($self->epoch());

}


sub as_gmtime {
  my $self = shift;

  return gmtime($self->epoch());

}


# XXX Implement this
sub day_of_week {
  my $self = shift;

  return (gmtime($self->epoch()))[6];
}


# XXX Implement this
sub day_of_year {
  my $self = shift;

  return (gmtime($self->epoch()))[7];
}



# XXX Implement this
sub start_of_week {
  my $self = shift;

  # There's an issue here when Sunday is in the previous year. Should we return
  # the day number in the previous year? But then the calling program has to
  # be smart enough to notice this, Ive chosen here to return a negative year
  # day to indicate last year (okay Im lazy means I don't have to worry about
  # leap years). Note that it seems that localtime etc count days from 0..364
  # rather than 1..365 as it states in the man pages, am I missing something??
  # Sunday is zero hence the need to subtract an extra day
  return $self->day_of_year() - $self->day_of_week() + 1;
}


1; 

__END__