1Time::Duration(3)     User Contributed Perl Documentation    Time::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

MILLISECOND MODE

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
61       For example, "duration(1.021)" will return 1 second and 21 milliseconds
62       in this mode.
63
64       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

FUNCTIONS

69       This module provides all the following functions, which are all
70       exported by default when you call "use Time::Duration;".
71
72       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
78           For example, duration(120) or duration(-120) is "2 minutes".  And
79           duration(0) is "0 seconds".
80
81           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
94       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
100       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
109       ago_exact($seconds)
110           Same as ago($seconds), except that the returned value is an exact
111           (unrounded) expression of $seconds.
112
113       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
120       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
129       later_exact($seconds)
130           Same as later($seconds), except that the returned value is an exact
131           (unrounded) expression of $seconds.
132
133       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
140       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
143           and 16 minutes ago", but "concise(ago(4567))" returns "1h16m ago".
144

I18N/L10N NOTES

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

BACKSTORY

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
155         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
159       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

CAVEAT

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

SEE ALSO

171       Time::Elapsed - similarly converts durations to natural language, but
172       in addition to English also supports Danish, German, French, and
173       Turkish.
174
175       Date::Interval, which is similarly named, but does something rather
176       different.
177
178       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
189       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

AUTHOR

194       Original author Sean M. Burke, "sburke@cpan.org".
195
196       Then maintained by Avi Finkel, "avi@finkel.org".
197
198       Currently maintained by Neil Bowers, "neilb@cpan.org".
199
200
201
202perl v5.34.0                      2022-01-21                 Time::Duration(3)
Impressum