NAME

Date::ICal - Perl extension for ICalendar date objects.

SYNOPSIS

use Date::ICal;

$ical = Date::ICal->new( ical => '19971024T120000' );
$ical = Date::ICal->new( epoch => time );
$ical = Date::ICal->new( year => 1964,
    month => 10, day => 16, hour => 16,
    min => 12, sec => 47, tz => '0530' );

$hour = $ical->hour;
$year = $ical->year;

$ical_string = $ical->ical;
$epoch_time = $ical->epoch;

DESCRIPTION

Date::ICal talks the ICal date format, and is intended to be a base class for other date/calendar modules that know about ICal time format also.

See http://dates.rcbowen.com/unified.txt for details

METHODS

Date::ICal has the following methods available:

new

A new Date::ICal object can be created with any valid ICal string:

my $ical = Date::ICal->new( ical => '19971024T120000' );
# will default to the timezone specified in $TZ, see below

Or with any epoch time:

my $ical = Date::ICal->new( epoch => time );

Or, better still, create it with components

my $date = Date::ICal->new( 
                       day => 25, 
                       month => 10, 
                       year => 1066,
                       hour => 7,
                       min => 15,
                       sec => 47
                       );

If you call new without any arguments, you'll get a Date::ICal object that is set to the time right now.

my $ical = Date::ICal->new();

If you already have an object in Date::ICal, or some other subclass thereof, you can create a new Date::ICal (or subclass) object using that object to start with. This is particularly useful for converting from one calendar to another:

# Direct conversion from Discordian to ISO dates
my $disco = Date::Discordian->new( disco => '12 Chaos, YOLD 3177' );
my $iso = Date::ISO->new( $disco );
print $iso->iso;

new() handles timezones. It defaults times to UTC (Greenwich Mean Time, also called Zulu). If you want to set up a time that's in the US "Pacific" timezone, which is GMT-8, use something like:

 my $ical = Date::ICal->new( ical => '19971024T120000',
                             offset => "-0800");

Note that as of version 1.44, new() tries to be intelligent about figuring out your local time zone. If you enter a time that's not *explicitly* in UTC, it looks at the environment variable $TZ, if it exists, to determine your local offset. If $TZ isn't set, new() will complain.

ical

$ical_string = $ical->ical;

Retrieves, or sets, the date on the object, using any valid ICal date/time string. Output is in UTC (ends with a "Z") by default. To get output in localtime relative to the current machine, do:

$ical_string = $ical->ical( localtime => 1 );

To get output relative to an arbitrary offset, do:

$ical_string = $ical->ical( offset => '+0545' );

epoch

$epoch_time = $ical->epoch;

$ical->epoch( 98687431 );

Sets, or retrieves, the epoch time represented by the object, if it is representable as such. (Dates before 1971 or after 2038 will not have an epoch representation.)

Internals note: The ICal representation of the date is considered the only authoritative one. This means that we may need to reconstruct the epoch time from the ICal representation if we are not sure that they are in synch. We'll need to do clever things to keep track of when the two may not be in synch. And, of course, the same will go for any subclasses of this class.

_offset_to_seconds

 $seconds_plus_or_minus = offset_to_seconds($offset);

Changes -0600 to -18000. Not object method, no side-effects.

_offset_from_seconds

 $seconds_plus_or_minus = offset_from_seconds($offset_in_seconds);

Changes -18000 (seconds) to -0600 (hours, minutes). Not object method, no side-effects.

offset

 $offset = $ical->offset;

 # We need tests for these.  
 $ical->offset( '+1100' ); # a number of hours and minutes: UTC+11
 $ical->offset( 0 );       # reset to UTC

Sets or retrieves the offset from UTC for this time. This allows timezone support, assuming you know what your local (or non-local) UTC offset is. Defaults to 0.

Internals note: all times are internally stored in UTC, even though they may have some offset information. Offsets are internally stored in signed integer seconds.

BE CAREFUL about using this function on objects that were initialized with an offset. If you started an object with:

my $d = new(ical=>'19700101120000', offset=>'+0100'); 

and you then call:

$d->offset('+0200'); 

you'll be saying "Yeah, I know I *said* it was in +0100, but really I want it to be in +0200 now and forever." Which may be your intention, if you're trying to transpose a whole set of dates to another timezone--- but you can also do that at the presentation level, with the ical() method. Either way will work.

add

$date->add( %hash ); # Hash of day, hour, min, etc, values
$date->add( ical => $ical_duration_string );

Adds a duration to a Date::ICal object.

Duration should be passed in as either an ical string, or as a hash of date/time properties.

The result will be normalized. That is, the output time will have meaningful values, rather than being 48:73 pm on the 34th of hexadecember.

$self->add( month=>2 );
$self->add( duration =>'P1W' );

compare

$cmp = $date1->compare($date2);

@dates = sort {$a->compare($b)} @dates;

Compare two Date::ICal objects. Semantics are compatible with sort; returns -1 if $a < $b, 0 if $a == $b, 1 if $a > $b.

day

my $day = $date->day;

Returns the day of the month.

Day is in the range 1..31

month

my $month = $date->month;

Returns the month of the year.

Month is returned as a number in the range 1..12

year

my $year = $date->year;

Returns the year.

jd2greg

($year, $month, $day) = jd2greg( $jd );

Convert number of days on or after Jan 1, 1 CE (Gregorian) to
gregorian year,month,day.

greg2jd

$jd = greg2jd( $year, $month, $day );

Convert gregorian year,month,day to days on or after Jan 1, 1 CE
(Gregorian).  Normalization is performed (e.g. month of 28 means
April two years after given year) for month < 1 or > 12 or day < 1
or > last day of month.

days_this_year

$yday = Date::ICal::days_this_year($day, $month, $year);

Returns the number of days so far this year. Analogous to the yday attribute of gmtime (or localtime) except that it works outside of the epoch.

hour

my $hour = $date->hour

Returns the hour of the day.

Hour is in the range 0..23

min

my $min = $date->min;

Returns the minute.

Minute is in the range 0..59

sec

my $sec = $date->sec;

Returns the second.

Second is in the range 0..60. The value of 60 is (maybe) needed for leap seconds. But I'm not sure if we're going to go there.

julian

my $jd = $date->jd;

Returns a listref, containing two elements. The date as a julian day, and the time as the number of seconds since midnight. This should not be thought of as a real julian day, because it's not. The module is internally consistent, and that's enough.

This method really only is here for compatibility with previous versions, as the jd method is now thrown over for plain hash references.

See the file INTERNALS for more information about this internal format.

TODO

- add timezone support, including moving between timezones

- add gmtime and localtime methods, perhaps?

INTERNALS

Please see the file INTERNALS for discussion on the internals.

AUTHOR

Rich Bowen (DrBacchus) rbowen@rcbowen.com

And the rest of the Reefknot team. See the source for a full list of patch contributors and version-by-version notes.

SEE ALSO

datetime@perl.org mailing list

http://reefknot.org/

http://dates.rcbowen.com/

Time::Local

Net::ICal

# CVS History #{{{

CVS History

$Log: ICal.pm,v $
Revision 1.55  2001/11/28 02:00:16  rbowen
Able to add n years to a date via the add method. Tests to match.

Revision 1.54  2001/11/24 18:57:37  rbowen
Oops. I reversed the order of the argument list when I added this
function back in, thereby breaking all code that was calling it.

Revision 1.53  2001/11/24 16:25:10  rbowen
Since _seconds_from_offset returns a number, not a string, we only need
the sign if it is negative. Resolves some test failures that I was
seeing in t/08offset.t for negative offsets.

Revision 1.52  2001/11/24 03:42:39  rbowen
Resolves one of the test failures in offset/add - when add crossed a day
boundary by virtue of a difference in seconds, it was not compenting in
the day value, and could end up with negative times.

Revision 1.51  2001/11/24 03:11:25  rbowen
Added back in days_this_year method using new greg2jd method.

Revision 1.50  2001/11/24 02:54:22  rbowen
This is Yitzchak's patch to give us much more efficient gregorian <->
julian conversions, and to remove strange anomolous problems in the 17th
and 18 centuries. Note that we lose a few internal methods here, at
least one of which I'll be putting back in a minute.

Revision 1.49  2001/11/22 10:56:23  srl
This version incorporates a patch by Yitzchak Scott-Thoennes to
adjust the offset() API. It no longer takes integer seconds
as a parameter, because there's no programmatic way to tell the
difference between, say, +3600 (UTC+1 in seconds) and +3600 (UTC+36,
if you interpret that as an HHMM value).

I also refactored things a bit, creating an _offset_from_seconds
method to match _offset_to_seconds; this should eliminate some
duplication. There's also new POD to clear up some confusion about
new(offset => foo) used together with offset().

Revision 1.48  2001/11/22 09:22:24  srl
API-consistency patch from Yitzchak Scott-Thoennes <sthoenna@efn.org>;
Makes the ical() method take a hash of parameters, not a hashref,
so that ical() is like the other methods. This crept in around 1.44,
and it shouldn't have. My mistake.

Revision 1.47  2001/11/22 09:02:34  srl
Fixed some 5.6isms; patch contributed by Yitzchak Scott-Thoennes
<sthoenna@efn.org>.

Revision 1.46  2001/11/15 13:25:04  srl
Minor patches to tests; another piece of optimization from Mike Heins.

Revision 1.45  2001/11/15 05:32:17  srl
Added benchmark.pl to help developers in optimizing the module.
Also modified new() to warn more clearly if the $TZ environment
variable isn't set, and not to utterly fail tests if $TZ isn't there.

Revision 1.44  2001/11/15 05:11:32  srl
Further patches from Mike Heins, plus some documentation from me:
	- added localtime argument to ical() for output in localtime.
	  Added documentation about the localtime argument. Note
          that $ENV{$TZ} is now relevant to some of the module's behavior.
	- removed a memoize() that wasn't providing significant speed
	  improvements.
	- minor optimization of _calc_local_offset

Revision 1.43  2001/11/15 04:20:38  srl
Committed another small patch by Mike Heins, which precalculates
the values returned by the months() function so that the module
is faster at runtime.

Revision 1.42  2001/11/15 04:11:13  srl
Another patch from Mike Heins (mheins@minivend.com); an optimizing
cheat for leapyears; uses a precalculated table of values instead
of always calculating leapyear values. I edited Mike's patch slightly
so that @leapcheat isn't a package global.

Revision 1.41  2001/11/15 03:58:34  srl
Incorporated part of a patch by Mike Heins (mheins@minivend.com);
an optimization. Internal storage of julian times is now in
$self->{julian} and $self->{julsec}, instead of using an array.
This gives us slightly better speed. Also, made some of the UTC
behaviors slightly more consistent.

Revision 1.40  2001/10/16 10:33:44  srl
Further fixes to the offset() method. This code isn't as well-tested
as I'd like it to be, but it seems to do the right thing for all the
tests that are there. I had to revise many of the tests, because
the API semantics have changed. Times must now be explicitly
specified with a Z in order to be handled as UTC.

Revision 1.39  2001/10/10 02:58:29  srl
Added some tests, reorganized some code to prepare spaces for
offset/timezone-aware output. Added at least one test that's
known to fail for purposes of knowing when we succeed. :)

Revision 1.38  2001/10/09 04:28:58  srl
Started working on code to properly handle times with offsets from GMT.
added a new _calc_local_offset method to figure out what the
current machine's UTC offset is. We need tests for this that will
work in any timezone; patches welcome.

Revision 1.37  2001/09/30 13:19:14  lotr
* Oops, forgot some bits when I added month to add()
* use overload for compare

Revision 1.36  2001/09/29 11:01:55  lotr
Add the ability to add months to a date. Needed for Net::ICal::Recurrence

Revision 1.35  2001/09/26 15:26:09  lotr
* fix off-by-one error in months() and add tests for that

Revision 1.34  2001/09/12 03:26:23  rbowen
There's no particular reason to have Date::ICal be 5.6 dependant.

Revision 1.33  2001/08/25 12:20:30  rbowen
Fixed bug reported by Chris Jones. In sub add, I was checking one
attribute and using another. Added tests for this bug, and for adding
durations by attribute.

Revision 1.32  2001/08/10 03:27:47  srl
Started adding timezone support by making an offset() method and an offset
property. This still needs to be wired into the new() method and the
output methods, but we have to resolve some interface details first.

Revision 1.31  2001/08/07 02:41:11  rbowen
Test::More gets angry if there are no tests.

Revision 1.30  2001/08/07 02:30:01  rbowen
Moved the inline tests into t/ for the sake of making the module more
readable. Please don't let this discorage you from writing inline
tests.

Revision 1.29  2001/08/06 19:32:39  rbowen
Creating an object without args was calling gmtime( $args{epoch} ).
Fixed and added tests. Also added Time::HiRes to PREREQ list.

Revision 1.28  2001/08/06 18:45:47  rbowen
sub epoch was referencing another sub that has gone away. Fixed, and
added tests.

Revision 1.27  2001/08/02 04:38:16  srl
Adjusted the add() method to return a copy of $self instead of the
return value of $self->jd(). This was important to making
the Net::ICal tests pass, but it's also the Right Way, I think.

Revision 1.26  2001/08/02 03:47:59  rbowen
Handle negative durations correctly.

Revision 1.25  2001/08/01 02:19:03  rbowen
Two main changes here.
1) Split the internal date/time representation into date, time
integers, so that we don't have any more roundoff error.
2) Memoized the parsetime and parsedate methods, so that we're not
doing that three times every time we want three components, which we
were doing.

cpanm Date::ICal

perl -MCPAN -e shell
install Date::ICal