This file is indexed.

/usr/share/perl5/Time/Duration.pm is in libtime-duration-perl 1.20-1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
package Time::Duration;
$Time::Duration::VERSION = '1.20';
use 5.006;
use strict;
use warnings;
use constant DEBUG => 0;

require Exporter;

our @ISA         = ('Exporter');
our @EXPORT      = qw( later later_exact earlier earlier_exact
                       ago ago_exact from_now from_now_exact
                       duration duration_exact
                       concise
                     );
our @EXPORT_OK   = ('interval', @EXPORT);
our $MILLISECOND = 0;

# ALL SUBS ARE PURE FUNCTIONS

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sub concise ($) {
  my $string = $_[0];
  DEBUG and print "in : $string\n";
  $string =~ tr/,//d;
  $string =~ s/\band\b//;
  $string =~ s/\b(year|day|hour|minute|second)s?\b/substr($1,0,1)/eg;
  $string =~ s/\b(millisecond)s?\b/ms/g;
  $string =~ s/\s*(\d+)\s*/$1/g;
  return $string;
}

sub later {
  interval(      $_[0], $_[1], ' earlier', ' later', 'right then'); }
sub later_exact {
  interval_exact($_[0], $_[1], ' earlier', ' later', 'right then'); }
sub earlier {
  interval(      $_[0], $_[1], ' later', ' earlier', 'right then'); }
sub earlier_exact {
  interval_exact($_[0], $_[1], ' later', ' earlier', 'right then'); }
sub ago {
  interval(      $_[0], $_[1], ' from now', ' ago', 'right now'); }
sub ago_exact {
  interval_exact($_[0], $_[1], ' from now', ' ago', 'right now'); }
sub from_now {
  interval(      $_[0], $_[1], ' ago', ' from now', 'right now'); }
sub from_now_exact {
  interval_exact($_[0], $_[1], ' ago', ' from now', 'right now'); }

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
sub duration_exact {
  my $span = $_[0];   # interval in seconds
  my $precision = int($_[1] || 0) || 2;  # precision (default: 2)
  return '0 seconds' unless $span;
  _render('',
          _separate(abs $span));
}

sub duration {
  my $span = $_[0];   # interval in seconds
  my $precision = int($_[1] || 0) || 2;  # precision (default: 2)
  return '0 seconds' unless $span;
  _render('',
          _approximate($precision,
                       _separate(abs $span)));
}

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

sub interval_exact {
  my $span = $_[0];                    # interval, in seconds
                                       # precision is ignored
  my $direction = ($span < 0) ? $_[2]  # what a neg number gets
                : ($span > 0) ? $_[3]  # what a pos number gets
                : return        $_[4]; # what zero gets
  _render($direction,
          _separate($span));
}

sub interval {
  my $span = $_[0];                     # interval, in seconds
  my $precision = int($_[1] || 0) || 2; # precision (default: 2)
  my $direction = ($span < 0) ? $_[2]   # what a neg number gets
                : ($span > 0) ? $_[3]   # what a pos number gets
                : return        $_[4];  # what zero gets
  _render($direction,
          _approximate($precision,
                       _separate($span)));
}

#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#~#
#
# The actual figuring is below here

use constant MINUTE => 60;
use constant HOUR => 3600;
use constant DAY  => 24 * HOUR;
use constant YEAR => 365 * DAY;

sub _separate {
  # Breakdown of seconds into units, starting with the most significant
  
  my $remainder = abs $_[0]; # remainder
  my $this; # scratch
  my @wheel; # retval
  
  # Years:
  $this = int($remainder / (365 * 24 * 60 * 60));
  push @wheel, ['year', $this, 1_000_000_000];
  $remainder -= $this * (365 * 24 * 60 * 60);
    
  # Days:
  $this = int($remainder / (24 * 60 * 60));
  push @wheel, ['day', $this, 365];
  $remainder -= $this * (24 * 60 * 60);
    
  # Hours:
  $this = int($remainder / (60 * 60));
  push @wheel, ['hour', $this, 24];
  $remainder -= $this * (60 * 60);
  
  # Minutes:
  $this = int($remainder / 60);
  push @wheel, ['minute', $this, 60];
  $remainder -= $this * 60;
  
  push @wheel, ['second', int($remainder), 60];

	# Thanks to Steven Haryanto (http://search.cpan.org/~sharyanto/) for the basis of this change.
	if ($MILLISECOND) {
		$remainder -= int($remainder);
		push @wheel, ['millisecond', sprintf("%0.f", $remainder * 1000), 1000];
	}

  return @wheel;
}

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
sub _approximate {
  # Now nudge the wheels into an acceptably (im)precise configuration
  my($precision, @wheel) = @_;

 Fix:
  {
    # Constraints for leaving this block:
    #  1) number of nonzero wheels must be <= $precision
    #  2) no wheels can be improperly expressed (like having "60" for mins)
  
    my $nonzero_count = 0;
    my $improperly_expressed;

    DEBUG and print join ' ', '#', (map "${$_}[1] ${$_}[0]",  @wheel), "\n";
    for(my $i = 0; $i < @wheel; $i++) {
      my $this = $wheel[$i];
      next if $this->[1] == 0; # Zeros require no attention.
      ++$nonzero_count;
      next if $i == 0; # the years wheel is never improper or over any limit; skip
      
      if($nonzero_count > $precision) {
        # This is one nonzero wheel too many!
        DEBUG and print '', $this->[0], " is one nonzero too many!\n";

        # Incr previous wheel if we're big enough:
        if($this->[1] >= ($this->[-1] / 2)) {
          DEBUG and printf "incrementing %s from %s to %s\n",
           $wheel[$i-1][0], $wheel[$i-1][1], 1 + $wheel[$i-1][1], ;
          ++$wheel[$i-1][1];
        }

        # Reset this and subsequent wheels to 0:
        for(my $j = $i; $j < @wheel; $j++) { $wheel[$j][1] = 0 }
        redo Fix; # Start over.
      } elsif($this->[1] >= $this->[-1]) {
        # It's an improperly expressed wheel.  (Like "60" on the mins wheel)
        $improperly_expressed = $i;
        DEBUG and print '', $this->[0], ' (', $this->[1], 
           ") is improper!\n";
      }
    }
    
    if(defined $improperly_expressed) {
      # Only fix the least-significant improperly expressed wheel (at a time).
      DEBUG and printf "incrementing %s from %s to %s\n",
       $wheel[$improperly_expressed-1][0], $wheel[$improperly_expressed-1][1], 
        1 + $wheel[$improperly_expressed-1][1], ;
      ++$wheel[ $improperly_expressed - 1][1];
      $wheel[ $improperly_expressed][1] = 0;
      # We never have a "150" in the minutes slot -- if it's improper,
      #  it's only by having been rounded up to the limit.
      redo Fix; # Start over.
    }
    
    # Otherwise there's not too many nonzero wheels, and there's no
    #  improperly expressed wheels, so fall thru...
  }

  return @wheel;
}

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
sub _render {
  # Make it into English

  my $direction = shift @_;
  my @wheel = map
        {;
            (  $_->[1] == 0) ? ()  # zero wheels
            : ($_->[1] == 1) ? "${$_}[1] ${$_}[0]"  # singular
            :                  "${$_}[1] ${$_}[0]s" # plural
        }
        @_
  ;
  return "just now" unless @wheel; # sanity
  $wheel[-1] .= $direction;
  return $wheel[0] if @wheel == 1;
  return "$wheel[0] and $wheel[1]" if @wheel == 2;
  $wheel[-1] = "and $wheel[-1]";
  return join q{, }, @wheel;
}

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1;

__END__

so "1y 0d 1h 50m 50s", N=3, so you round at minutes to "1y 0d 1h 51m 0s",
#That's okay, so fall thru.

so "1y 1d 0h 59m 50s", N=3, so you round at minutes to "1y 1d 0h 60m 0s",
but that's not improperly expressed, so you loop around and get
"1y 1d 1h 0m 0s", which is short enough, and is properly expressed.

=head1 NAME

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

=head1 SYNOPSIS

Example use in a program that ends by noting its runtime:

  my $start_time = time();
  use Time::Duration;
  
  # then things that take all that time, and then ends:
  print "Runtime ", duration(time() - $start_time), ".\n";

Example use in a program that reports age of a file:

  use Time::Duration;
  my $file = 'that_file';
  my $age = $^T - (stat($file))[9];  # 9 = modtime
  print "$file was modified ", ago($age);

=head1 DESCRIPTION

This module provides functions for expressing durations in rounded or exact
terms.


In the first example in the Synopsis, using duration($interval_seconds):

If the C<time() - $start_time> is 3 seconds, this prints
"Runtime: B<3 seconds>.".  If it's 0 seconds, it's "Runtime: B<0 seconds>.".
If it's 1 second, it's "Runtime: B<1 second>.".  If it's 125 seconds, you
get "Runtime: B<2 minutes and 5 seconds>.".  If it's 3820 seconds (which
is exactly 1h, 3m, 40s), you get it rounded to fit within two expressed
units: "Runtime: B<1 hour and 4 minutes>.".  Using duration_exact instead
would return "Runtime: B<1 hour, 3 minutes, and 40 seconds>".

In the second example in the Synopsis, using ago($interval_seconds):

If the $age is 3 seconds, this prints
"I<file> was modified B<3 seconds ago>".  If it's 0 seconds, it's
"I<file> was modified B<just now>", as a special case.  If it's 1 second,
it's "from B<1 second ago>".  If it's 125 seconds, you get "I<file> was
modified B<2 minutes and 5 seconds ago>".  If it's 3820 seconds (which
is exactly 1h, 3m, 40s), you get it rounded to fit within two expressed
units: "I<file> was modified B<1 hour and 4 minutes ago>".  
Using ago_exact instead
would return "I<file> was modified B<1 hour, 3 minutes, and 40 seconds
ago>".  And if the file's
modtime is, surprisingly, three seconds into the future, $age is -3,
and you'll get the equally and appropriately surprising
"I<file> was modified B<3 seconds from now>."

=head1 MILLISECOND MODE

By default, this module assumes input is an integer representing number
of seconds and only emits results based on the integer part of any
floating-point values passed to it.  However, if you set the variable
C<$Time::Duration::MILLISECOND> to any true value, then the methods will
interpret inputs as floating-point numbers and will emit results containing
information about the number of milliseconds in the value.

For example, C<duration(1.021)> will return B<1 second and 21 milliseconds>
in this mode.

Millisecond mode is not enabled by default because this module sees heavy use
and existing users of it may be relying on its implicit truncation of non-integer
arguments.


=head1 FUNCTIONS

This module provides all the following functions, which are all exported
by default when you call C<use Time::Duration;>.


=over

=item duration($seconds)

=item duration($seconds, $precision)

Returns English text expressing the approximate time duration 
of abs($seconds), with at most S<C<$precision || 2>> expressed units.
(That is, duration($seconds) is the same as duration($seconds,2).)

For example, duration(120) or duration(-120) is "2 minutes".  And
duration(0) is "0 seconds".

The precision figure means that no more than that many units will
be used in expressing the time duration.  For example,
31,629,659 seconds is a duration of I<exactly>
1 year, 1 day, 2 hours, and 59 seconds (assuming 1 year = exactly
365 days, as we do assume in this module).  However, if you wanted
an approximation of this to at most two expressed (i.e., nonzero) units, it
would round it and truncate it to "1 year and 1 day".  Max of 3 expressed
units would get you "1 year, 1 day, and 2 hours".  Max of 4 expressed
units would get you "1 year, 1 day, 2 hours, and 59 seconds",
which happens to be exactly true.  Max of 5 (or more) expressed units
would get you the same, since there are only four nonzero units possible
in for that duration.

=item duration_exact($seconds)

Same as duration($seconds), except that the returned value is an exact
(unrounded) expression of $seconds.  For example, duration_exact(31629659)
returns "1 year, 1 day, 2 hours, and 59 seconds later",
which is I<exactly> true.


=item ago($seconds)

=item ago($seconds, $precision)

For a positive value of seconds, this prints the same as
C<duration($seconds, [$precision]) . S<' ago'>>.  For example,
ago(120) is "2 minutes ago".  For a negative value of seconds,
this prints the same as
C<duration($seconds, [$precision]) . S<' from now'>>.  For example,
ago(-120) is "2 minutes from now".  As a special case, ago(0)
returns "right now".

=item ago_exact($seconds)

Same as ago($seconds), except that the returned value is an exact
(unrounded) expression of $seconds.


=item from_now($seconds)

=item from_now($seconds, $precision)

=item from_now_exact($seconds)

The same as ago(-$seconds), ago(-$seconds, $precision), 
ago_exact(-$seconds).  For example, from_now(120) is "2 minutes from now".


=item later($seconds)

=item later($seconds, $precision)

For a positive value of seconds, this prints the same as
C<duration($seconds, [$precision]) . S<' later'>>.  For example,
ago(120) is "2 minutes later".  For a negative value of seconds,
this prints the same as
C<duration($seconds, [$precision]) . S<' earlier'>>.  For example,
later(-120) is "2 minutes earlier".  As a special case, later(0)
returns "right then".

=item later_exact($seconds)

Same as later($seconds), except that the returned value is an exact
(unrounded) expression of $seconds.

=item earlier($seconds)

=item earlier($seconds, $precision)

=item earlier_exact($seconds)

The same as later(-$seconds), later(-$seconds, $precision), 
later_exact(-$seconds).  For example, earlier(120) is "2 minutes earlier".


=item concise( I<function(> ... ) )

Concise takes the string output of one of the above functions and makes
it more concise.  For example, 
C<< ago(4567) >> returns "1 hour and 16 minutes ago", but
C<< concise(ago(4567)) >> returns "1h16m ago".

=back



=head1 I18N/L10N NOTES

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



=head1 BACKSTORY

I wrote the basic C<ago()> function for use in Infobot
(C<http://www.infobot.org>), because I was tired of this sort of
response from the Purl Infobot:

  me> Purl, seen Woozle?
  <Purl> Woozle was last seen on #perl 20 days, 7 hours, 32 minutes
  and 40 seconds ago, saying: Wuzzle!

I figured if it was 20 days ago, I don't care about the seconds.  So
once I had written C<ago()>, I abstracted the code a bit and got
all the other functions.


=head1 CAVEAT

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


=head1 SEE ALSO

L<Date::Interval|Date::Interval>, which is similarly named, but does
something rather different.

I<Star Trek: The Next Generation> (1987-1994), where the character
Data would express time durations like
"1 year, 20 days, 22 hours, 59 minutes, and 35 seconds"
instead of rounding to "1 year and 21 days".  This is because no-one
ever told him to use Time::Duration.



=head1 COPYRIGHT AND DISCLAIMER

Copyright 2013, Sean M. Burke C<sburke@cpan.org>; Avi Finkel,
C<avi@finkel.org>, all rights reserved.  This program is free
software; you can redistribute it and/or modify it under the
same terms as Perl itself.

This program is distributed in the hope that it will be useful,
but without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

=head1 AUTHOR

Current maintainer Avi Finkel, C<avi@finkel.org>; Original author
Sean M. Burke, C<sburke@cpan.org>

=cut