difftime                package: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 replacement 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)

