Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Date::ICal(3)	      User Contributed Perl Documentation	 Date::ICal(3)

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

       $Revision: 678 $

	   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 );

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

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

	   $ical2 = $ical + $duration;

       (Where $duration	is either a duration string, like 'P2W3DT7H9M',	or a
       Date::ICal::Duration (qv) object.

	   $ical += 'P6DT12H';

	   $duration = $ical - $ical2;
	   $ical3 = $ical - $duration;

       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

       Rich Bowen, and the Reefknot team. Alas,	Reefknot is no more. See for more modern and accurate modules.

       Last touched by $Author:	rbowen $

       Date::ICal has the following methods available:

       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

	   $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_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.

	   $seconds_plus_or_minus = offset_to_seconds($offset);

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

	   $seconds_plus_or_minus = offset_from_seconds($offset_in_seconds);

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

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


       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.

	   $self->add( year => 3, month	=> 2, week => 1, day =>	12,
		       hour => 1, minute => 34,	sec => 59 );
	   $date->add( duration	=> 'P1WT1H1M1S'	); # add 1 wk, 1 hr, 1 min, and	1 sec

       Adds a duration to a Date::ICal object.

       Supported paraters are: duration, eom_mode, year, month,	week, day,
       hour, min, sec or seconds.

       'duration' is a ICalendar duration string (see duration_value).

       If a value is undefined or omitted, 1 is	assumed:

	   $ical->add( 'minute'	); # add a minute

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

       Adding months or	years can be done via three different methods,
       specified by the	eom_mode parameter, which then applies to all
       additions (or subtractions) of months or	years following	it in the
       parameter list.

       The default, eom_mode =>	'wrap',	means adding months or years that
       result in days beyond the end of	the new	month will roll	over into the
       following month.	 For instance, adding one year to Feb 29 will result
       in Mar 1.

       If you specify eom_mode => 'limit', the end of the month	is never
       crossed.	 Thus, adding one year to Feb 29, 2000 will result in Feb 28,
       2001.  However, adding three more years will result in Feb 28, 2004,
       not Feb 29.

       If you specify eom_mode => 'preserve', the same calculation is done as
       for 'limit' except that if the original date is at the end of the month
       the new date will also be.  For instance, adding	one month to Feb 29,
       2000 will result	in Mar 31, 2000.

       All additions are performed in the order	specified.  For	instance, with
       the default setting of eom_mode => 'wrap', adding one day and one month
       to Feb 29 will result in	Apr 1, while adding one	month and one day will
       result in Mar 30.

	   $date = $date1 + $duration;

       Where $duration is either a duration string, or a Date::ICal::Duration

	   $date += 'P2DT4H7M';

       Adds a duration to a date object. Returns a new object, or, in the case
       of +=, modifies the existing object.

       Given a duration	string,	this function returns the number of days,
       seconds,	and months represented by that duration. In that order.	Seems
       odd to me. This should be considered an internal	function, and you
       should expect the API to	change in the very near	future.

	 $duration = $date1 - $date2;

       Subtract	one Date::ICal object from another to give a duration -	the
       length of the interval between the two dates. The return	value is a
       Date::ICal::Duration object (qv)	and allows you to get at each of the
       individual components, or the entire duration string:

	   $d =	$date1 - $X;

       Note that $X can	be any of the following:

       If $X is	another	Date::ICal object (or subclass thereof)	then $d	will
       be a Date::ICal::Duration object.

	   $week = $d->weeks; #	how many weeks apart?
	   $days = $d->as_days;	# How many days	apart?

       If $X is	a duration string, or a	Date::ICal::Diration object, then $d
       will be an object in the	same class as $date1;

	   $newdate = $date - $duration;

	   $copy = $date->clone;

       Returns a replica of the	date object, including all attributes.

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

	   my $day = $date->day;

       Returns the day of the month.

       Day is in the range 1..31

	   my $month = $date->month;

       Returns the month of the	year.

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

	   my $year = $date->year;

       Returns the year.

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

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

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

	 $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

	   my $day_of_week = $date->day_of_week

       Returns the day of week as 0..6 (0 is Sunday, 6 is Saturday).

	   my $hour = $date->hour

       Returns the hour	of the day.

       Hour is in the range 0..23

	   my $min = $date->min;

       Returns the minute.

       Minute is in the	range 0..59

	   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.

	 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

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

       - add gmtime and	localtime methods, perhaps?
       - Fix the INTERNALS file	so that	it actually reflects reality

       Please see the file INTERNALS for discussion on the internals.

       Rich Bowen (DrBacchus)

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

SEE ALSO mailing list



perl v5.32.1			  2011-07-05			 Date::ICal(3)


Want to link to this manual page? Use this URL:

home | help