1Duration(3) User Contributed Perl Documentation Duration(3)
2
6 Time::Duration - rounded or exact English expression of durations
7
9 Example use in a program that ends by noting its runtime:
10 my $start_time = time();
12 use Time::Duration;
13 # then things that take all that time, and then ends:
15 print "Runtime ", duration(time() - $start_time), ".\n";
16 Example use in a program that reports age of a file:
18 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
25 This module provides functions for expressing durations in rounded or
26 exact terms.
27 In the first example in the Synopsis, using
29 duration($interval_seconds):
30 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 In the second example in the Synopsis, using ago($interval_seconds):
40 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
54 This module provides all the following functions, which are all
55 exported by default when you call "use Time::Duration;".
56 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 For example, duration(120) or duration(-120) is "2 minutes". And
64 duration(0) is "0 seconds".
65 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 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 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 ago_exact($seconds)
95 Same as ago($seconds), except that the returned value is an exact
96 (unrounded) expression of $seconds.
97 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 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 later_exact($seconds)
115 Same as later($seconds), except that the returned value is an exact
116 (unrounded) expression of $seconds.
117 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 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
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
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 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 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
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
156 Date::Interval, which is similarly named, but does something rather
157 different.
158 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 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
174 Current maintainer Avi Finkel, "avi@finkel.org"; Original author Sean
175 M. Burke, "sburke@cpan.org"
176perl v5.12.0 2007-08-19 Duration(3)