1Interval(3)           User Contributed Perl Documentation          Interval(3)
2
3
4

NAME

6       Time::Interval - Converts time intervals of days, hours, minutes, and
7       seconds
8
9       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
13       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

SYNOPSIS

18               use Time::Interval;
19
20               $data = getInterval(
21                       "1/25/03 12:34:32 EDT 2003",
22                       "4/25/03 11:24:00 EDT 2003"
23               );
24
25               $string = getInterval(
26                       "1/25/03 12:34:32 EDT 2003",
27                       "4/25/03 11:24:00 EDT 2003",
28                       "string"
29               );
30
31               $number_of_minutes = convertInterval(
32                       days            => 5,
33                       hours           => 23,
34                       minutes         => 10,
35                       ConvertTo       => "minutes"
36               );
37
38               $data = parseInterval(seconds => 14295872);
39
40               $string = parseInterval(
41                       seconds => 14295872,
42                       String  => 1
43               );
44
45               $string = parseInterval(
46                       seconds => 14295872,
47                       Small   => 1
48               );
49
50               $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

getInterval

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
61   Returned Data format
62       getInterval returns a hash reference in the same format as
63       parseInterval.
64
65   Catching exceptions
66       upon failure this routine will return the undef value, and an error
67       string will be warn'd to stdout.
68
69   Arguments
70       argument 1 (required)
71           this should be a date string in any of the formats available to
72           Date::Parse.
73
74       argument 2 (required)
75           this should be a date string in any of the formats available to
76           Date::Parse.
77
78       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
85           '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
90           '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

convertInterval

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
100   Returned data
101       is a number, of time units that you specify on the ConvertTo option
102
103   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
108       days
109           specify number of days
110
111       hours
112           specify number of hours
113
114       minutes
115           specify number of minutes
116
117       seconds
118           specify number of seconds
119

parseInterval

121       this will convert the given time interval to the number of days, hours,
122       minutes and seconds.
123
124   Returned Data Format
125       unless the 'String' option is specified, this routine returns a has
126       reference containing the following data:
127
128       \%data    = (      'days'         => $number_of_days,
129            'hours'        => $number_of_hours,      'minutes' =>
130       $number_of_minutes,      'seconds' => $number_of_seconds );
131
132   Options
133       days
134           specify number of days
135
136       hours
137           specify number of hours
138
139       minutes
140           specify number of minutes
141
142       seconds
143           specify number of seconds
144
145       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
150           "70 days, 16 hours, 56 minutes, 18 seconds"
151
152       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
157           "70d 16h 56m 18s"
158

coalesce

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
168   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

Author:

175           Andrew N. Hicox     <ahicox@hicox.com>
176           http://www.hicox.com
177
178
179
180perl v5.36.0                      2023-01-20                       Interval(3)
Impressum