1Time::Duration(3) User Contributed Perl Documentation Time::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 By default, this module assumes input is an integer representing number
55 of seconds and only emits results based on the integer part of any
56 floating-point values passed to it. However, if you set the variable
57 $Time::Duration::MILLISECOND to any true value, then the methods will
58 interpret inputs as floating-point numbers and will emit results
59 containing information about the number of milliseconds in the value.
60 For example, duration(1.021) will return 1 second and 21 milliseconds
62 in this mode.
63 Millisecond mode is not enabled by default because this module sees
65 heavy use and existing users of it may be relying on its implicit
66 truncation of non-integer arguments.
67
69 This module provides all the following functions, which are all
70 exported by default when you call "use Time::Duration;".
71 duration($seconds)
73 duration($seconds, $precision)
74 Returns English text expressing the approximate time duration of
75 abs($seconds), with at most "$precision || 2" expressed units.
76 (That is, duration($seconds) is the same as duration($seconds,2).)
77 For example, duration(120) or duration(-120) is "2 minutes". And
79 duration(0) is "0 seconds".
80 The precision figure means that no more than that many units will
82 be used in expressing the time duration. For example, 31,629,659
83 seconds is a duration of exactly 1 year, 1 day, 2 hours, and 59
84 seconds (assuming 1 year = exactly 365 days, as we do assume in
85 this module). However, if you wanted an approximation of this to
86 at most two expressed (i.e., nonzero) units, it would round it and
87 truncate it to "1 year and 1 day". Max of 3 expressed units would
88 get you "1 year, 1 day, and 2 hours". Max of 4 expressed units
89 would get you "1 year, 1 day, 2 hours, and 59 seconds", which
90 happens to be exactly true. Max of 5 (or more) expressed units
91 would get you the same, since there are only four nonzero units
92 possible in for that duration.
93 duration_exact($seconds)
95 Same as duration($seconds), except that the returned value is an
96 exact (unrounded) expression of $seconds. For example,
97 duration_exact(31629659) returns "1 year, 1 day, 2 hours, and 59
98 seconds later", which is exactly true.
99 ago($seconds)
101 ago($seconds, $precision)
102 For a positive value of seconds, this prints the same as
103 "duration($seconds, [$precision]) . ' ago'". For example, ago(120)
104 is "2 minutes ago". For a negative value of seconds, this prints
105 the same as "duration($seconds, [$precision]) . ' from now'". For
106 example, ago(-120) is "2 minutes from now". As a special case,
107 ago(0) returns "right now".
108 ago_exact($seconds)
110 Same as ago($seconds), except that the returned value is an exact
111 (unrounded) expression of $seconds.
112 from_now($seconds)
114 from_now($seconds, $precision)
115 from_now_exact($seconds)
116 The same as ago(-$seconds), ago(-$seconds, $precision),
117 ago_exact(-$seconds). For example, from_now(120) is "2 minutes
118 from now".
119 later($seconds)
121 later($seconds, $precision)
122 For a positive value of seconds, this prints the same as
123 "duration($seconds, [$precision]) . ' later'". For example,
124 ago(120) is "2 minutes later". For a negative value of seconds,
125 this prints the same as "duration($seconds, [$precision]) .
126 ' earlier'". For example, later(-120) is "2 minutes earlier". As
127 a special case, later(0) returns "right then".
128 later_exact($seconds)
130 Same as later($seconds), except that the returned value is an exact
131 (unrounded) expression of $seconds.
132 earlier($seconds)
134 earlier($seconds, $precision)
135 earlier_exact($seconds)
136 The same as later(-$seconds), later(-$seconds, $precision),
137 later_exact(-$seconds). For example, earlier(120) is "2 minutes
138 earlier".
139 concise( function( ... ) )
141 Concise takes the string output of one of the above functions and
142 makes it more concise. For example, ago(4567) returns "1 hour and
143 16 minutes ago", but "concise(ago(4567))" returns "1h16m ago".
144
146 Little of the internals of this module are English-specific. See
147 source and/or contact me if you're interested in making a localized
148 version for some other language than English.
149
151 I wrote the basic ago() function for use in Infobot
152 ("http://www.infobot.org"), because I was tired of this sort of
153 response from the Purl Infobot:
154 me> Purl, seen Woozle?
156 <Purl> Woozle was last seen on #perl 20 days, 7 hours, 32 minutes
157 and 40 seconds ago, saying: Wuzzle!
158 I figured if it was 20 days ago, I don't care about the seconds. So
160 once I had written ago(), I abstracted the code a bit and got all the
161 other functions.
162
164 This module calls a durational "year" an interval of exactly 365 days
165 of exactly 24 hours each, with no provision for leap years or monkey
166 business with 23/25 hour days (much less leap seconds!). But since the
167 main work of this module is approximation, that shouldn't be a great
168 problem for most purposes.
169
171 Time::Elapsed - similarly converts durations to natural language, but
172 in addition to English also supports Danish, German, French, and
173 Turkish.
174 Date::Interval, which is similarly named, but does something rather
176 different.
177 Star Trek: The Next Generation (1987-1994), where the character Data
179 would express time durations like "1 year, 20 days, 22 hours, 59
180 minutes, and 35 seconds" instead of rounding to "1 year and 21 days".
181 This is because no-one ever told him to use Time::Duration.
182
184 Copyright 2013, Sean M. Burke "sburke@cpan.org"; Avi Finkel,
185 "avi@finkel.org", all rights reserved. This program is free software;
186 you can redistribute it and/or modify it under the same terms as Perl
187 itself.
188 This program is distributed in the hope that it will be useful, but
190 without any warranty; without even the implied warranty of
191 merchantability or fitness for a particular purpose.
192
194 Original author Sean M. Burke, "sburke@cpan.org".
195 Then maintained by Avi Finkel, "avi@finkel.org".
197 Currently maintained by Neil Bowers, "neilb@cpan.org".
199perl v5.36.0 2023-01-20 Time::Duration(3)