timeDate-class
Time and Date Class
Description
The timeDate class represents times and dates.
Details
This class holds a vector of times and/or dates.
It extends the groupVec class, as well as the
positionsCalendar class (see the documentation for 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 string in the time.zome slot must be one of the names
from the time zone list (see the timeZoneList
documentation). Because 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). You can change these directly.
You can also change the format directly, but we do not recommend changing the
groupVec slots directly.
Slots
columns
(list) (from groupVec).
names
(character) (from groupVec).
classes
(character) (from groupVec).
format
(character) output format string.
time.zone
(character) time zone string.
Time functions
Objects of class.time can be created using the new function, in
which case they are constructed to have length 0 and the default format and
zone from timeDateOptions("time.out.format") and timeDateOptions("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 were
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 timeDateOptions for documentation.
Formatting
The input and output format specifications look familiar to C and IMOX
programmers and are patterned on the
strptime function under Solaris.
Input formats
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 are 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 is inserted into the time
vector. (To skip characters in a string, use %c or %w.)
NOTE: 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.
*
anything not in this list matches itself explicitly.
%c
any single character, which is skipped. This is useful for skipping entries like days of the week, which, if
abbreviated, could be skipped by "%3c" (see also %w). To skip the rest of the string, use "%\$c".
%d
input day, within a month, as integer.
%H
input hour as integer.
%m
input month as integer or as alpha string. If an alpha
string, case does not matter, and any substring of a month in
timeDateOptions("time.month.name") that distinguishes it from the other
months is accepted.
%M
input minute as integer.
%n
input milliseconds as integer, without considering field width as in %N.
%N
input milliseconds as integer. A field width (either given
explicitly or inferred from input string) of 1 or 2 causes input
of 10ths or 100ths of a second instead, as if the digits were
following a period. Field widths greater than 3 are likely to
result in illegal input.
%p
accepts strings from timeDateOptions("time.am.pm"), defining am and pm, with
matching as for months. If pm is given, and the hour is before 13, the time is
bumped into the afternoon. If am is given, and the hour is 12, the time
is bumped into the morning. Note that this modifies previously-parsed hours only.
%S
input seconds as integer.
%w
a whitespace-delimited word, which is skipped (no width or
delimiter specification. For that, use %c).
%y
input year as integer. If less than 100,
timeDateOptions("time.century") is used to determine the actual year.
%Y
input year as integer, without considering the century.
%Z
a time zone string. Accepts a whitespace-delimited word, unless
another delimiter or width is specified. The legal time zones are
the names of timeZoneList().
%(digits)(char)
if there are one or more digits between "%" and the
specification character, these are parsed as an integer, and specify
the field width to be used. The following (digits) characters are
scanned for the specified item.
%:(delim)(char)
if there is a colon and any single character
between a "%" and the specification character, the field is taken to
be all the characters up to but not including the given delimiter
character. The delimiter itself is not scanned or skipped by the
format.
%$(char)
If there is a \$ between a % and a specification character,
the field goes to the end of the input string.
whitespace
whitespace (spaces, tabs, carriage returns, and so on) is ignored in
the input format string. In the string being
parsed, any amount of white space can appear between elements of the
date/time. Thus, the parse format string " %H:%M: %S " parses "5: 6:45".
[...]
specify optional specification. Text and specifications
within the brackets optionally can be included. This does not
support fancy backtracking between multiple optional specs.
%%,%[,%]
the %, [, and ] characters, which must be matched in
the input string.
Output formats
Output formats are used to convert time objects to character strings.
They 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 are
printed, but if it is a numeric field, the output string becomes "NA".
The following format specifications can be used:
*
anything not in this list matches itself explicitly (including
whitespace, unlike in input specs).
%a
print abbreviated weekday ("Mon", and so on) from timeDateOptions("time.day.abb").
%A
print full weekday ("Monday", and so on) from timeDateOptions("time.day.name").
%b
print month as abbreviation, from timeDateOptions("time.month.abb").
%B
print month as full name, from timeDateOptions("time.month.name").
%C
print year within century as integer: 0-99.
%d
print day within month as integer: 1-31.
%D
print day within year as integer: 1-366.
%H
print hour (24-hour clock) as integer, 0-23.
%I
print hour (12-hour clock) as integer, 1-12.
%m
print month as integer: 1-12.
%M
print minutes as integer: 0-59.
%N
print milliseconds as integer. It is a good idea to pad with zeros if this is
after a decimal point! A width of less than 3 causes printing
of 10ths or 100ths of a second instead: 0-999.
%p
print "am" or "pm", using strings from timeDateOptions("time.am.pm").
%q
print quarter of the year, as integer: 1-4.
%Q
print quarter of the year, as Roman numeral: I-IV.
%S
print seconds as integer: 0-59 (60 for leap second).
%y
print year as two-digit integer if year is in century specified
by timeDateOptions("time.century"), otherwise full year.
%Y
print full year as integer (see also %C).
%Z
print the time zone string from the objects time.zone slot.
%z
print the time zone string from the objects 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 (that is, if the time zone is "PST/PDT"). If there is no
"/" character, the entire time zone is used for both.
%%
print the % character
%(digits)(char)
if there are one or more digits between "%" and the
specification character, these are parsed as an integer, and specify
the field width to use. The value is printed, right justified
using (digits) characters. If (digits) begins with zero, the field
is left-padded with zeros if it is a numeric field, otherwise it is
left-padded with spaces. If a numeric value is too long for the field
width, the field is replaced with asterix "*" characters to indicate
overflow; character strings can be abbreviated by specifying short fields.
Note
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 might be off by a second; they
are treated as though the leap second occurred at the very end of the day,
because there is currenly no provision in the splusTimeDate package
for keeping track of leap seconds.
See Also
Examples
## 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"