R: Time Intervals

difftime {base} | R Documentation

## Time Intervals

### Description

Create, print and round time intervals.

### Usage

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

### Arguments

`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.

### Details

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 replacement 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

`DateTimeClasses`.

### Examples

    (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)

[Package base version 2.8.1 Index]