DateTimeClasses             package:base             R Documentation

_D_a_t_e-_T_i_m_e _C_l_a_s_s_e_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     ## S3 method for class 'POSIXct':
     print(x, ...)

     ## S3 method for class 'POSIXct':
     summary(object, digits = 15, ...)

     time + z
     time - z
     time1 lop time2

_A_r_g_u_m_e_n_t_s:

x, object: An object to be printed or summarized from one of the
          date-time classes.

  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: date-time objects

time1, time2: date-time objects or character vectors.  (Character
          vectors are converted by 'as.POSIXct'.)

       z: a numeric vector (in seconds)

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

_D_e_t_a_i_l_s:

     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

     '_s_e_c' 0-61: seconds

     '_m_i_n' 0-59: minutes

     '_h_o_u_r' 0-23: hours

     '_m_d_a_y' 1-31: day of the month

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

     '_y_e_a_r' Years since 1900.

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

     '_y_d_a_y' 0-365: day of the year.

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

     The classes correspond to the POSIX/C99 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.

     Components 'wday' and 'yday' of '"POSIXlt"' are for information,
     and are not used in the conversion to calendar time. However,
     'isdst' is needed to distinguish times at the end of DST:
     typically 1am to 2am occurs twice, first in DST and then in
     standard time.  At all other times 'isdst' can be deduced from the
     first six values, but the behaviour if it is set incorrectly is
     platform-dependent.

     Logical comparisons and limited arithmetic are available for both
     classes.  One can add or subtract a number of seconds 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.

     '"POSIXct"' objects may also have an attribute '"tzone"', a
     character vector of length one.  If set, it will determine how the
     object is converted to class '"POSIXlt"' and in particular how it
     is printed.  This is usually desirable, but if you want to specify
     an object in a particular timezone but to be printed in the
     current timezone you may want to remove the '"tzone"' attribute
     (e.g. by 'c(x)').

     Unfortunately, the conversion is complicated by the operation of
     time zones and leap seconds (23 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 always covers the period 1970-2037,
     and on most machines back to 1902 (when time zones were in their
     infancy).  Outside the platform limits we use our own C code. 
     This uses the offset from GMT in use either for 1902 (when there
     was no DST) or that predicted for one of 2030 to 2037 (chosen so
     that the likely DST transition days are Sundays), and uses the
     alternate (daylight-saving) timezone only if 'isdst' is positive
     or (if '-1') if DST was predicted to be in operation in the 2030s
     on that day.  (There is no reason to suppose that the DST rules
     will remain the same in the future, and indeed the US legislated
     in 2005 to change its rules as from 2007, with a possible future
     reversion.)

     It seems that some rare systems use leap seconds, but most ignore
     them (as required by POSIX).  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 or the
     'zoneinfo' database.)

     Using 'c' on '"POSIXlt"' objects converts them to the current time
     zone, and on '"POSIXct"' objects drops any '"tzone"' attributes
     (even if they are all marked with the same time zone).

     A few times have specific issues.  First, the leapseconds are
     ignored, and real times such as '"2005-12-31 23:59:60"' are
     (probably) treated as the next second.  However, they will never
     be generated by R, and are unlikely to arise as input.  Second, on
     some OSes there is a problem in the POSIX/C99 standard with
     '"1969-12-31 23:59:59"', which is '-1' in calendar time and is
     used as an error code. Thus 'as.POSIXct("1969-12-31 23:59:59",
     format="%Y-%m-%d %H:%M:%S", tz="UTC")' may give 'NA', and hence
     'as.POSIXct("1969-12-31 23:59:59", tz="UTC")' will give
     '"1969-12-31 23:59:50"'. Other OSes report errors separately and
     so are able to handle that time as valid.

_S_u_b-_s_e_c_o_n_d _A_c_c_u_r_a_c_y:

     Classes '"POSIXct"' and  '"POSIXlt"' are able to express fractions
     of a second.  (Conversion of fractions between the two forms may
     not be exact, but will have better than microsecond accuracy.)

     Fractional seconds are printed only if 'options("digits.secs")' is
     set: see 'strftime'.

_W_a_r_n_i_n_g:

     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 'as.POSIXlt' for valid settings.

_S_e_e _A_l_s_o:

     Dates for dates without times.

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

_E_x_a_m_p_l_e_s:

     (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 23 leapseconds in your timezone
     print(.leap.seconds, tz="PST8PDT")  # and in Seattle's