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

NAME

6       Time::Duration - rounded or exact English expression of durations
7

SYNOPSIS

9       Example use in a program that ends by noting its runtime:
10
11         my $start_time = time();
12         use Time::Duration;
13
14         # then things that take all that time, and then ends:
15         print "Runtime ", duration(time() - $start_time), ".\n";
16
17       Example use in a program that reports age of a file:
18
19         use Time::Duration;
20         my $file = 'that_file';
21         my $age = $^T - (stat($file))[9];  # 9 = modtime
22         print "$file was modified ", ago($age);
23

DESCRIPTION

25       This module provides functions for expressing durations in rounded or
26       exact terms.
27
28       In the first example in the Synopsis, using
29       duration($interval_seconds):
30
31       If the "time() - $start_time" is 3 seconds, this prints "Runtime: 3
32       seconds.".  If it's 0 seconds, it's "Runtime: 0 seconds.".  If it's 1
33       second, it's "Runtime: 1 second.".  If it's 125 seconds, you get
34       "Runtime: 2 minutes and 5 seconds.".  If it's 3820 seconds (which is
35       exactly 1h, 3m, 40s), you get it rounded to fit within two expressed
36       units: "Runtime: 1 hour and 4 minutes.".  Using duration_exact instead
37       would return "Runtime: 1 hour, 3 minutes, and 40 seconds".
38
39       In the second example in the Synopsis, using ago($interval_seconds):
40
41       If the $age is 3 seconds, this prints "file was modified 3 seconds
42       ago".  If it's 0 seconds, it's "file was modified just now", as a
43       special case.  If it's 1 second, it's "from 1 second ago".  If it's 125
44       seconds, you get "file was modified 2 minutes and 5 seconds ago".  If
45       it's 3820 seconds (which is exactly 1h, 3m, 40s), you get it rounded to
46       fit within two expressed units: "file was modified 1 hour and 4 minutes
47       ago".  Using ago_exact instead would return "file was modified 1 hour,
48       3 minutes, and 40 seconds ago".  And if the file's modtime is,
49       surprisingly, three seconds into the future, $age is -3, and you'll get
50       the equally and appropriately surprising "file was modified 3 seconds
51       from now."
52

FUNCTIONS

54       This module provides all the following functions, which are all
55       exported by default when you call "use Time::Duration;".
56
57       duration($seconds)
58       duration($seconds, $precision)
59           Returns English text expressing the approximate time duration of
60           abs($seconds), with at most "$precision || 2" expressed units.
61           (That is, duration($seconds) is the same as duration($seconds,2).)
62
63           For example, duration(120) or duration(-120) is "2 minutes".  And
64           duration(0) is "0 seconds".
65
66           The precision figure means that no more than that many units will
67           be used in expressing the time duration.  For example, 31,629,659
68           seconds is a duration of exactly 1 year, 1 day, 2 hours, and 59
69           seconds (assuming 1 year = exactly 365 days, as we do assume in
70           this module).  However, if you wanted an approximation of this to
71           at most two expressed (i.e., nonzero) units, it would round it and
72           truncate it to "1 year and 1 day".  Max of 3 expressed units would
73           get you "1 year, 1 day, and 2 hours".  Max of 4 expressed units
74           would get you "1 year, 1 day, 2 hours, and 59 seconds", which
75           happens to be exactly true.  Max of 5 (or more) expressed units
76           would get you the same, since there are only four nonzero units
77           possible in for that duration.
78
79       duration_exact($seconds)
80           Same as duration($seconds), except that the returned value is an
81           exact (unrounded) expression of $seconds.  For example,
82           duration_exact(31629659) returns "1 year, 1 day, 2 hours, and 59
83           seconds later", which is exactly true.
84
85       ago($seconds)
86       ago($seconds, $precision)
87           For a positive value of seconds, this prints the same as
88           "duration($seconds, [$precision]) . ' ago'".  For example, ago(120)
89           is "2 minutes ago".  For a negative value of seconds, this prints
90           the same as "duration($seconds, [$precision]) . ' from now'".  For
91           example, ago(-120) is "2 minutes from now".  As a special case,
92           ago(0) returns "right now".
93
94       ago_exact($seconds)
95           Same as ago($seconds), except that the returned value is an exact
96           (unrounded) expression of $seconds.
97
98       from_now($seconds)
99       from_now($seconds, $precision)
100       from_now_exact($seconds)
101           The same as ago(-$seconds), ago(-$seconds, $precision),
102           ago_exact(-$seconds).  For example, from_now(120) is "2 minutes
103           from now".
104
105       later($seconds)
106       later($seconds, $precision)
107           For a positive value of seconds, this prints the same as
108           "duration($seconds, [$precision]) . ' later'".  For example,
109           ago(120) is "2 minutes later".  For a negative value of seconds,
110           this prints the same as "duration($seconds, [$precision]) .
111           ' earlier'".  For example, later(-120) is "2 minutes earlier".  As
112           a special case, later(0) returns "right then".
113
114       later_exact($seconds)
115           Same as later($seconds), except that the returned value is an exact
116           (unrounded) expression of $seconds.
117
118       earlier($seconds)
119       earlier($seconds, $precision)
120       earlier_exact($seconds)
121           The same as later(-$seconds), later(-$seconds, $precision),
122           later_exact(-$seconds).  For example, earlier(120) is "2 minutes
123           earlier".
124
125       concise( function( ... ) )
126           Concise takes the string output of one of the above functions and
127           makes it more concise.  For example, "ago(4567)" returns "1 hour
128           and 16 minutes ago", but "concise(ago(4567))" returns "1h16m ago".
129

I18N/L10N NOTES

131       Little of the internals of this module are English-specific.  See
132       source and/or contact me if you're interested in making a localized
133       version for some other language than English.
134

BACKSTORY

136       I wrote the basic "ago()" function for use in Infobot
137       ("http://www.infobot.org"), because I was tired of this sort of
138       response from the Purl Infobot:
139
140         me> Purl, seen Woozle?
141         <Purl> Woozle was last seen on #perl 20 days, 7 hours, 32 minutes
142         and 40 seconds ago, saying: Wuzzle!
143
144       I figured if it was 20 days ago, I don't care about the seconds.  So
145       once I had written "ago()", I abstracted the code a bit and got all the
146       other functions.
147

CAVEAT

149       This module calls a durational "year" an interval of exactly 365 days
150       of exactly 24 hours each, with no provision for leap years or monkey
151       business with 23/25 hour days (much less leap seconds!).  But since the
152       main work of this module is approximation, that shouldn't be a great
153       problem for most purposes.
154

SEE ALSO

156       Date::Interval, which is similarly named, but does something rather
157       different.
158
159       Star Trek: The Next Generation (1987-1994), where the character Data
160       would express time durations like "1 year, 20 days, 22 hours, 59
161       minutes, and 35 seconds" instead of rounding to "1 year and 21 days".
162       This is because no-one ever told him to use Time::Duration.
163
165       Copyright 2006, Sean M. Burke "sburke@cpan.org", all rights reserved.
166       This program is free software; you can redistribute it and/or modify it
167       under the same terms as Perl itself.
168
169       This program is distributed in the hope that it will be useful, but
170       without any warranty; without even the implied warranty of
171       merchantability or fitness for a particular purpose.
172

AUTHOR

174       Current maintainer Avi Finkel, "avi@finkel.org"; Original author Sean
175       M. Burke, "sburke@cpan.org"
176
177
178
179perl v5.12.0                      2007-08-19                       Duration(3)
Impressum