Time and Date Class

DESCRIPTION:

The timeDate class represents times and dates in S.

SLOTS:

ARGUMENTS:

.Data
( list) (from groupVec).
.Data.names
( character) (from groupVec).
.Data.classes
( CLASS) (from groupVec).
format
( character) output format string.
time.zone
( character) time zone string.

DETAILS:

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.

TIME FUNCTIONS:

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.

FORMATTING:

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 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 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.

ARGUMENTS:

*
anything not in this list matches itself explicitly
%c
any single character, which is skipped. This is primarily useful for skipping things like days of the week, which if abbreviated could be skipped by "%3c" (see also %w), and for skipping the rest of the string, "%$c"
%d
input day within 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 options("time.month.name") that distinguishes it from the other months will be 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 will cause 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 options("time.am.pm"), defining am and pm, with matching as for months. If pm is given, and hour is before 13, the time is bumped into the afternoon. If am is given, and hour is 12, the time is bumped into the morning. Note that this only modifies previously parsed hours.
%S
input seconds as integer
%w
a whitespace-delimited word, which is skipped (no width or delimeter specification for this -- use %c for that).
%y
input year as integer. If less than 100, options("time.century") is used to determine the actual year.
%Y
input year as integer, without considering the century
%Z
time zone string. Accepts a whitespace delimeted word unless another delimeter 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 delimeter 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, etc.) 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 " will parse "5: 6:45".
[...]
specify optional specification. Text and specifications within the brackets may optionally 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, 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:

ARGUMENTS:

*
anything not in this list matches itself explicitly (including whitespace, unlike in input specs)
%a
abbreviated weekday ("Mon", etc.) from options("time.day.abb").
%A
full weekday ("Monday", etc.) from options("time.day.name")
%b
print month as abbreviation, from options("time.month.abb").
%B
print month as full name, from options("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
hour (24-hour clock) as integer, 0-23
%I
hour (12-hour clock) as integer, 1-12
%m
print month as integer: 1-12
%M
minutes as integer: 0-59
%N
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 will cause printing of 10ths or 100ths of a second instead: 0-999
%p
will insert "am" or "pm", using strings from options("time.am.pm")
%q
quarter of the year, as integer: 1-4
%Q
quarter of the year, as Roman numeral: I-IV
%S
seconds as integer: 0-59 (60 for leap second)
%y
print year as two-digit integer if year is in century specified by options("time.century"), otherwise full year
%Y
print full year as integer (see also %C)
%Z
will insert the time zone string from the objects time.zone slot.
%z
will insert 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 (e.g. if the time zone is "PST/PDT"). If there is no "/" character, the entire time zone will be used for both.
%%
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 be used. 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 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.

SEE ALSO:

class, class, , function, , .

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"