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. Alas, Reefknot is no more. See
46       http://datetime.perl.org/ for more modern modules.
47
48       Last touched by $Author: rbowen $
49

METHODS

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

INTERNALS

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