1NAME
2 Date::ICal - Perl extension for ICalendar date objects.
3
4VERSION
5 $Rev: 368 $
6
7SYNOPSIS
8 use Date::ICal;
9
10 $ical = Date::ICal->new( ical => '19971024T120000' );
11 $ical = Date::ICal->new( epoch => time );
12 $ical = Date::ICal->new( year => 1964,
13 month => 10, day => 16, hour => 16,
14 min => 12, sec => 47, tz => '0530' );
15
16 $hour = $ical->hour;
17 $year = $ical->year;
18
19 $ical_string = $ical->ical;
20 $epoch_time = $ical->epoch;
21
22 $ical2 = $ical + $duration;
23
24 (Where $duration is either a duration string, like 'P2W3DT7H9M', or a
25 Date::ICal::Duration (qv) object.
26
27 $ical += 'P6DT12H';
28
29 $duration = $ical1 - $ical2;
30 $ical3 = $ical1 - $duration;
31
32DESCRIPTION
33 Date::ICal talks the ICal date format, and is intended to be a base
34 class for other date/calendar modules that know about ICal time format
35 also.
36
37AUTHOR
38 Rich Bowen
39
40 Last touched by $Author: rbowen $
41
42METHODS
43 Date::ICal has the following methods available:
44
45 new
46
47 A new Date::ICal object can be created with any valid ICal string:
48
49 my $ical = Date::ICal->new( ical => '19971024T120000' );
50 # will default to the timezone specified in $TZ, see below
51
52 Or with any epoch time:
53
54 my $ical = Date::ICal->new( epoch => time );
55
56 Or, better still, create it with components
57
58 my $date = Date::ICal->new(
59 day => 25,
60 month => 10,
61 year => 1066,
62 hour => 7,
63 min => 15,
64 sec => 47
65 );
66
67 If you call new without any arguments, you'll get a Date::ICal object
68 that is set to the time right now.
69
70 my $ical = Date::ICal->new();
71
72 If you already have an object in Date::ICal, or some other subclass
73 thereof, you can create a new Date::ICal (or subclass) object using that
74 object to start with. This is particularly useful for converting from
75 one calendar to another:
76
77 # Direct conversion from Discordian to ISO dates
78 my $disco = Date::Discordian->new( disco => '12 Chaos, YOLD 3177' );
79 my $iso = Date::ISO->new( $disco );
80 print $iso->iso;
81
82 new() handles timezones. It defaults times to UTC (Greenwich Mean Time,
83 also called Zulu). If you want to set up a time that's in the US
84 "Pacific" timezone, which is GMT-8, use something like:
85
86 my $ical = Date::ICal->new( ical => '19971024T120000',
87 offset => "-0800");
88
89 Note that as of version 1.44, new() tries to be intelligent about
90 figuring out your local time zone. If you enter a time that's not
91 *explicitly* in UTC, it looks at the environment variable $TZ, if it
92 exists, to determine your local offset. If $TZ isn't set, new() will
93 complain.
94
95 ical
96
97 $ical_string = $ical->ical;
98
99 Retrieves, or sets, the date on the object, using any valid ICal
100 date/time string. Output is in UTC (ends with a "Z") by default. To get
101 output in localtime relative to the current machine, do:
102
103 $ical_string = $ical->ical( localtime => 1 );
104
105 To get output relative to an arbitrary offset, do:
106
107 $ical_string = $ical->ical( offset => '+0545' );
108
109 epoch
110
111 $epoch_time = $ical->epoch;
112
113 $ical->epoch( 98687431 );
114
115 Sets, or retrieves, the epoch time represented by the object, if it is
116 representable as such. (Dates before 1971 or after 2038 will not have an
117 epoch representation.)
118
119 Internals note: The ICal representation of the date is considered the
120 only authoritative one. This means that we may need to reconstruct the
121 epoch time from the ICal representation if we are not sure that they are
122 in synch. We'll need to do clever things to keep track of when the two
123 may not be in synch. And, of course, the same will go for any subclasses
124 of this class.
125
126 _offset_to_seconds
127
128 $seconds_plus_or_minus = offset_to_seconds($offset);
129
130 Changes -0600 to -21600. Not object method, no side-effects.
131
132 _offset_from_seconds
133
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
141 $offset = $ical->offset;
142
143 # We need tests for these.
144 $ical->offset( '+1100' ); # a number of hours and minutes: UTC+11
145 $ical->offset( 0 ); # reset to UTC
146
147 Sets or retrieves the offset from UTC for this time. This allows
148 timezone support, assuming you know what your local (or non-local) UTC
149 offset is. Defaults to 0.
150
151 Internals note: all times are internally stored in UTC, even though they
152 may have some offset information. Offsets are internally stored in
153 signed integer seconds.
154
155 BE CAREFUL about using this function on objects that were initialized
156 with an offset. If you started an object with:
157
158 my $d = new(ical=>'19700101120000', offset=>'+0100');
159
160 and you then call:
161
162 $d->offset('+0200');
163
164 you'll be saying "Yeah, I know I *said* it was in +0100, but really I
165 want it to be in +0200 now and forever." Which may be your intention, if
166 you're trying to transpose a whole set of dates to another timezone---
167 but you can also do that at the presentation level, with the ical()
168 method. Either way will work.
169
170 add
171
172 $self->add( year => 3, month => 2, week => 1, day => 12,
173 hour => 1, minute => 34, sec => 59 );
174 $date->add( duration => 'P1WT1H1M1S' ); # add 1 wk, 1 hr, 1 min, and 1 sec
175
176 Adds a duration to a Date::ICal object.
177
178 Supported paraters are: duration, eom_mode, year, month, week, day,
179 hour, min, sec or seconds.
180
181 'duration' is a ICalendar duration string (see duration_value).
182
183 If a value is undefined or omitted, 1 is assumed:
184
185 $ical->add( 'minute' ); # add a minute
186
187 The result will be normalized. That is, the output time will have
188 meaningful values, rather than being 48:73 pm on the 34th of
189 hexadecember.
190
191 Adding months or years can be done via three different methods,
192 specified by the eom_mode parameter, which then applies to all additions
193 (or subtractions) of months or years following it in the parameter list.
194
195 The default, eom_mode => 'wrap', means adding months or years that
196 result in days beyond the end of the new month will roll over into the
197 following month. For instance, adding one year to Feb 29 will result in
198 Mar 1.
199
200 If you specify eom_mode => 'limit', the end of the month is never
201 crossed. Thus, adding one year to Feb 29, 2000 will result in Feb 28,
202 2001. However, adding three more years will result in Feb 28, 2004, not
203 Feb 29.
204
205 If you specify eom_mode => 'preserve', the same calculation is done as
206 for 'limit' except that if the original date is at the end of the month
207 the new date will also be. For instance, adding one month to Feb 29,
208 2000 will result in Mar 31, 2000.
209
210 All additions are performed in the order specified. For instance, with
211 the default setting of eom_mode => 'wrap', adding one day and one month
212 to Feb 29 will result in Apr 1, while adding one month and one day will
213 result in Mar 30.
214
215 add_overload
216
217 $date = $date1 + $duration;
218
219 Where $duration is either a duration string, or a Date::ICal::Duration
220 object.
221
222 $date += 'P2DT4H7M';
223
224 Adds a duration to a date object. Returns a new object, or, in the case
225 of +=, modifies the existing object.
226
227 duration_value
228
229 Given a duration string, this function returns the number of days,
230 seconds, and months represented by that duration. In that order. Seems
231 odd to me. This should be considered an internal function, and you
232 should expect the API to change in the very near future.
233
234 subtract
235
236 $duration = $date1 - $date2;
237
238 Subtract one Date::ICal object from another to give a duration - the
239 length of the interval between the two dates. The return value is a
240 Date::ICal::Duration object (qv) and allows you to get at each of the
241 individual components, or the entire duration string:
242
243 $d = $date1 - $X;
244
245 Note that $X can be any of the following:
246
247 If $X is another Date::ICal object (or subclass thereof) then $d will be
248 a Date::ICal::Duration object.
249
250 $week = $d->weeks; # how many weeks apart?
251 $days = $d->as_days; # How many days apart?
252
253 If $X is a duration string, or a Date::ICal::Diration object, then $d
254 will be an object in the same class as $date1;
255
256 $newdate = $date - $duration;
257
258 clone
259
260 $copy = $date->clone;
261
262 Returns a replica of the date object, including all attributes.
263
264 compare
265
266 $cmp = $date1->compare($date2);
267
268 @dates = sort {$a->compare($b)} @dates;
269
270 Compare two Date::ICal objects. Semantics are compatible with sort;
271 returns -1 if $a < $b, 0 if $a == $b, 1 if $a > $b.
272
273 day
274
275 my $day = $date->day;
276
277 Returns the day of the month.
278
279 Day is in the range 1..31
280
281 month
282
283 my $month = $date->month;
284
285 Returns the month of the year.
286
287 Month is returned as a number in the range 1..12
288
289 year
290
291 my $year = $date->year;
292
293 Returns the year.
294
295 jd2greg
296
297 ($year, $month, $day) = jd2greg( $jd );
298
299 Convert number of days on or after Jan 1, 1 CE (Gregorian) to
300 gregorian year,month,day.
301
302 greg2jd
303
304 $jd = greg2jd( $year, $month, $day );
305
306 Convert gregorian year,month,day to days on or after Jan 1, 1 CE
307 (Gregorian). Normalization is performed (e.g. month of 28 means
308 April two years after given year) for month < 1 or > 12 or day < 1
309 or > last day of month.
310
311 days_this_year
312
313 $yday = Date::ICal::days_this_year($day, $month, $year);
314
315 Returns the number of days so far this year. Analogous to the yday
316 attribute of gmtime (or localtime) except that it works outside of the
317 epoch.
318
319 day_of_week
320
321 my $day_of_week = $date->day_of_week
322
323 Returns the day of week as 0..6 (0 is Sunday, 6 is Saturday).
324
325 hour
326
327 my $hour = $date->hour
328
329 Returns the hour of the day.
330
331 Hour is in the range 0..23
332
333 min
334
335 my $min = $date->min;
336
337 Returns the minute.
338
339 Minute is in the range 0..59
340
341 sec
342
343 my $sec = $date->sec;
344
345 Returns the second.
346
347 Second is in the range 0..60. The value of 60 is (maybe) needed for leap
348 seconds. But I'm not sure if we're going to go there.
349
350 julian
351
352 my $jd = $date->jd;
353
354 Returns a listref, containing two elements. The date as a julian day,
355 and the time as the number of seconds since midnight. This should not be
356 thought of as a real julian day, because it's not. The module is
357 internally consistent, and that's enough.
358
359 This method really only is here for compatibility with previous
360 versions, as the jd method is now thrown over for plain hash references.
361
362 See the file INTERNALS for more information about this internal format.
363
364TODO
365 - add gmtime and localtime methods, perhaps?
366 - Fix the INTERNALS file so that it actually reflects reality
367INTERNALS
368 Please see the file INTERNALS for discussion on the internals.
369
370AUTHOR
371 Rich Bowen (DrBacchus) rbowen@rcbowen.com
372
373 And the rest of the Reefknot team. See the source for a full list of
374 patch contributors and version-by-version notes.
375
376SEE ALSO
377 datetime@perl.org mailing list
378
379 http://datetime.perl.org/
380
381 Time::Local
382
383 Net::ICal
384
385------------------------------------------------
386NAME
387 Date::ICal::Duration - durations in iCalendar format, for math purposes.
388
389VERSION
390 $Revision: 368 $
391
392SYNOPSIS
393 use Date::ICal::Duration;
394
395 $d = Date::ICal::Duration->new( ical => '-P1W3DT2H3M45S' );
396
397 $d = Date::ICal::Duration->new( weeks => 1,
398 days => 1,
399 hours => 6,
400 minutes => 15,
401 seconds => 45);
402
403 # a one hour duration, without other components
404 $d = Date::ICal::Duration->new( seconds => "3600");
405
406 # Read-only accessors:
407 $d->weeks;
408 $d->days;
409 $d->hours;
410 $d->minutes;
411 $d->seconds;
412 $d->sign;
413
414 # TODO: Resolve sign() discussion from rk-devel and update synopsis.
415
416 $d->as_seconds (); # returns just seconds
417 $d->as_elements (); # returns a hash of elements, like the accessors above
418 $d->as_ical(); # returns an iCalendar duration string
419
420DESCRIPTION
421 This is a trivial class for representing duration objects, for doing
422 math in Date::ICal
423
424AUTHOR
425 Rich Bowen, and the Reefknot team.
426
427 Last touched by $Author: rbowen $
428
429METHODS
430 Date::ICal::Duration has the following methods available:
431
432 new
433
434 A new Date::ICal::Duration object can be created with an iCalendar
435 string :
436
437 my $ical = Date::ICal::Duration->new ( ical => 'P3W2D' );
438 # 3 weeks, 2 days, positive direction
439 my $ical = Date::ICal::Duration->new ( ical => '-P6H3M30S' );
440 # 6 hours, 3 minutes, 30 seconds, negative direction
441
442 Or with a number of seconds:
443
444 my $ical = Date::ICal::Duration->new ( seconds => "3600" );
445 # one hour positive
446
447 Or, better still, create it with components
448
449 my $date = Date::ICal::Duration->new (
450 weeks => 6,
451 days => 2,
452 hours => 7,
453 minutes => 15,
454 seconds => 47,
455 sign => "+"
456 );
457
458 The sign defaults to "+", but "+" and "-" are legal values.
459
460 sign, weeks, days, hours, minutes, seconds
461
462 Read-only accessors for the elements of the object.
463
464 as_seconds
465
466 Returns the duration in raw seconds.
467
468 WARNING -- this folds in the number of days, assuming that they are
469 always 86400 seconds long (which is not true twice a year in areas that
470 honor daylight savings time). If you're using this for date arithmetic,
471 consider using the *add()* method from a the Date::ICal manpage object,
472 as this will behave better. Otherwise, you might experience some error
473 when working with times that are specified in a time zone that observes
474 daylight savings time.
475
476 as_days
477
478 $days = $duration->as_days;
479
480 Returns the duration as a number of days. Not to be confused with the
481 "days" method, this method returns the total number of days, rather than
482 mod'ing out the complete weeks. Thus, if we have a duration of 33 days,
483 "weeks" will return 4, "days" will return 5, but "as_days" will return
484 33.
485
486 Note that this is a lazy convenience function which is just weeks*7 +
487 days.
488
489 as_ical
490
491 Return the duration in an iCalendar format value string (e.g.,
492 "PT2H0M0S")
493
494 as_elements
495
496 Returns the duration as a hashref of elements.
497
498INTERNALS
499 head2 GENERAL MODEL
500
501 Internally, we store 3 data values: a number of days, a number of
502 seconds (anything shorter than a day), and a sign (1 or -1). We are
503 assuming that a day is 24 hours for purposes of this module; yes, we
504 know that's not completely accurate because of daylight-savings-time
505 switchovers, but it's mostly correct. Suggestions are welcome.
506
507 NOTE: The methods below SHOULD NOT be relied on to stay the same in
508 future versions.
509
510 _set_from_ical ($self, $duration_string)
511
512 Converts a RFC2445 DURATION format string to the internal storage
513 format.
514
515 _parse_ical_string ($string)
516
517 Regular expression for parsing iCalendar into usable values.
518
519 _set_from_components ($self, $hashref)
520
521 Converts from a hashref to the internal storage format. The hashref can
522 contain elements "sign", "weeks", "days", "hours", "minutes", "seconds".
523
524 _set_from_ical ($self, $num_seconds)
525
526 Sets internal data storage properly if we were only given seconds as a
527 parameter.
528
529 $self->_hms();
530
531 Return an arrayref to hours, minutes, and second components, or undef if
532 nsecs is undefined. If given an arrayref, computes the new nsecs value
533 for the duration.
534
535 $self->_wd()
536
537 Return an arrayref to weeks and day components, or undef if ndays is
538 undefined. If Given an arrayref, computs the new ndays value for the
539 duration.
540
541