\HeaderA{difftime}{Time Intervals}{difftime}
\aliasA{*.difftime}{difftime}{*.difftime}
\aliasA{/.difftime}{difftime}{/.difftime}
\aliasA{as.difftime}{difftime}{as.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{[.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")

## S3 method for class 'difftime':
round(x, digits = 0)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{time1, time2}] date-time 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{tim}] character string specifying a time interval.
\item[\code{format}] character specifying the format of \code{tim}.
\item[\code{x}] an object inheriting from class \code{"difftime"}.
\item[\code{digits}] integer.  Number of significant digits to retain.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Function \code{difftime} takes a difference of two date/time objects
(of either class) 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 two 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 time intervals.

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 implicitly
converts the numeric vector to a \code{"difftime"} object with the
same units as the \code{"difftime"} object.
\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 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
\end{ExampleCode}
\end{Examples}

