.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Time::Duration 3pm"
.TH Time::Duration 3pm "2015-04-25" "perl v5.20.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Time::Duration \- rounded or exact English expression of durations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
Example use in a program that ends by noting its runtime:
.PP
.Vb 2
\&  my $start_time = time();
\&  use Time::Duration;
\&  
\&  # then things that take all that time, and then ends:
\&  print "Runtime ", duration(time() \- $start_time), ".\en";
.Ve
.PP
Example use in a program that reports age of a file:
.PP
.Vb 4
\&  use Time::Duration;
\&  my $file = \*(Aqthat_file\*(Aq;
\&  my $age = $^T \- (stat($file))[9];  # 9 = modtime
\&  print "$file was modified ", ago($age);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides functions for expressing durations in rounded or exact
terms.
.PP
In the first example in the Synopsis, using duration($interval_seconds):
.PP
If the \f(CW\*(C`time() \- $start_time\*(C'\fR is 3 seconds, this prints
"Runtime: \fB3 seconds\fR.\*(L".  If it's 0 seconds, it's \*(R"Runtime: \fB0 seconds\fR.\*(L".
If it's 1 second, it's \*(R"Runtime: \fB1 second\fR.\*(L".  If it's 125 seconds, you
get \*(R"Runtime: \fB2 minutes and 5 seconds\fR.\*(L".  If it's 3820 seconds (which
is exactly 1h, 3m, 40s), you get it rounded to fit within two expressed
units: \*(R"Runtime: \fB1 hour and 4 minutes\fR.\*(L".  Using duration_exact instead
would return \*(R"Runtime: \fB1 hour, 3 minutes, and 40 seconds\fR".
.PP
In the second example in the Synopsis, using ago($interval_seconds):
.PP
If the \f(CW$age\fR is 3 seconds, this prints
"\fIfile\fR was modified \fB3 seconds ago\fR\*(L".  If it's 0 seconds, it's
\&\*(R"\fIfile\fR was modified \fBjust now\fR\*(L", as a special case.  If it's 1 second,
it's \*(R"from \fB1 second ago\fR\*(L".  If it's 125 seconds, you get \*(R"\fIfile\fR was
modified \fB2 minutes and 5 seconds ago\fR\*(L".  If it's 3820 seconds (which
is exactly 1h, 3m, 40s), you get it rounded to fit within two expressed
units: \*(R"\fIfile\fR was modified \fB1 hour and 4 minutes ago\fR\*(L".  
Using ago_exact instead
would return \*(R"\fIfile\fR was modified \fB1 hour, 3 minutes, and 40 seconds
ago\fR\*(L".  And if the file's
modtime is, surprisingly, three seconds into the future, \f(CW$age\fR is \-3,
and you'll get the equally and appropriately surprising
\&\*(R"\fIfile\fR was modified \fB3 seconds from now\fR."
.SH "MILLISECOND MODE"
.IX Header "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
\&\f(CW$Time::Duration::MILLISECOND\fR 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.
.PP
For example, \f(CW\*(C`duration(1.021)\*(C'\fR will return \fB1 second and 21 milliseconds\fR
in this mode.
.PP
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.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
This module provides all the following functions, which are all exported
by default when you call \f(CW\*(C`use Time::Duration;\*(C'\fR.
.IP "duration($seconds)" 4
.IX Item "duration($seconds)"
.PD 0
.ie n .IP "duration($seconds, $precision)" 4
.el .IP "duration($seconds, \f(CW$precision\fR)" 4
.IX Item "duration($seconds, $precision)"
.PD
Returns English text expressing the approximate time duration 
of abs($seconds), with at most \f(CW\*(C`$precision\ ||\ 2\*(C'\fR expressed units.
(That is, duration($seconds) is the same as duration($seconds,2).)
.Sp
For example, duration(120) or duration(\-120) is \*(L"2 minutes\*(R".  And
\&\fIduration\fR\|(0) is \*(L"0 seconds\*(R".
.Sp
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 \fIexactly\fR
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 \*(L"1 year and 1 day\*(R".  Max of 3 expressed
units would get you \*(L"1 year, 1 day, and 2 hours\*(R".  Max of 4 expressed
units would get you \*(L"1 year, 1 day, 2 hours, and 59 seconds\*(R",
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.
.IP "duration_exact($seconds)" 4
.IX Item "duration_exact($seconds)"
Same as duration($seconds), except that the returned value is an exact
(unrounded) expression of \f(CW$seconds\fR.  For example, duration_exact(31629659)
returns \*(L"1 year, 1 day, 2 hours, and 59 seconds later\*(R",
which is \fIexactly\fR true.
.IP "ago($seconds)" 4
.IX Item "ago($seconds)"
.PD 0
.ie n .IP "ago($seconds, $precision)" 4
.el .IP "ago($seconds, \f(CW$precision\fR)" 4
.IX Item "ago($seconds, $precision)"
.PD
For a positive value of seconds, this prints the same as
\&\f(CW\*(C`duration($seconds, [$precision]) . \*(Aq\ ago\*(Aq\*(C'\fR.  For example,
ago(120) is \*(L"2 minutes ago\*(R".  For a negative value of seconds,
this prints the same as
\&\f(CW\*(C`duration($seconds, [$precision]) . \*(Aq\ from\ now\*(Aq\*(C'\fR.  For example,
ago(\-120) is \*(L"2 minutes from now\*(R".  As a special case, \fIago\fR\|(0)
returns \*(L"right now\*(R".
.IP "ago_exact($seconds)" 4
.IX Item "ago_exact($seconds)"
Same as ago($seconds), except that the returned value is an exact
(unrounded) expression of \f(CW$seconds\fR.
.IP "from_now($seconds)" 4
.IX Item "from_now($seconds)"
.PD 0
.ie n .IP "from_now($seconds, $precision)" 4
.el .IP "from_now($seconds, \f(CW$precision\fR)" 4
.IX Item "from_now($seconds, $precision)"
.IP "from_now_exact($seconds)" 4
.IX Item "from_now_exact($seconds)"
.PD
The same as ago(\-$seconds), ago(\-$seconds, \f(CW$precision\fR), 
ago_exact(\-$seconds).  For example, from_now(120) is \*(L"2 minutes from now\*(R".
.IP "later($seconds)" 4
.IX Item "later($seconds)"
.PD 0
.ie n .IP "later($seconds, $precision)" 4
.el .IP "later($seconds, \f(CW$precision\fR)" 4
.IX Item "later($seconds, $precision)"
.PD
For a positive value of seconds, this prints the same as
\&\f(CW\*(C`duration($seconds, [$precision]) . \*(Aq\ later\*(Aq\*(C'\fR.  For example,
ago(120) is \*(L"2 minutes later\*(R".  For a negative value of seconds,
this prints the same as
\&\f(CW\*(C`duration($seconds, [$precision]) . \*(Aq\ earlier\*(Aq\*(C'\fR.  For example,
later(\-120) is \*(L"2 minutes earlier\*(R".  As a special case, \fIlater\fR\|(0)
returns \*(L"right then\*(R".
.IP "later_exact($seconds)" 4
.IX Item "later_exact($seconds)"
Same as later($seconds), except that the returned value is an exact
(unrounded) expression of \f(CW$seconds\fR.
.IP "earlier($seconds)" 4
.IX Item "earlier($seconds)"
.PD 0
.ie n .IP "earlier($seconds, $precision)" 4
.el .IP "earlier($seconds, \f(CW$precision\fR)" 4
.IX Item "earlier($seconds, $precision)"
.IP "earlier_exact($seconds)" 4
.IX Item "earlier_exact($seconds)"
.PD
The same as later(\-$seconds), later(\-$seconds, \f(CW$precision\fR), 
later_exact(\-$seconds).  For example, earlier(120) is \*(L"2 minutes earlier\*(R".
.IP "concise( \fIfunction(\fR ... ) )" 4
.IX Item "concise( function( ... ) )"
Concise takes the string output of one of the above functions and makes
it more concise.  For example, 
\&\f(CW\*(C`ago(4567)\*(C'\fR returns \*(L"1 hour and 16 minutes ago\*(R", but
\&\f(CW\*(C`concise(ago(4567))\*(C'\fR returns \*(L"1h16m ago\*(R".
.SH "I18N/L10N NOTES"
.IX Header "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.
.SH "BACKSTORY"
.IX Header "BACKSTORY"
I wrote the basic \f(CW\*(C`ago()\*(C'\fR function for use in Infobot
(\f(CW\*(C`http://www.infobot.org\*(C'\fR), because I was tired of this sort of
response from the Purl Infobot:
.PP
.Vb 3
\&  me> Purl, seen Woozle?
\&  <Purl> Woozle was last seen on #perl 20 days, 7 hours, 32 minutes
\&  and 40 seconds ago, saying: Wuzzle!
.Ve
.PP
I figured if it was 20 days ago, I don't care about the seconds.  So
once I had written \f(CW\*(C`ago()\*(C'\fR, I abstracted the code a bit and got
all the other functions.
.SH "CAVEAT"
.IX Header "CAVEAT"
This module calls a durational \*(L"year\*(R" 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Date::Interval, which is similarly named, but does
something rather different.
.PP
\&\fIStar Trek: The Next Generation\fR (1987\-1994), where the character
Data would express time durations like
\&\*(L"1 year, 20 days, 22 hours, 59 minutes, and 35 seconds\*(R"
instead of rounding to \*(L"1 year and 21 days\*(R".  This is because no-one
ever told him to use Time::Duration.
.SH "COPYRIGHT AND DISCLAIMER"
.IX Header "COPYRIGHT AND DISCLAIMER"
Copyright 2013, Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR; Avi Finkel,
\&\f(CW\*(C`avi@finkel.org\*(C'\fR, all rights reserved.  This program is free
software; you can redistribute it and/or modify it under the
same terms as Perl itself.
.PP
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.
.SH "AUTHOR"
.IX Header "AUTHOR"
Current maintainer Avi Finkel, \f(CW\*(C`avi@finkel.org\*(C'\fR; Original author
Sean M. Burke, \f(CW\*(C`sburke@cpan.org\*(C'\fR