timeDate
class represents times and dates in S.
list
) (from
groupVec
).
character
) (from
groupVec
).
CLASS
) (from
groupVec
).
character
) output format string.
character
) time zone string.
The
timeDate
class is set up to hold a vector of times and/or dates.
It extends the
groupVec
and
groupVecVirtual
classes, as well as the
positionsCalendar
class (see documentation on the
positions
class).
The groupVec portion of a time object holds a
date portion, stored as a vector of the days since January 1, 1960, and a
time portion, stored as a vector of the number of milliseconds since
midnight, GMT. The
groupVec
column names are
"julian.day"
and
"milliseconds"
,
and the column classes are
integer
.
The
format
slot holds an
output format string (see below); the
time.zone
slot holds the time zone string. The time zone string
must be one of the names from the time zone list (see
timeZoneList
documentation). Since times are stored
internally always in GMT, the time zone string is used for
printing and for converting to calendar times and dates
(month/day/year, hour/minute/second/millisecond), and can be changed
by the user directly. The format can also be changed by the user
directly, but it is not recommended to change the groupVec slots directly.
Objects of class time can be created using the
new
function, in
which case they are set up to have length 0 and the default format and
zone from
options("time.out.format")
and
options("time.zone")
respectively. Alternatively, they can be created using the
timeDate
and
timeCalendar
functions.
There are
as
relationships set up for
timeDate
objects to coerce them to
and from
character
,
numeric
, and
integer
. For numbers, the
integer part is the julian day, and the fractional part is the
fraction of the day given by the number of milliseconds divided by the
number of milliseconds in a day, in GMT. Addition of numbers to
time objects and subtraction of numerics from time objects works as
though the time were converted to a number, the operation was
performed, and the number was converted back to a
time. Their subtraction results in a
timeSpan
object, and a
timeSpan
object can be added to or subtracted from a time.
Only a few other mathematical functions make sense for time objects:
floor
,
ceiling
,
min
,
max
,
mean
, and
range
.
Multiplication, division, and other operations that do not
make sense for times and dates (in the absence of an origin) result in
numbers, via automatic coercion to class numeric.
Note that while conversion
to/from numerics is always in GMT,
floor
and
ceiling
take account of
the time zone to ouput time objects whose time is midnight in their
time zone, and whose date is no later than the input time's date for
floor
, and no earlier for
ceiling
. In addition to these mathematical
operations, all of the standard comparison operators have methods for
comparing two time objects.
There are also functions for time objects that pick out particular
parts. See
days
,
hours
, and
mdy
for more information.
Various options are used by the time class, primarily for printing to and
reading from character strings. See
options
for documentation.
The old-style date and time format specifiers used in the
dates
,
times
, and
chron
functions, e.g. "mdy", "m/d/y", "h:m:s", were
quite inflexible, and did not allow combining dates and times in a
single string. Because of that, we have designed a new
set of input and output format specifications, which will
look familiar to c and unix programmers and are patterned on the
strptime function under Solaris. For backwards compatibility,
we are still supporting the old-style format strings, and to
tell whether a given string is old or new style, we simply check
for the presence of a "%" character (not a
legal character in an old-style date or time format string).
Users are encouraged to use the new format
styles, as the old ones will eventually be deprecated.
Input format strings are used to convert character strings to time objects.
When reading time objects, the default of January 1, 1960, Midnight GMT
is supplied, and the input format specifications below can be used
to override this default time. They will be read in from left to right.
If the entire input string is not matched by the format string, or if
the resulting time or date is not valid, an NA will be put into the time
vector. (To skip characters in a string, use %c or %w.)
One thing to note is that if you are reading a time zone from your
character string, the notation used for the time zone in your character
string must be one of the components of the time zone list. See
documentation for
timeZoneList
for more information.
timeZoneList()
.
Output formats are used to convert time objects to character strings, and are stored in the format slot of the time object. During output, if a given field width is too short to hold the output, if that output field is a character field, the leftmost characters will be printed, but if it is a numeric field, the output string will become "NA". The following format specifications can be used:
time.zone
slot.
time.zone
slot,
using the part before the first
"/"
character if it is standard
time, and the part after the first
"/"
character if it is daylight
savings time (e.g. if the time zone is
"PST/PDT"
). If there is no
"/"
character, the entire time zone will be used for both.
The calendar follows the conventions of the British Empire, which changed from Julian to Gregorian calendars in September of 1752. Calendar dates prior to 1920 were different in many countries. See the "Calendar FAQ" posted regularly to Usenet news groups soc.history, sci.astro, sci.answers, soc.answers, and news.answers, and to a web site at http://www.pip.dknet.dk/~c-t/calendar.html for more information on the history of calendars around the world. The time objects allow days with leap seconds, but calculated times of day for days containing leap seconds may be off by a second -- they will be treated as though the leap second occurred at the very end of the day, since there is currenly no provision in S for keeping track of leap seconds.
The default format for input is initially: "%m[/][.]%d[/][,]%y [%H[:%M[:%S[.%N]]][%p][[(]%3Z[)]]]" This allows reading strings such as "Jan 22 1997", "January 22, 1997", "1/22/97", "1/22/97 2PM" The default format for output is initially: "%02m/%02d/%Y %02H:%02M:%02S.%03N" Another choice would be "%A %B %d, %Y %I:%02M %p" These would result in the following output: "01/22/1997 14:34:45.025" and "Thursday January 22, 1997 2:34 PM"