difftime {base}R Documentation

Time Intervals


Create, print and round time intervals.


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':
## S3 method for class 'difftime':
units(x) <- value
## S3 method for class 'difftime':
as.double(x, units="auto", ...)


time1, time2 date-time or date objects.
tz a timezone specification to be used for the conversion. System-specific, but "" is the current time zone, and "GMT" is UTC.
units character. Units in which the results are desired. Can be abbreviated.
value character. Like units above, except that abbreviations are not allowed.
tim character string or numeric value specifying a time interval.
format character specifying the format of tim: see strptime. The default is a locale-specific time format.
x an object inheriting from class "difftime".
digits integer. Number of significant digits to retain.
... arguments to be passed to or from other methods.


Function difftime calculates a difference of two date/time objects and returns an object of class "difftime" with an attribute indicating the units. There is a round method for objects of this class, as well as methods for the group-generic (see Ops) logical and arithmetic operations.

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

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

Limited arithmetic is available on "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 "difftime" object with the same units as the "difftime" object.

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

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

The format method simply formats the numeric value and appends the units as a text string.

See Also



(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
(z <- as.difftime(c(0,30,60), units="mins"))
as.numeric(z, units="secs")
as.numeric(z, units="hours")

[Package base version 2.5.0 Index]