splusTimeDate (version 2.5.0-137)

timeDate-class: Time and Date Class

Description

The timeDate class represents times and dates.

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.

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"