1Interval(3) User Contributed Perl Documentation Interval(3)
2
6 Time::Interval - Converts time intervals of days, hours, minutes, and
7 seconds
8 This is a rather simple perl module for dealing with time intervals.
10 Among other things, this module can tell you the number of hours,
11 minutes, and seconds elapsed between two dates.
12 NOTE: this module does not handle resolutions < 1 second. Please see
14 the Time::HiRes module for high resolution time operations. This module
15 will round fractional second values to the nearest whole number.
16
18 use Time::Interval;
19 $data = getInterval(
21 "1/25/03 12:34:32 EDT 2003",
22 "4/25/03 11:24:00 EDT 2003"
23 );
24 $string = getInterval(
26 "1/25/03 12:34:32 EDT 2003",
27 "4/25/03 11:24:00 EDT 2003",
28 "string"
29 );
30 $number_of_minutes = convertInterval(
32 days => 5,
33 hours => 23,
34 minutes => 10,
35 ConvertTo => "minutes"
36 );
37 $data = parseInterval(seconds => 14295872);
39 $string = parseInterval(
41 seconds => 14295872,
42 String => 1
43 );
44 $string = parseInterval(
46 seconds => 14295872,
47 Small => 1
48 );
49 $min_intervals = coalesce([
51 [ '1/25/03 12:34:32 EDT 2003', '1/25/03 15:34:32 EDT 2003' ],
52 [ '1/25/03 14:34:32 EDT 2003', '1/25/03 16:34:32 EDT 2003' ],
53 [ '1/25/03 09:10:18 EDT 2003', '1/25/03 12:32:15 EDT 2003' ]
54 ]);
55
57 this will take two date strings in any of the formats recognized by
58 Date::Parse, and return the number of days, hours, minutes, and seconds
59 elapsed between the two times.
60 Returned Data format
62 getInterval returns a hash reference in the same format as
63 parseInterval.
64 Catching exceptions
66 upon failure this routine will return the undef value, and an error
67 string will be warn'd to stdout.
68 Arguments
70 argument 1 (required)
71 this should be a date string in any of the formats available to
72 Date::Parse.
73 argument 2 (required)
75 this should be a date string in any of the formats available to
76 Date::Parse.
77 argument 3 (optional)
79 this argument controls how the interval will be returned. If not
80 defined, the inerval will be returned as a hash reference
81 containing the number of days, hourse, minutes and seconds between
82 the two dates. If the following values are specified the interval
83 will be returned as a string:
84 'small'
86 if this value is specified, a string containing abbreviated
87 values will be returned (dhms format) for instance 1d 2h 3m 0s
88 (one day, two hours, three minutes and 0 seconds)
89 'string'
91 if this value (or any value other than 'short') is specified a
92 string containing the interval will be returned for instance:
93 '1 day, 2 hours, 3 minutes, 0 seconds'
94
96 this will convert a given number of days, hours, minutes, or seconds,
97 or any combination thereof to the format specified by the ConverrtTo
98 option.
99 Returned data
101 is a number, of time units that you specify on the ConvertTo option
102 Options
104 ConvertTo 'days'|'hours'|'minutes'|'seconds'
105 convert the given time interval to this unit of time measurement,
106 if not specified, the default value is 'seconds'
107 days
109 specify number of days
110 hours
112 specify number of hours
113 minutes
115 specify number of minutes
116 seconds
118 specify number of seconds
119
121 this will convert the given time interval to the number of days, hours,
122 minutes and seconds.
123 Returned Data Format
125 unless the 'String' option is specified, this routine returns a has
126 reference containing the following data:
127 \%data = ( 'days' => $number_of_days,
129 'hours' => $number_of_hours, 'minutes' =>
130 $number_of_minutes, 'seconds' => $number_of_seconds );
131 Options
133 days
134 specify number of days
135 hours
137 specify number of hours
138 minutes
140 specify number of minutes
141 seconds
143 specify number of seconds
144 String
146 if this option is specified as a non-zero value a string containing
147 the number of days, hours, minutes, and seconds is returned, for
148 example:
149 "70 days, 16 hours, 56 minutes, 18 seconds"
151 Small
153 if this option is specified as a non-zero value a string containing
154 the number of days, hours, minutes, and seconds is returned in
155 abbreviated form (dhms format), for example:
156 "70d 16h 56m 18s"
158
160 given a set of time intervals (start and end time pairs), this method
161 will return the minimum set based on overlapping time spans. That is,
162 this method will return a list of unique contiguous time intervals from
163 the given list. As with the other methods in this package, time strings
164 may be submitted in any of the formats supported by Date::Parse. Data
165 is returned as it was passed in, as a reference to an array of array
166 references (see below).
167 Arguments
169 coalesce takes only one argument, an array reference. The reference
170 should be to an array of array references, each of which contains a
171 start and an end time. For a quick example, take a look at the SYNOPSIS
172 section.
173
175 Andrew N. Hicox <ahicox@hicox.com>
176 http://www.hicox.com
177perl v5.36.0 2023-01-20 Interval(3)