NAME

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

SYNOPSIS

$t = new Net::ICal::Time("19970101T120000Z");
$t = new Net::ICal::Time("19970101T120000","America/Los_Angeles");
$t = new Net::ICal::Time(time(),"America/Los_Angeles");

$t2 = $t->add(Net::Ical::Duration("1D"));

$duration = $t->subtract(Net::ICal::Time("19970101T110000Z"))

# Add 5 minutes
$t->min($t->min()+5);

# Add 5 minutes
$t->sec($t->sec()+300);

# Compare
if($t->compare($t2) > 0) {}

DESCRIPTION

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

new

Creates a new time object given one of:

• ISO format string

• Some other format string, maybe whatever a Date module understands

• Integer representing seconds past the POSIX epoch

The optional second argument is the timezone in Olsen place name format, which looks like "America/Los_Angeles"; it can be used to get the standard offset from UTC, the dates the location goes to and from Daylight Savings Time, and the magnitude of the Daylight Savings time offset.

clone()

Create a new copy of this time.

is_valid()

TBD

is_date([true|false])

Accessor to the is_date flag. If true, the flag indicates that the hour, minute and second fields are set to zero and not used in comparisons.

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.

normalize()

Adjust any out-of range values so that they are in-range. For instance, 12:65:00 would become 13:05:00.

hour([$hour])

Accessor to the hour. Out of range values are normalized.

Accessor to the minute. Out of range values are normalized.

Accessor to the second. Out of range values are normalized. For instance, setting the second to -1 will decrement the minute and set the second to 59, while setting the second to 3600 will increment the hour.

year([$year])

Accessor to the year. Out of range values are normalized.

month([$month])

Accessor to the month. Out of range values are normalized.

day([$day])

Accessor to the month day. Out of range values are normalized.

add($duration)

Takes a 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".

as_ical()

Convert to an iCal format time string.

as_ical()

Convert to an iCal format property string.

as_int()

Convert the time to an integer that represents seconds past the POSIX epoch

as_localtime()

Convert to list format, as per localtime()

as_gmtime()

Convert to list format, as per gmtime()

compare($time)

Compare a time to this one and return -1 if the argument is earlier than this one, 1 if it is later, and 0 if it is the same. The routine does the comparision after converting the time to UTC. It converts floating times using the system's notion of the timezone.

day_of_week()

Return 0-6 representing day of week of this date. Could be replaced with (gmtime($t->as_int()))[6]

day_of_year()

Return 1-365 representing day of year of this date. Could be replaced with (gmtime($t->as_int()))[7]

start_of_week()

Return the day of year of the first day (Sunday) of the week that this date is in

cpanm Net::ICal

perl -MCPAN -e shell
install Net::ICal