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

NAME

6       Date::ICal::Duration - durations in iCalendar format, for math
7       purposes.
8

VERSION

10       $Revision: 1.61 $
11

SYNOPSIS

13           use Date::ICal::Duration;
14
15           $d = Date::ICal::Duration->new( ical => '-P1W3DT2H3M45S' );
16
17           $d = Date::ICal::Duration->new( weeks => 1,
18                                           days => 1,
19                                           hours => 6,
20                                           minutes => 15,
21                                           seconds => 45);
22
23           # a one hour duration, without other components
24           $d = Date::ICal::Duration->new( seconds => "3600");
25
26           # Read-only accessors:
27           $d->weeks;
28           $d->days;
29           $d->hours;
30           $d->minutes;
31           $d->seconds;
32           $d->sign;
33
34           # TODO: Resolve sign() discussion from rk-devel and update synopsis.
35
36           $d->as_seconds ();   # returns just seconds
37           $d->as_elements ();  # returns a hash of elements, like the accessors above
38           $d->as_ical();       # returns an iCalendar duration string
39

DESCRIPTION

41       This is a trivial class for representing duration objects, for doing
42       math in Date::ICal
43

AUTHOR

45       Rich Bowen, and the Reefknot team (www.reefknot.org)
46
47       Last touched by $Author: rbowen $
48

METHODS

50       Date::ICal::Duration has the following methods available:
51
52   new
53       A new Date::ICal::Duration object can be created with an iCalendar
54       string :
55
56           my $ical = Date::ICal::Duration->new ( ical => 'P3W2D' );
57           # 3 weeks, 2 days, positive direction
58           my $ical = Date::ICal::Duration->new ( ical => '-P6H3M30S' );
59           # 6 hours, 3 minutes, 30 seconds, negative direction
60
61       Or with a number of seconds:
62
63           my $ical = Date::ICal::Duration->new ( seconds => "3600" );
64           # one hour positive
65
66       Or, better still, create it with components
67
68           my $date = Date::ICal::Duration->new (
69                                  weeks => 6,
70                                  days => 2,
71                                  hours => 7,
72                                  minutes => 15,
73                                  seconds => 47,
74                                  sign => "+"
75                                  );
76
77       The sign defaults to "+", but "+" and "-" are legal values.
78
79   sign, weeks, days, hours, minutes, seconds
80       Read-only accessors for the elements of the object.
81
82   as_seconds
83       Returns the duration in raw seconds.
84
85       WARNING -- this folds in the number of days, assuming that they are
86       always 86400 seconds long (which is not true twice a year in areas that
87       honor daylight savings time).  If you're using this for date
88       arithmetic, consider using the add() method from a Date::ICal object,
89       as this will behave better.  Otherwise, you might experience some error
90       when working with times that are specified in a time zone that observes
91       daylight savings time.
92
93   as_days
94           $days = $duration->as_days;
95
96       Returns the duration as a number of days. Not to be confused with the
97       "days" method, this method returns the total number of days, rather
98       than mod'ing out the complete weeks. Thus, if we have a duration of 33
99       days, "weeks" will return 4, "days" will return 5, but "as_days" will
100       return 33.
101
102       Note that this is a lazy convenience function which is just weeks*7 +
103       days.
104
105   as_ical
106       Return the duration in an iCalendar format value string (e.g.,
107       "PT2H0M0S")
108
109   as_elements
110       Returns the duration as a hashref of elements.
111

INTERNALS

113       head2 GENERAL MODEL
114
115       Internally, we store 3 data values: a number of days, a number of
116       seconds (anything shorter than a day), and a sign (1 or -1). We are
117       assuming that a day is 24 hours for purposes of this module; yes, we
118       know that's not completely accurate because of daylight-savings-time
119       switchovers, but it's mostly correct. Suggestions are welcome.
120
121       NOTE: The methods below SHOULD NOT be relied on to stay the same in
122       future versions.
123
124   _set_from_ical ($self, $duration_string)
125       Converts a RFC2445 DURATION format string to the internal storage
126       format.
127
128   _parse_ical_string ($string)
129       Regular expression for parsing iCalendar into usable values.
130
131   _set_from_components ($self, $hashref)
132       Converts from a hashref to the internal storage format.  The hashref
133       can contain elements "sign", "weeks", "days", "hours", "minutes",
134       "seconds".
135
136   _set_from_ical ($self, $num_seconds)
137       Sets internal data storage properly if we were only given seconds as a
138       parameter.
139
140   $self->_hms();
141       Return an arrayref to hours, minutes, and second components, or undef
142       if nsecs is undefined.  If given an arrayref, computes the new nsecs
143       value for the duration.
144
145   $self->_wd()
146       Return an arrayref to weeks and day components, or undef if ndays is
147       undefined.  If Given an arrayref, computs the new ndays value for the
148       duration.
149
150
151
152perl v5.12.0                      2002-02-07           Date::ICal::Duration(3)