DateTimeClasses {base} | R Documentation |
Description of the classes "POSIXlt"
and "POSIXct"
representing calendar dates and times (to the nearest second).
## S3 method for class 'POSIXct'
print(x, ...)
## S3 method for class 'POSIXct'
summary(object, digits = 15, ...)
time + z
time - z
time1 lop time2
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 |
z |
a numeric vector (in seconds) |
lop |
One of |
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 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.
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.
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
.
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.
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.
(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