\HeaderA{difftime}{Time Intervals}{difftime}
\aliasA{*.difftime}{difftime}{*.difftime}
\aliasA{/.difftime}{difftime}{/.difftime}
\aliasA{as.difftime}{difftime}{as.difftime}
\aliasA{as.double.difftime}{difftime}{as.double.difftime}
\aliasA{format.difftime}{difftime}{format.difftime}
\aliasA{Math.difftime}{difftime}{Math.difftime}
\aliasA{mean.difftime}{difftime}{mean.difftime}
\aliasA{Ops.difftime}{difftime}{Ops.difftime}
\aliasA{print.difftime}{difftime}{print.difftime}
\aliasA{round.difftime}{difftime}{round.difftime}
\aliasA{Summary.difftime}{difftime}{Summary.difftime}
\aliasA{time interval}{difftime}{time interval}
\aliasA{units}{difftime}{units}
\methaliasA{units.difftime}{difftime}{units.difftime}
\aliasA{units<\Rdash}{difftime}{units<.Rdash.}
\methaliasA{units<\Rdash.difftime}{difftime}{units<.Rdash..difftime}
\aliasA{[.difftime}{difftime}{[.difftime}
\keyword{utilities}{difftime}
\keyword{chron}{difftime}
\begin{Description}\relax
Create, print and round time intervals.
\end{Description}
\begin{Usage}
\begin{verbatim}
time1 - time2

difftime(time1, time2, tz = "",
         units = c("auto", "secs", "mins", "hours",
                   "days", "weeks"))

as.difftime(tim, format = "%X", units = "auto")

## S3 method for class 'difftime':
round(x, digits = 0, ...)
## S3 method for class 'difftime':
format(x, ...)
## S3 method for class 'difftime':
units(x)
## S3 replacement method for class 'difftime':
units(x) <- value
## S3 method for class 'difftime':
as.double(x, units = "auto", ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{time1, time2}] \LinkA{date-time}{date.Rdash.time} or \LinkA{date}{date} objects.
\item[\code{tz}] a timezone specification to be used for the conversion.
System-specific, but \code{""} is the current time zone, and
\code{"GMT"} is UTC.
\item[\code{units}] character.  Units in which the results are desired. Can
be abbreviated.
\item[\code{value}] character.  Like \code{units} above, except that
abbreviations are not allowed.
\item[\code{tim}] character string or numeric value specifying a time interval.
\item[\code{format}] character specifying the format of \code{tim}: see
\code{\LinkA{strptime}{strptime}}.  The default is a locale-specific time format.
\item[\code{x}] an object inheriting from class \code{"difftime"}.
\item[\code{digits}] integer.  Number of significant digits to retain.
\item[\code{...}] arguments to be passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Function \code{difftime} calculates a difference of two date/time objects
and returns an object of class \code{"difftime"}
with an attribute indicating the units.  There is a \code{\LinkA{round}{round}}
method for objects of this class, as well as methods for the
group-generic (see \code{\LinkA{Ops}{Ops}}) logical and
arithmetic operations.

If \code{units = "auto"}, a suitable set of units is chosen, the largest
possible (excluding \code{"weeks"}) in which all the absolute
differences are greater than one.

Subtraction of date-time objects gives an object of this class,
by calling \code{difftime} with \code{units = "auto"}.  Alternatively,
\code{as.difftime()} works on character-coded or numeric time
intervals; in the latter case, units must be specified, and
\code{format} has no effect.

Limited arithmetic is available on \code{"difftime"} objects: they can
be added or subtracted, and multiplied or divided by a numeric vector.
In addition, adding or subtracting a numeric vector by a
\code{"difftime"} object implicitly converts the numeric vector to a
\code{"difftime"} object with the same units as the \code{"difftime"}
object.  There are methods for \code{\LinkA{mean}{mean}} and
\code{\LinkA{sum}{sum}} (via the \code{\LinkA{Summary}{Summary}}
group generic).

The units of a \code{"difftime"} object can be extracted by the
\code{units} function, which also has an replacement form.  If the units
are changed, the numerical value is scaled accordingly.

The \code{as.double} method returns the numeric value expressed in
the specified units.  Using  \code{units = "auto"} means the units of the
object.

The \code{format} method simply formats the numeric value and appends
the units as a text string.
\end{Details}
\begin{SeeAlso}\relax
\code{\LinkA{DateTimeClasses}{DateTimeClasses}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
(z <- Sys.time() - 3600)
Sys.time() - z                # just over 3600 seconds.

## time interval between releases of R 1.2.2 and 1.2.3.
ISOdate(2001, 4, 26) - ISOdate(2001, 2, 26)

as.difftime(c("0:3:20", "11:23:15"))
as.difftime(c("3:20", "23:15", "2:"), format= "%H:%M")# 3rd gives NA
(z <- as.difftime(c(0,30,60), units="mins"))
as.numeric(z, units="secs")
as.numeric(z, units="hours")
format(z)
\end{ExampleCode}
\end{Examples}

