DateTimeClasses.Rd 9.82 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/DateTimeClasses.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2011 R Core Team
Radford Neal's avatar
Radford Neal committed
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
% Distributed under GPL 2 or later

\name{DateTimeClasses}
% implementation mostly in ../R/datetime.R
\alias{DateTimeClasses}
\alias{POSIXct}
\alias{POSIXlt}
\alias{POSIXt}
\alias{print.POSIXct}
\alias{print.POSIXlt}
\alias{summary.POSIXct}
\alias{summary.POSIXlt}
\alias{+.POSIXt}
\alias{-.POSIXt}
\alias{Ops.POSIXt}
\alias{Math.POSIXt}
\alias{Summary.POSIXct}
\alias{Math.POSIXlt}
\alias{Summary.POSIXlt}
\alias{[.POSIXct}
\alias{[<-.POSIXct}
\alias{[[.POSIXct}
\alias{[.POSIXlt}
\alias{[<-.POSIXlt}
\alias{as.data.frame.POSIXct}
\alias{as.data.frame.POSIXlt}
\alias{as.list.POSIXct}
\alias{.leap.seconds}
\alias{is.na.POSIXlt}
\alias{all.equal.POSIXct}
\alias{c.POSIXct}
\alias{c.POSIXlt}
\alias{as.matrix.POSIXlt}
\alias{length.POSIXlt}
\alias{mean.POSIXct}
\alias{mean.POSIXlt}
\alias{str.POSIXt}
\alias{check_tzones}
\alias{duplicated.POSIXlt}
\alias{unique.POSIXlt}
\alias{split.POSIXct}
Radford Neal's avatar
Radford Neal committed
45 46
\alias{names.POSIXlt}
\alias{names<-.POSIXlt}
Radford Neal's avatar
Radford Neal committed
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95

\alias{date-time} % linked to in difftime.Rd

\title{Date-Time Classes}
\description{
  Description of the classes \code{"POSIXlt"} and \code{"POSIXct"}
  representing calendar dates and times (to the nearest second).
}
\usage{
\method{print}{POSIXct}(x, \dots)

\method{summary}{POSIXct}(object, digits = 15, \dots)

\special{time + z}
\special{z + time}
\special{time - z}
\special{time1 lop time2}
}
\arguments{
  \item{x, object}{An object to be printed or summarized from one of the
    date-time classes.}
  \item{digits}{Number of significant digits for the computations:
    should be high enough to represent the least important time unit
    exactly.}
  \item{\dots}{Further arguments to be passed from or to other methods.}
  \item{time}{date-time objects}
  \item{time1, time2}{date-time objects or character vectors.  (Character
    vectors are converted by \code{\link{as.POSIXct}}.)}
  \item{z}{a numeric vector (in seconds)}
  \item{lop}{One of \code{==}, \code{!=}, \code{<}, \code{<=}, \code{>}
    or \code{>=}.}
}
\details{
  There are two basic classes of date/times.  Class \code{"POSIXct"}
  represents the (signed) number of seconds since the beginning of 1970
  (in the UTC timezone) as a numeric vector.  Class \code{"POSIXlt"} is
  a named list of vectors representing
  \describe{
    \item{\code{sec}}{0--61: seconds}
    \item{\code{min}}{0--59: minutes}
    \item{\code{hour}}{0--23: hours}
    \item{\code{mday}}{1--31: day of the month}
    \item{\code{mon}}{0--11: months after the first of the year.}
    \item{\code{year}}{years since 1900.}
    \item{\code{wday}}{0--6 day of the week, starting on Sunday.}
    \item{\code{yday}}{0--365: day of the year.}
    \item{\code{isdst}}{Daylight Savings Time flag.  Positive if in
      force, zero if not, negative if unknown.}
  }
Radford Neal's avatar
Radford Neal committed
96 97 98
  Note that the internal list structure is somewhat hidden, as many
  methods, including \code{\link{print}()} or \code{\link{str}}, apply
  to the abstract date-time vector, as for \code{"POSIXct"}.
Radford Neal's avatar
Radford Neal committed
99 100 101 102 103 104 105
  The classes correspond to the POSIX/C99 constructs of \sQuote{calendar
    time} (the \code{time_t} data type) and \sQuote{local time} (or
  broken-down time, the \code{struct tm} data type), from which they
  also inherit their names.  The components of \code{"POSIXlt"} are
  integer vectors, except \code{sec}.

  \code{"POSIXct"} is more convenient for including in data frames, and
Radford Neal's avatar
Radford Neal committed
106 107 108 109 110
  \code{"POSIXlt"} is closer to human-readable forms.  A virtual class
  \code{"POSIXt"} exists from which both of the classes inherit: it is
  used to allow operations such as subtraction to mix the two classes.
  Note that \code{\link{length}(x)} is the length of the corresponding
  (abstract) date/time vector, also in the \code{"POSIXlt"} case.
Radford Neal's avatar
Radford Neal committed
111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171

  Components \code{wday} and \code{yday} of \code{"POSIXlt"} are for
  information, and are not used in the conversion to calendar time.
  However, \code{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 \code{isdst} can be deduced from
  the first six values, but the behaviour if it is set incorrectly is
  platform-dependent.
  % POSIX says used 'initially', so it should probably be ignored.
  % glibc has a complicated fixup.

  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 \code{\link{difftime}}.  Be
  aware that \code{"POSIXlt"} objects will be interpreted as being in
  the current timezone for these operations, unless a timezone has been
  specified.

  \code{"POSIXlt"} objects will often have an attribute \code{"tzone"},
  a character vector of length 3 giving the timezone name from the
  \env{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.

  \code{"POSIXct"} objects may also have an attribute \code{"tzone"}, a
  character vector of length one.  If set to a non-empty value, it will
  determine how the object is converted to class \code{"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 \code{"tzone"}
  attribute (e.g. by \code{c(x)}).

  Unfortunately, the conversion is complicated by the operation of time
  zones and leap seconds (24 days have been 86401 seconds long so far:
  the times of the extra seconds are in the object \code{.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 \code{isdst} is positive or (if \code{-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 \code{"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
  \file{zoneinfo} database.)

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

Radford Neal's avatar
Radford Neal committed
172
  A few times have specific issues.  First, the leap seconds are ignored,
Radford Neal's avatar
Radford Neal committed
173 174 175
  and real times such as \code{"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
Radford Neal's avatar
Radford Neal committed
176
  a problem in the POSIX/C99 standard with \code{"1969-12-31 23:59:59 UTC"},
Radford Neal's avatar
Radford Neal committed
177 178
  which is \code{-1} in calendar time and that value is on those OSes
  also used as an error code.  Thus \code{as.POSIXct("1969-12-31
Radford Neal's avatar
Radford Neal committed
179
  23:59:59", format = "\%Y-\%m-\%d \%H:\%M:\%S", tz = "UTC")} may give
Radford Neal's avatar
Radford Neal committed
180
  \code{NA}, and hence \code{as.POSIXct("1969-12-31 23:59:59",
Radford Neal's avatar
Radford Neal committed
181
  tz = "UTC")} will give \code{"1969-12-31 23:59:00"}.  Other OSes
Radford Neal's avatar
Radford Neal committed
182 183
  (including the code used by \R on Windows) report errors separately
  and so are able to handle that time as valid.
Radford Neal's avatar
Radford Neal committed
184 185
  
  The print methods respect \code{\link{options}("max.print")}.
Radford Neal's avatar
Radford Neal committed
186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
}
\section{Sub-second Accuracy}{
  Classes \code{"POSIXct"} and  \code{"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
  \code{\link{options}("digits.secs")} is set: see \code{\link{strftime}}.
}
\seealso{
  \link{Dates} for dates without times.

  \code{\link{as.POSIXct}} and \code{\link{as.POSIXlt}} for conversion
  between the classes.

  \code{\link{strptime}} for conversion to and from character
  representations.

  \code{\link{Sys.time}} for clock time as a \code{"POSIXct"} object.

  \code{\link{difftime}} for time intervals.

  \code{\link{cut.POSIXt}}, \code{\link{seq.POSIXt}},
  \code{\link{round.POSIXt}} and \code{\link{trunc.POSIXt}} for methods
  for these classes.

  \code{\link{weekdays}} for convenience extraction functions.
}
Radford Neal's avatar
Radford Neal committed
214 215 216 217 218
\references{
  Ripley, B. D. and Hornik, K. (2001) Date-time classes. \emph{R News},
  \bold{1/2}, 8--11.
  \url{http://www.r-project.org/doc/Rnews/Rnews_2001-2.pdf}
}
Radford Neal's avatar
Radford Neal committed
219
\section{Warning}{
Radford Neal's avatar
Radford Neal committed
220 221
  Some Unix-like systems (especially Linux ones) do not have environment
  variable \env{TZ}
Radford Neal's avatar
Radford Neal committed
222 223
  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
Radford Neal's avatar
Radford Neal committed
224
  setting \env{TZ}.  See \code{\link{Sys.timezone}} for valid settings.
Radford Neal's avatar
Radford Neal committed
225
}
Radford Neal's avatar
Radford Neal committed
226
\examples{\donttest{% <-->  may fail on platforms wrongly set up
Radford Neal's avatar
Radford Neal committed
227 228 229 230 231
(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
Radford Neal's avatar
Radford Neal committed
232
format(.leap.seconds)         # all 24 leap seconds in your timezone
Radford Neal's avatar
Radford Neal committed
233
print(.leap.seconds, tz="PST8PDT")  # and in Seattle's
Radford Neal's avatar
Radford Neal committed
234 235 236 237 238 239

## look at *internal* representation of "POSIXlt" :
leapS <- as.POSIXlt(.leap.seconds)
names(leapS) ; is.list(leapS)
utils::str(unclass(leapS), vec.len = 7)
}}
Radford Neal's avatar
Radford Neal committed
240 241
\keyword{utilities}
\keyword{chron}