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: 682 $
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       <https://github.com/houseabsolute/DateTime.pm/wiki> or
47       <https://metacpan.org/> for more modern modules.
48
49       Last touched by $Author: rbowen $
50

METHODS

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

INTERNALS

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

153       © 2001-2022 Rich Bowen
154
155       © 2022-2023 Michal Josef Špaček
156
157       This library is free software; you can redistribute it and/or modify it
158       under the same terms as Perl itself.
159
160
161
162perl v5.38.0                      2023-07-20           Date::ICal::Duration(3)
Impressum