DateTimeClasses             package:base             R Documentation

Date-Time Classes

Description:

     Description of the classes `"POSIXlt"' and `"POSIXct"'
     representing calendar dates and times (to the nearest second).

Usage:

     print.POSIXct(x, ...)
     print.POSIXlt(x, ...)

     summary.POSIXct(object, digits = 15, ...)
     summary.POSIXlt(object, digits = 15, ...)

     time + number
     time - number
     time1 lop time2

Arguments:

x, object: An object to be printed or summarized.

  digits: Number of significant digits for the computations: should be
          high enough to represent the least important time unit
          exactly.

     ...: Further arguments to be passed from or to other methods.

time, time1, time2: date-time objects.

  number: a numeric object.

     lop: One of `==', `!=', `<', `<=', `>' or `>='.

Details:

     There are two basic classes of date/times.  Class `"POSIXct"'
     represents the (signed) number of seconds since the beginning of
     1970 as a numeric vector.  Class `"POSIXlt"' is a named list of
     vectors representing

     `sec' 0-61: seconds

     `min' 0-59: minutes

     `hour' 0-23: hours

     `mday' 1-31: day of the month

     `mon' 0-11: months after the first of the year.

     `year' Years since 1900.

     `wday' 0-6 day of the week, starting on Sunday.

     `yday' 0-365: day of the year.

     `isdst' Daylight savings time flag. Positive if in force, zero if
          not, negative if unknown.

     The classes correspond to the ANSI C constructs of ``calendar
     time'' (the `time_t' data type) and ``local time'' (or broken-down
     time, the `struct tm' data type), from which they also inherit
     their names.

     `"POSIXct"' is more convenient for including in data frames, and
     `"POSIXlt"' is closer to human-readable forms. A virtual class
     `"POSIXt"' inherits from both of the classes: it is used to allow
     operations such as subtraction to mix the two classes.

     Logical comparisons and limited arithmetic are available for both
     classes. One can add or subtract a number of seconds or a
     `difftime' object from a date-time object, but not add two
     date-time objects.  Subtraction of two date-time objects is
     equivalent to using `difftime'.  Be aware that `"POSIXlt"' objects
     will be interpreted as being in the current timezone for these
     operations, unless a timezone has been specified.

     `"POSIXlt"' objects will often have an attribute `"tzone"', a
     character vector of length 3 giving the timezone name from the
     `"TZ"' environment variable and the names of the base timezone and
     the alternate (daylight-saving) timezone.  Sometimes this may just
     be of length one, giving the timezone name.

     Unfortunately, the conversion is complicated by the operation of
     time zones and leap seconds (22 days have been 86401 seconds long
     so far: the times of the extra seconds are in the object
     `.leap.seconds'). The details of this are entrusted to the OS
     services where possible. This will usually cover the period
     1970-2037, and on Unix machines back to 1902 (when time zones were
     in their infancy).  Outside those ranges we use our own C code. 
     This uses the offset from GMT in use in the timezone in 2000, and
     uses the alternate (daylight-saving) timezone only if `isdst' is
     positive.

     It seems that some systems use leap seconds but most do not. This
     is detected and corrected for at build time, so all `"POSIXct"'
     times used by R do not include leap seconds.  (Conceivably this
     could be wrong if the system has changed since build time, just
     possibly by changing locales.)

     Using `c' on `"POSIXlt"' objects converts them to the current time
     zone.

Warning:

     Some Unix-like systems (especially Linux ones) do not have `"TZ"'
     set, yet have internal code that expects it (as does POSIX).  We
     have tried to work around this, but if you get unexpected results
     try setting `"TZ"'.

See Also:

     `as.POSIXct' and `as.POSIXlt' for conversion between the classes.

     `strptime' for conversion to and from character representations.

     `Sys.time' for clock time as a `"POSIXct"' object.

     `difftime' for time intervals.

     `cut.POSIXt', `seq.POSIXt', `round.POSIXt' and `trunc.POSIXt' for
     methods for these classes.

     `weekdays.POSIXt' for convenience extraction functions.

Examples:

     (z <- Sys.time())             # the current date, as class "POSIXct"

     Sys.time() - 3600             # an hour ago

     as.POSIXlt(Sys.time(), "GMT") # the current time in GMT
     format(.leap.seconds)         # all 22 leapseconds in your timezone

