EVOLUTION-MANAGER

Edit File: DateTimeClasses.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Date-Time Classes</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for DateTimeClasses {base}"><tr><td>DateTimeClasses {base}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>Date-Time Classes</h2>

<h3>Description</h3>

Description of the classes <code>"POSIXlt"</code> and <code>"POSIXct"</code>
representing calendar dates and times.

<h3>Usage</h3>

<pre>
## S3 method for class 'POSIXct'
print(x, tz = "", usetz = TRUE, max = NULL, ...)

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

time + z
z + time
time - z
time1 lop time2
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>x, object</code></td>
<td>
an object to be printed or summarized from one of the
date-time classes.
</td></tr>
<tr valign="top"><td><code>tz, usetz</code></td>
<td>
for timezone formatting, passed to <code><a href="strptime.html">format.POSIXct</a></code>.
</td></tr>
<tr valign="top"><td><code>max</code></td>
<td>
numeric or <code>NULL</code>, specifying the maximal number of
entries to be printed. By default, when <code>NULL</code>,
<code><a href="options.html">getOption</a>("max.print")</code> used.
</td></tr>
<tr valign="top"><td><code>digits</code></td>
<td>
number of significant digits for the computations:
should be high enough to represent the least important time unit
exactly.
</td></tr>
<tr valign="top"><td><code>...</code></td>
<td>
further arguments to be passed from or to other methods.
</td></tr>
<tr valign="top"><td><code>time</code></td>
<td>
date-time objects
</td></tr>
<tr valign="top"><td><code>time1, time2</code></td>
<td>
date-time objects or character vectors. (Character
vectors are converted by <code><a href="as.POSIXlt.html">as.POSIXct</a></code>.)
</td></tr>
<tr valign="top"><td><code>z</code></td>
<td>
a numeric vector (in seconds)
</td></tr>
<tr valign="top"><td><code>lop</code></td>
<td>
one of <code>==</code>, <code>!=</code>, <code>&lt;</code>, <code>&lt;=</code>, <code>&gt;</code>
or <code>&gt;=</code>.
</td></tr>
</table>

<h3>Details</h3>

There are two basic classes of date/times. Class <code>"POSIXct"</code>
represents the (signed) number of seconds since the beginning of 1970
(in the UTC time zone) as a numeric vector. Class <code>"POSIXlt"</code> is
a named list of vectors representing

<dl>
<dt><code>sec</code></dt><dd>0&ndash;61: seconds.
</dd>
<dt><code>min</code></dt><dd>0&ndash;59: minutes.
</dd>
<dt><code>hour</code></dt><dd>0&ndash;23: hours.
</dd>
<dt><code>mday</code></dt><dd>1&ndash;31: day of the month
</dd>
<dt><code>mon</code></dt><dd>0&ndash;11: months after the first of the year.
</dd>
<dt><code>year</code></dt><dd>years since 1900.
</dd>
<dt><code>wday</code></dt><dd>0&ndash;6 day of the week, starting on Sunday.
</dd>
<dt><code>yday</code></dt><dd>0&ndash;365: day of the year.
</dd>
<dt><code>isdst</code></dt><dd>Daylight Saving Time flag. Positive if in
force, zero if not, negative if unknown.
</dd>
<dt><code>zone</code></dt><dd>(Optional.) The abbreviation for the time zone in
force at that time: <code>""</code> if unknown (but <code>""</code> might also
be used for UTC).
</dd>
<dt><code>gmtoff</code></dt><dd>(Optional.) The offset in seconds from GMT:
positive values are East of the meridian. Usually <code>NA</code> if
unknown, but <code>0</code> could mean unknown.
</dd>
</dl>

(The last two components are not present for times in UTC and are
platform-dependent: they are supported on platforms based on BSD or
<code>glibc</code> (including Linux and macOS) and those using the
<code>tzcode</code> implementation shipped with R (including Windows). But
they are not necessarily set.). Note that the internal list structure
is somewhat hidden, as many methods (including
<code><a href="length.html">length</a>(x)</code>, <code><a href="print.html">print</a>()</code> and <code><a href="../../utils/html/str.html">str</a></code>)
apply to the abstract date-time vector, as for <code>"POSIXct"</code>. As
from R 3.5.0, one can extract and replace single components
via <code>[</code> indexing with two indices (see the examples). The
classes correspond to the POSIX/C99 constructs of &lsquo;calendar
time&rsquo; (the <code>time_t</code> data type) and &lsquo;local time&rsquo; (or
broken-down time, the <code>struct tm</code> data type), from which they
also inherit their names. The components of <code>"POSIXlt"</code> are
integer vectors, except <code>sec</code> and <code>zone</code>.

<code>"POSIXct"</code> is more convenient for including in data frames, and
<code>"POSIXlt"</code> is closer to human-readable forms. A virtual class
<code>"POSIXt"</code> exists from which both of the classes inherit: it is
used to allow operations such as subtraction to mix the two classes.

Components <code>wday</code> and <code>yday</code> of <code>"POSIXlt"</code> are for
information, and are not used in the conversion to calendar time.
However, <code>isdst</code> 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</code> can be deduced from
the first six values, but the behaviour if it is set incorrectly is
platform-dependent.

Logical comparisons and some arithmetic operations 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><a href="difftime.html">difftime</a></code>.
Be aware that <code>"POSIXlt"</code> objects will be interpreted as being in
the current time zone for these operations unless a time zone has been
specified.

<code>"POSIXlt"</code> objects will often have an attribute <code>"tzone"</code>,
a character vector of length 3 giving the time zone name from the
TZ environment variable and the names of the base time zone
and the alternate (daylight-saving) time zone. Sometimes this may
just be of length one, giving the <a href="timezones.html">time zone</a> name.

<code>"POSIXct"</code> objects may also have an attribute <code>"tzone"</code>, 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"</code> and in
particular how it is printed. This is usually desirable, but if you
want to specify an object in a particular time zone but to be printed
in the current time zone you may want to remove the <code>"tzone"</code>
attribute (e.g., by <code>c(x)</code>).

Unfortunately, the conversion is complicated by the operation of time
zones and leap seconds (according to this version of R's data,
27 days have been 86401 seconds long so
far, the last being on (actually, immediately before)
2017-01-01: the times of the
extra seconds are in the object <code>.leap.seconds</code>). The details of
this are entrusted to the OS services where possible. It seems that
some rare systems used to use leap seconds, but all known current
platforms ignore them (as required by POSIX). This is detected and
corrected for at build time, so <code>"POSIXct"</code> times used by R do
not include leap seconds on any platform.

Using <code><a href="c.html">c</a></code> on <code>"POSIXlt"</code> objects converts them to the
current time zone, and on <code>"POSIXct"</code> objects drops any
<code>"tzone"</code> attributes (even if they are all marked with the same
time zone).

A few times have specific issues. First, the leap seconds are ignored,
and real times such as <code>"2005-12-31 23:59:60"</code> 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 <code>"1969-12-31 23:59:59 UTC"</code>,
which is <code>-1</code> in calendar time and that value is on those OSes
also used as an error code. Thus <code>as.POSIXct("1969-12-31
 23:59:59", format = "%Y-%m-%d %H:%M:%S", tz = "UTC")</code> may give
<code>NA</code>, and hence <code>as.POSIXct("1969-12-31 23:59:59",
 tz = "UTC")</code> will give <code>"1969-12-31 23:59:00"</code>. Other OSes
(including the code used by R on Windows) report errors separately
and so are able to handle that time as valid.

The print methods respect <code><a href="options.html">options</a>("max.print")</code>.

<h3>Sub-second Accuracy</h3>

Classes <code>"POSIXct"</code> and <code>"POSIXlt"</code> 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><a href="options.html">options</a>("digits.secs")</code> is set: see <code><a href="strptime.html">strftime</a></code>.

<h3>Valid ranges for times</h3>

The <code>"POSIXlt"</code> class can represent a very wide range of times (up
to billions of years), but such times can only be interpreted with
reference to a time zone.

The concept of time zones was first adopted in the nineteenth century,
and the Gregorian calendar was introduced in 1582 but not universally
adopted until 1927. OS services almost invariably assume the
Gregorian calendar and may assume that the time zone that was first
enacted for the location was in force before that date. (The earliest
legislated time zone seems to have been London on 1847-12-01.) Some
OSes assume the previous use of &lsquo;local time&rsquo; based on the
longitude of a location within the time zone.

Most operating systems represent <code>POSIXct</code> times as C type
<code>long</code>. This means that on 32-bit OSes this covers the period
1902 to 2037. On all known 64-bit platforms and for the code we use
on 32-bit Windows, the range of representable times is billions of
years: however, not all can convert correctly times before 1902 or
after 2037. A few benighted OSes used a unsigned type and so cannot
represent times before 1970.

Where possible the platform limits are detected, and outside
the 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) time zone only
if <code>isdst</code> is positive or (if <code>-1</code>) if DST was predicted to
be in operation in the 2030s on that day.

Note that there are places (e.g., Rome) whose offset from UTC varied
in the years prior to 1902, and these will be handled correctly only
where there is OS support.

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. So conversions
for times more than a year or two ahead are speculative.

<h3>Warnings</h3>

Some Unix-like systems (especially Linux ones) do not have environment
variable 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 <code><a href="timezones.html">Sys.timezone</a></code> for
valid settings.

Great care is needed when comparing objects of class <code>"POSIXlt"</code>.
Not only are components and attributes optional; several components
may have values meaning &lsquo;not yet determined&rsquo; and the same time
represented in different time zones will look quite different.

Currently the order of the list components of <code>"POSIXlt"</code>
objects must not be changed, as several C-based conversion methods
rely on the order for efficiency.

<h3>References</h3>

Ripley, B. D. and Hornik, K. (2001) Date-time classes. R News,
1/2, 8&ndash;11.
<a href="https://www.r-project.org/doc/Rnews/Rnews_2001-2.pdf">https://www.r-project.org/doc/Rnews/Rnews_2001-2.pdf</a>

<a href="Dates.html">Dates</a> for dates without times.

<code><a href="as.POSIXlt.html">as.POSIXct</a></code> and <code><a href="as.POSIXlt.html">as.POSIXlt</a></code> for conversion
between the classes.

<code><a href="strptime.html">strptime</a></code> for conversion to and from character
representations.

<code><a href="Sys.time.html">Sys.time</a></code> for clock time as a <code>"POSIXct"</code> object.

<code><a href="difftime.html">difftime</a></code> for time intervals.

<code><a href="cut.POSIXt.html">cut.POSIXt</a></code>, <code><a href="seq.POSIXt.html">seq.POSIXt</a></code>,
<code><a href="round.POSIXt.html">round.POSIXt</a></code> and <code><a href="round.POSIXt.html">trunc.POSIXt</a></code> for methods
for these classes.

<code><a href="weekday.POSIXt.html">weekdays</a></code> for convenience extraction functions.

<h3>Examples</h3>

<pre>
(z &lt;- 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)         # the leap seconds in your time zone
print(.leap.seconds, tz = "PST8PDT")  # and in Seattle's

## look at *internal* representation of "POSIXlt" :
leapS &lt;- as.POSIXlt(.leap.seconds)
names(leapS) ; is.list(leapS)
## str() "too smart" --&gt;  need unclass(.):
utils::str(unclass(leapS), vec.len = 7)
## Extracting *single* components of POSIXlt objects:
leapS[1 : 5, "year"]

## length(.) &lt;- n now works for "POSIXct" and "POSIXlt" :
for(lpS in list(.leap.seconds, leapS)) {
 ls &lt;- lpS; length(ls) &lt;- 12
 l2 &lt;- lpS; length(l2) &lt;- 5 + length(lpS)
 stopifnot(exprs = {
 ## length(.) &lt;- * is compatible to subsetting/indexing:
 identical(ls, lpS[seq_along(ls)])
 identical(l2, lpS[seq_along(l2)])
 ## has filled with NA's
 is.na(l2[(length(lpS)+1):length(l2)])
 })
}
</pre>

<hr /><div style="text-align: center;">[Package base version 3.6.0 <a href="00Index.html">Index</a>]</div>
</body></html>