R: Time Intervals (original) (raw)
| difftime {base} | R Documentation |
|---|
Time Intervals / Differences
Description
Time intervals creation, printing, and some arithmetic. The[print](../../base/help/print.html)() method calls these “time differences”.
Usage
time1 - time2
difftime(time1, time2, tz,
units = c("auto", "secs", "mins", "hours",
"days", "weeks"))
as.difftime(tim, format = "%X", units = "auto", tz = "UTC")
## S3 method for class 'difftime'
format(x, ..., with.units = TRUE)
## 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", ...)
## Group methods, notably for round(), signif(), floor(),
## ceiling(), trunc(), abs(); called directly, *not* as Math():
## S3 method for class 'difftime'
Math(x, ...)
Arguments
| time1, time2 | date-time or date objects. |
|---|---|
| tz | an optional time zone specification to be used for the conversion, mainly for "POSIXlt" objects. |
| units | character string. Units in which the results are desired. Can be abbreviated. |
| value | character string. Like units, except that abbreviations are not allowed. |
| tim | character string or numeric value specifying a time interval. |
| format | character specifying the format of tim: seestrptime. The default is a locale-specific time format. |
| x | an object inheriting from class "difftime". |
| ... | arguments to be passed to or from other methods. |
| with.units | (for the format() method:) logical indicating the units should be part, e.g., "3.5 hours"; if false, the units are suppressed. |
Details
Function difftime calculates a difference of two date/time objects, time1 (end) and time2 (beginning), and returns an object of class "difftime" with an attribute indicating the units. The[Math](../../base/help/S3groupGeneric.html) group method provides[round](../../base/help/round.html), [signif](../../base/help/signif.html), [floor](../../base/help/floor.html),[ceiling](../../base/help/ceiling.html), [trunc](../../base/help/trunc.html), [abs](../../base/help/abs.html), and[sign](../../base/help/sign.html) methods for objects of this class, and there are methods for the group-generic (see[Ops](../../base/help/S3groupGeneric.html)) 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, andformat 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 by a"difftime" object implicitly converts the numeric vector to a"difftime" object with the same units as the "difftime"object. There are methods for [mean](../../base/help/mean.html) and[sum](../../base/help/sum.html) (via the [Summary](../../base/help/S3groupGeneric.html)group generic), and [diff](../../base/help/diff.html) via [diff.default](../../base/help/diff.default.html)building on the "difftime" method for arithmetic, notably-.
The units of a "difftime" object can be extracted by theunits 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 units = "days" means a period of 24 hours, hence takes no account of Daylight Savings Time. Differences in objects of class "[Date](../../base/help/Date.html)" are computed as if in the UTC time zone.
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.
Warning
Because R follows POSIX (and almost all computer clocks) in ignoring leap seconds, so do time differences. So in a UTC time zone
z <- as.POSIXct(c("2016-12-31 23:59:59", "2017-01-01 00:00:01"))
z[2] - z[1]reports ‘Time difference of 2 secs’ but 3 seconds elapsed while the computer clock advanced by 2 seconds.
If you want the elapsed time interval, you need to add in any leap seconds for yourself.
Note
Units such as "months" are not possible as they are not of constant length. To create intervals of months, quarters or years use [seq.Date](../../base/help/seq.Date.html) or [seq.POSIXt](../../base/help/seq.POSIXt.html).
See Also
[DateTimeClasses](../../base/help/DateTimeClasses.html).
Examples
(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)
[Package _base_ version 4.6.0 Index]