Date::ICal(3pm)

1Date::ICal(3)         User Contributed Perl Documentation        Date::ICal(3)
2
3
4

NAME

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

VERSION

9       $Revision: 678 $
10

SYNOPSIS

12           use Date::ICal;
13
14           $ical = Date::ICal->new( ical => '19971024T120000' );
15           $ical = Date::ICal->new( epoch => time );
16           $ical = Date::ICal->new( year => 1964,
17               month => 10, day => 16, hour => 16,
18               min => 12, sec => 47 );
19
20           $hour = $ical->hour;
21           $year = $ical->year;
22
23           $ical_string = $ical->ical;
24           $epoch_time = $ical->epoch;
25
26           $ical2 = $ical + $duration;
27
28       (Where $duration is either a duration string, like 'P2W3DT7H9M', or a
29       Date::ICal::Duration (qv) object.
30
31           $ical += 'P6DT12H';
32
33           $duration = $ical - $ical2;
34           $ical3 = $ical - $duration;
35

DESCRIPTION

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

AUTHOR

42       Rich Bowen, and the Reefknot team. Alas, Reefknot is no more. See
43       http://datetime.perl.org/ for more modern and accurate modules.
44
45       Last touched by $Author: rbowen $
46

METHODS

48       Date::ICal has the following methods available:
49
50   new
51       A new Date::ICal object can be created with any valid ICal string:
52
53           my $ical = Date::ICal->new( ical => '19971024T120000' );
54           # will default to the timezone specified in $TZ, see below
55
56       Or with any epoch time:
57
58           my $ical = Date::ICal->new( epoch => time );
59
60       Or, better still, create it with components
61
62           my $date = Date::ICal->new(
63                                  day => 25,
64                                  month => 10,
65                                  year => 1066,
66                                  hour => 7,
67                                  min => 15,
68                                  sec => 47
69                                  );
70
71       If you call new without any arguments, you'll get a Date::ICal object
72       that is set to the time right now.
73
74           my $ical = Date::ICal->new();
75
76       If you already have an object in Date::ICal, or some other subclass
77       thereof, you can create a new Date::ICal (or subclass) object using
78       that object to start with. This is particularly useful for converting
79       from one calendar to another:
80
81          # Direct conversion from Discordian to ISO dates
82          my $disco = Date::Discordian->new( disco => '12 Chaos, YOLD 3177' );
83          my $iso = Date::ISO->new( $disco );
84          print $iso->iso;
85
86       new() handles timezones. It defaults times to UTC (Greenwich Mean Time,
87       also called Zulu). If you want to set up a time that's in the US
88       "Pacific" timezone, which is GMT-8, use something like:
89
90           my $ical = Date::ICal->new( ical => '19971024T120000',
91                                       offset => "-0800");
92
93       Note that as of version 1.44, new() tries to be intelligent about
94       figuring out your local time zone. If you enter a time that's not
95       *explicitly* in UTC, it looks at the environment variable $TZ, if it
96       exists, to determine your local offset. If $TZ isn't set, new() will
97       complain.
98
99   ical
100           $ical_string = $ical->ical;
101
102       Retrieves, or sets, the date on the object, using any valid ICal
103       date/time string. Output is in UTC (ends with a "Z") by default. To get
104       output in localtime relative to the current machine, do:
105
106           $ical_string = $ical->ical( localtime => 1 );
107
108       To get output relative to an arbitrary offset, do:
109
110           $ical_string = $ical->ical( offset => '+0545' );
111
112   epoch
113           $epoch_time = $ical->epoch;
114
115           $ical->epoch( 98687431 );
116
117       Sets, or retrieves, the epoch time represented by the object, if it is
118       representable as such. (Dates before 1971 or after 2038 will not have
119       an epoch representation.)
120
121       Internals note: The ICal representation of the date is considered the
122       only authoritative one. This means that we may need to reconstruct the
123       epoch time from the ICal representation if we are not sure that they
124       are in synch. We'll need to do clever things to keep track of when the
125       two may not be in synch.  And, of course, the same will go for any
126       subclasses of this class.
127
128   offset_to_seconds
129           $seconds_plus_or_minus = offset_to_seconds($offset);
130
131       Changes -0600 to -21600. Not object method, no side-effects.
132
133   offset_from_seconds
134           $seconds_plus_or_minus = offset_from_seconds($offset_in_seconds);
135
136       Changes -18000 (seconds) to -0600 (hours, minutes).  Not object method,
137       no side-effects.
138
139   offset
140           $offset = $ical->offset;
141
142           # We need tests for these.
143           $ical->offset( '+1100' ); # a number of hours and minutes: UTC+11
144           $ical->offset( 0 );       # reset to UTC
145
146       Sets or retrieves the offset from UTC for this time. This allows
147       timezone support, assuming you know what your local (or non-local) UTC
148       offset is. Defaults to 0.
149
150       Internals note: all times are internally stored in UTC, even though
151       they may have some offset information. Offsets are internally stored in
152       signed integer seconds.
153
154       BE CAREFUL about using this function on objects that were initialized
155       with an offset. If you started an object with:
156
157           my $d = new(ical=>'19700101120000', offset=>'+0100');
158
159       and you then call:
160
161           $d->offset('+0200');
162
163       you'll be saying "Yeah, I know I *said* it was in +0100, but really I
164       want it to be in +0200 now and forever." Which may be your intention,
165       if you're trying to transpose a whole set of dates to another
166       timezone--- but you can also do that at the presentation level, with
167       the ical() method. Either way will work.
168
169   add
170           $self->add( year => 3, month => 2, week => 1, day => 12,
171                       hour => 1, minute => 34, sec => 59 );
172           $date->add( duration => 'P1WT1H1M1S' ); # add 1 wk, 1 hr, 1 min, and 1 sec
173
174       Adds a duration to a Date::ICal object.
175
176       Supported paraters are: duration, eom_mode, year, month, week, day,
177       hour, min, sec or seconds.
178
179       'duration' is a ICalendar duration string (see duration_value).
180
181       If a value is undefined or omitted, 1 is assumed:
182
183           $ical->add( 'minute' ); # add a minute
184
185       The result will be normalized. That is, the output time will have
186       meaningful values, rather than being 48:73 pm on the 34th of
187       hexadecember.
188
189       Adding months or years can be done via three different methods,
190       specified by the eom_mode parameter, which then applies to all
191       additions (or subtractions) of months or years following it in the
192       parameter list.
193
194       The default, eom_mode => 'wrap', means adding months or years that
195       result in days beyond the end of the new month will roll over into the
196       following month.  For instance, adding one year to Feb 29 will result
197       in Mar 1.
198
199       If you specify eom_mode => 'limit', the end of the month is never
200       crossed.  Thus, adding one year to Feb 29, 2000 will result in Feb 28,
201       2001.  However, adding three more years will result in Feb 28, 2004,
202       not Feb 29.
203
204       If you specify eom_mode => 'preserve', the same calculation is done as
205       for 'limit' except that if the original date is at the end of the month
206       the new date will also be.  For instance, adding one month to Feb 29,
207       2000 will result in Mar 31, 2000.
208
209       All additions are performed in the order specified.  For instance, with
210       the default setting of eom_mode => 'wrap', adding one day and one month
211       to Feb 29 will result in Apr 1, while adding one month and one day will
212       result in Mar 30.
213
214   add_overload
215           $date = $date1 + $duration;
216
217       Where $duration is either a duration string, or a Date::ICal::Duration
218       object.
219
220           $date += 'P2DT4H7M';
221
222       Adds a duration to a date object. Returns a new object, or, in the case
223       of +=, modifies the existing object.
224
225   duration_value
226       Given a duration string, this function returns the number of days,
227       seconds, and months represented by that duration. In that order. Seems
228       odd to me. This should be considered an internal function, and you
229       should expect the API to change in the very near future.
230
231   subtract
232         $duration = $date1 - $date2;
233
234       Subtract one Date::ICal object from another to give a duration - the
235       length of the interval between the two dates. The return value is a
236       Date::ICal::Duration object (qv) and allows you to get at each of the
237       individual components, or the entire duration string:
238
239           $d = $date1 - $X;
240
241       Note that $X can be any of the following:
242
243       If $X is another Date::ICal object (or subclass thereof) then $d will
244       be a Date::ICal::Duration object.
245
246           $week = $d->weeks; # how many weeks apart?
247           $days = $d->as_days; # How many days apart?
248
249       If $X is a duration string, or a Date::ICal::Diration object, then $d
250       will be an object in the same class as $date1;
251
252           $newdate = $date - $duration;
253
254   clone
255           $copy = $date->clone;
256
257       Returns a replica of the date object, including all attributes.
258
259   compare
260           $cmp = $date1->compare($date2);
261
262           @dates = sort {$a->compare($b)} @dates;
263
264       Compare two Date::ICal objects. Semantics are compatible with sort;
265       returns -1 if $a < $b, 0 if $a == $b, 1 if $a > $b.
266
267   day
268           my $day = $date->day;
269
270       Returns the day of the month.
271
272       Day is in the range 1..31
273
274   month
275           my $month = $date->month;
276
277       Returns the month of the year.
278
279       Month is returned as a number in the range 1..12
280
281   year
282           my $year = $date->year;
283
284       Returns the year.
285
286   jd2greg
287           ($year, $month, $day) = jd2greg( $jd );
288
289           Convert number of days on or after Jan 1, 1 CE (Gregorian) to
290           gregorian year,month,day.
291
292   greg2jd
293           $jd = greg2jd( $year, $month, $day );
294
295           Convert gregorian year,month,day to days on or after Jan 1, 1 CE
296           (Gregorian).  Normalization is performed (e.g. month of 28 means
297           April two years after given year) for month < 1 or > 12 or day < 1
298           or > last day of month.
299
300   days_this_year
301         $yday = Date::ICal::days_this_year($day, $month, $year);
302
303       Returns the number of days so far this year. Analogous to the yday
304       attribute of gmtime (or localtime) except that it works outside of the
305       epoch.
306
307   day_of_week
308           my $day_of_week = $date->day_of_week
309
310       Returns the day of week as 0..6 (0 is Sunday, 6 is Saturday).
311
312   hour
313           my $hour = $date->hour
314
315       Returns the hour of the day.
316
317       Hour is in the range 0..23
318
319   min
320           my $min = $date->min;
321
322       Returns the minute.
323
324       Minute is in the range 0..59
325
326   sec
327           my $sec = $date->sec;
328
329       Returns the second.
330
331       Second is in the range 0..60. The value of 60 is (maybe) needed for
332       leap seconds. But I'm not sure if we're going to go there.
333
334   julian
335         my $jd = $date->jd;
336
337       Returns a listref, containing two elements. The date as a julian day,
338       and the time as the number of seconds since midnight. This should not
339       be thought of as a real julian day, because it's not. The module is
340       internally consistent, and that's enough.
341
342       This method really only is here for compatibility with previous
343       versions, as the jd method is now thrown over for plain hash
344       references.
345
346       See the file INTERNALS for more information about this internal format.
347

TODO

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

INTERNALS

353       Please see the file INTERNALS for discussion on the internals.
354

AUTHOR

356       Rich Bowen (DrBacchus) rbowen@rcbowen.com
357
358       And the rest of the Reefknot team. See the source for a full list of
359       patch contributors and version-by-version notes.
360