3 =head1 NAME $RCSfile: TimeUtils.pm,v $
13 Andrew DeFaria <Andrew@ClearSCM.com>
21 Fri Mar 12 10:17:44 PST 2004
25 $Date: 2012/11/13 23:34:13 $
31 This module seeks to handle time and duration entities in a simple
32 manner. Given a time(3) structure we have routines to format out, in a
33 human readable form, a duration.
37 # Do something that takes time...
39 # Display how long that took
40 display_duration $startTime;
42 # Displays how long that took into $log (See Logger.pm)
43 display_duration $startTime, $log;
45 # Get a date timestamp for today
46 my $yyyymmdd = format_yyyymmdd;
48 # Get a human readable duration between $startTime
49 # and the current time
50 my $duration = howlong $startTime, time;
54 This module exports a few time/duration related routines
58 The following routines are exported:
80 my ($start_time, $end_time) = @_;
84 =head2 howlong ($start_time, $end_time)
86 Returns a string that represents a human readable version of the
87 duration of time between $start_time and $end_time. For example, "1
88 hour, 10 minues and 5 seconds".
92 =for html <blockquote>
98 Time that represents the start time of the time period.
102 Time that represents the end time of the time period. (Default;
107 =for html </blockquote>
111 =for html <blockquote>
115 =item $duration string
119 =for html </blockquote>
125 return if $start_time > $end_time;
127 my $difference = $end_time - $start_time;
129 my $seconds_per_min = 60;
130 my $seconds_per_hour = 60 * $seconds_per_min;
131 my $seconds_per_day = $seconds_per_hour * 24;
138 if ($difference > $seconds_per_day) {
139 $days = int ($difference / $seconds_per_day);
140 $difference = $difference % $seconds_per_day;
143 if ($difference > $seconds_per_hour) {
144 $hours = int ($difference / $seconds_per_hour);
145 $difference = $difference % $seconds_per_hour;
148 if ($difference > $seconds_per_min) {
149 $minutes = int ($difference / $seconds_per_min);
150 $difference = $difference % $seconds_per_min;
153 $seconds = $difference;
162 $day_str = $days == 1 ? '1 day' : "$days days";
163 $duration = $day_str;
167 $hour_str = $hours == 1 ? '1 hour' : "$hours hours";
169 if ($duration ne '') {
170 $duration .= ' ' . $hour_str;
172 $duration = $hour_str;
177 $min_str = $minutes == 1 ? '1 minute' : "$minutes minutes";
179 if ($duration ne '') {
180 $duration .= ' ' . $min_str;
182 $duration = $min_str;
187 $sec_str = $seconds == 1 ? '1 second' : "$seconds seconds";
189 if ($duration ne '') {
190 $duration .= ' ' . $sec_str;
192 $duration = $sec_str;
196 if ($duration eq '' and $seconds == 0) {
197 $duration = 'under 1 second';
203 sub display_duration ($;$) {
204 my ($start_time, $log) = @_;
208 =head2 display_duration ($start_time, $log)
210 Displays the duration between $start_time and now to STDOUT (or
211 optionally to log it to $log - See Logger)
215 =for html <blockquote>
221 Time that represents the start time of the time period.
225 Log object to long durtion to.
229 =for html </blockquote>
233 =for html <blockquote>
241 =for html </blockquote>
245 unless ($start_time) {
247 $log->msg ('Finished in 0 seconds');
249 display 'Finished in 0 seconds';
254 my $duration = howlong $start_time, $end_time;
257 $log->msg ("Finished in $duration");
259 display "Finished in $duration";
265 sub format_yyyymmdd ($) {
270 =head2 format_yyyymmdd ($time)
272 Quickly returns a YYYYMMDD format date for $time. If $time is not
273 specified then it returns today.
277 =for html <blockquote>
283 The $time to get the date from
287 =for html </blockquote>
291 =for html <blockquote>
295 =item Date string in YYYYMMDD format for $time
299 =for html </blockquote>
305 my ($sec, $min, $hour, $mday, $mon, $year) = localtime ($time);
309 $mon = $mon < 10 ? "0$mon" : $mon;
310 $mday = $mday < 10 ? "0$mday" : $mday;
312 return '$year$mon$mday';
317 =head1 CONFIGURATION AND ENVIRONMENT
319 DEBUG: If set then $debug is set to this level.
321 VERBOSE: If set then $verbose is set to this level.
323 TRACE: If set then $trace is set to this level.
329 L<File::Spec|File::Spec>
331 =head2 ClearSCM Perl Modules
333 =for html <p><a href='/php/scm_man.php?file=lib/Display.pm'>Display</a></p>
335 =for html <p><a href='/php/scm_man.php?file=lib/Logger.pm'>Logger</a></p>
337 =head1 INCOMPATABILITIES
341 =head1 BUGS AND LIMITATIONS
343 There are no known bugs in this module.
345 Please report problems to Andrew DeFaria <Andrew@ClearSCM.com>.
347 =head1 LICENSE AND COPYRIGHT
349 This Perl Module is freely available; you can redistribute it and/or
350 modify it under the terms of the GNU General Public License as
351 published by the Free Software Foundation; either version 2 of the
352 License, or (at your option) any later version.
354 This Perl Module is distributed in the hope that it will be useful,
355 but WITHOUT ANY WARRANTY; without even the implied warranty of
356 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
357 General Public License (L<http://www.gnu.org/copyleft/gpl.html>) for more
360 You should have received a copy of the GNU General Public License
361 along with this Perl Module; if not, write to the Free Software Foundation,
362 Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.