splusTimeDate (version 1.5.0-72)

timeDate-class: Time and Date Class

Description

The timeDate class represents times and dates.

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.

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.

See Also

groupVec class, timeSpan class, timeDateOptions, timeDate function, timeCalendar, format.timeDate.

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"