\Header{DateTimeClasses}{Date-Time Classes}
\alias{+.POSIXt}{DateTimeClasses}
\alias{-.POSIXt}{DateTimeClasses}
\alias{.leap.seconds}{DateTimeClasses}
\alias{all.equal.POSIXct}{DateTimeClasses}
\alias{as.data.frame.POSIXct}{DateTimeClasses}
\alias{as.data.frame.POSIXlt}{DateTimeClasses}
\alias{as.matrix.POSIXlt}{DateTimeClasses}
\alias{c.POSIXct}{DateTimeClasses}
\alias{c.POSIXlt}{DateTimeClasses}
\alias{is.na.POSIXlt}{DateTimeClasses}
\alias{Math.POSIXlt}{DateTimeClasses}
\alias{Math.POSIXt}{DateTimeClasses}
\alias{mean.POSIXct}{DateTimeClasses}
\alias{mean.POSIXlt}{DateTimeClasses}
\alias{Ops.POSIXt}{DateTimeClasses}
\alias{POSIXct}{DateTimeClasses}
\alias{POSIXlt}{DateTimeClasses}
\alias{POSIXt}{DateTimeClasses}
\alias{print.POSIXct}{DateTimeClasses}
\alias{print.POSIXlt}{DateTimeClasses}
\alias{str.POSIXt}{DateTimeClasses}
\alias{Summary.POSIXct}{DateTimeClasses}
\alias{summary.POSIXct}{DateTimeClasses}
\alias{Summary.POSIXlt}{DateTimeClasses}
\alias{summary.POSIXlt}{DateTimeClasses}
\alias{[.POSIXct}{DateTimeClasses}
\alias{[.POSIXlt}{DateTimeClasses}
\alias{[<\Rdash.POSIXct}{DateTimeClasses}
\alias{[<\Rdash.POSIXlt}{DateTimeClasses}
\alias{[[.POSIXct}{DateTimeClasses}
\keyword{utilities}{DateTimeClasses}
\keyword{chron}{DateTimeClasses}
\begin{Description}\relax
Description of the classes \code{"POSIXlt"} and \code{"POSIXct"}
representing calendar dates and times (to the nearest second).
\end{Description}
\begin{Usage}
\begin{verbatim}
## S3 method for class 'POSIXct':
print(x, ...)

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

time + number
time - number
time1 lop time2
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x, object}] An object to be printed or summarized from one of the
date-time classes.
\item[\code{digits}] Number of significant digits for the computations:
should be high enough to represent the least important time unit
exactly.
\item[\code{...}] Further arguments to be passed from or to other methods.
\item[\code{time, time1, time2}] date-time objects.
\item[\code{number}] a numeric object.
\item[\code{lop}] One of \code{==}, \code{!=}, \code{<}, \code{<=}, \code{>}
or \code{>=}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
There are two basic classes of date/times.  Class \code{"POSIXct"}
represents the (signed) number of seconds since the beginning of 1970
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.
}
The classes correspond to the ANSI C constructs of \dQuote{calendar
time} (the \code{time\_t} data type) and \dQuote{local time} (or
broken-down time, the \code{struct tm} data type), from which they
also inherit their names.

\code{"POSIXct"} is more convenient for including in data frames, and
\code{"POSIXlt"} is closer to human-readable forms.
A virtual class \code{"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
\code{\Link{difftime}} object 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, 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 (22 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 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 \code{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 \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.)

Using \code{\Link{c}} on \code{"POSIXlt"} objects converts them to the
current time zone.
\end{Details}
\begin{Section}{Warning}
Some Unix-like systems (especially Linux ones) do not have \code{"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 \code{"TZ"}.
\end{Section}
\begin{SeeAlso}\relax
\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.POSIXt}} for convenience extraction functions.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
(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
print(.leap.seconds, tz="PST8PDT")  # and in Seattle's
\end{ExampleCode}
\end{Examples}

