% File src/library/base/man/difftime.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later

\name{difftime}
\title{Time Intervals / Differences}
\alias{difftime}
\alias{as.difftime}
\alias{as.double.difftime}
\alias{is.numeric.difftime}
\alias{print.difftime}
\alias{format.difftime}
\alias{units.difftime}
\alias{units<-.difftime}
\alias{Ops.difftime}
\alias{*.difftime}
\alias{/.difftime}
\alias{Math.difftime}
\alias{Summary.difftime}
\alias{[.difftime}
\alias{mean.difftime}
\alias{diff.difftime}
\alias{c.difftime}
\alias{length<-.difftime}
\alias{units}
\alias{units<-}
\alias{time interval} % used by mean.Rd
\description{
  Time intervals creation, printing, and some arithmetic.  The
  \code{\link{print}()} method calls these \dQuote{time differences}.
}
\usage{
\special{time1 - time2}

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

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

\method{format}{difftime}(x, ...)
\method{units}{difftime}(x)
\method{units}{difftime}(x) <- value
\method{as.double}{difftime}(x, units = "auto", ...)

## Group methods, notably for round(), signif(), floor(),
## ceiling(), trunc(), abs(); called directly, *not* as Math():
\method{Math}{difftime}(x, \dots)
}
\arguments{
  \item{time1, time2}{\link{date-time} or \link[=Dates]{date} objects.}
  \item{tz}{an optional \link{time zone} specification to be used for the
    conversion, mainly for \code{"POSIXlt"} objects.}
  \item{units}{character string.  Units in which the results are
    desired.  Can be abbreviated.}
  \item{value}{character string.  Like \code{units}, except that
    abbreviations are not allowed.}
  \item{tim}{character string or numeric value specifying a time interval.}
  \item{format}{character specifying the format of \code{tim}: see
    \code{\link{strptime}}.  The default is a locale-specific time format.}
  \item{x}{an object inheriting from class \code{"difftime"}.}
  \item{\dots}{arguments to be passed to or from other methods.}
}
\details{
  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.  The
  \code{\link[=S3groupGeneric]{Math}} group method provides
  \code{\link{round}}, \code{\link{signif}}, \code{\link{floor}},
  \code{\link{ceiling}}, \code{\link{trunc}}, \code{\link{abs}}, and
  \code{\link{sign}} methods for objects of this class, and there are
  methods for the group-generic (see
  \code{\link[=S3groupGeneric]{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{\link{mean}} and
  \code{\link{sum}} (via the \code{\link[=S3groupGeneric]{Summary}}
  group generic), and \code{\link{diff}} via \code{\link{diff.default}}
  building on the \code{"difftime"} method for arithmetic, notably
  \code{-}.

  The units of a \code{"difftime"} object can be extracted by the
  \code{units} function, which also has a replacement form.  If the
  units are changed, the numerical value is scaled accordingly.  The
  replacement version keeps attributes such as names and dimensions.

  Note that \code{units = "days"} means a period of 24 hours, hence
  takes no account of Daylight Savings Time.  Differences in objects
  of class \code{"\link{Date}"} are computed as if in the UTC time zone.

  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.
}
\note{
  Units such as \code{"months"} are not possible as they are not of
  constant length.  To create intervals of months, quarters or years
  use \code{\link{seq.Date}} or \code{\link{seq.POSIXt}}.
}
\seealso{
  \code{\link{DateTimeClasses}}.
}
\examples{\donttest{
(z <- Sys.time() - 3600)
Sys.time() - z                # just over 3600 seconds.

## time interval between release days 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)
}}
\keyword{utilities}
\keyword{chron}