Time Span Class

DESCRIPTION:

The timeSpan class represents time spans in S.

SLOTS:

ARGUMENTS:

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

DETAILS:

The timeSpan class is set up to hold a vector of time spans. It extends the groupVec and groupVecVirtual classes, as well as timeInterval. The groupVec portion of the time class object holds a day portion, stored as an integer vector of the number of full days in each time span, and a time portion, stored as a vector of the number of milliseconds in each time span. 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 format can be changed by the user directly, but it is not recommended to change the groupVec slots directly.

TIME SPAN FUNCTIONS:

Objects of class timeSpan can be created using the new function, in which case they are set up to have length 0 and the default format from options("tspan.out.format"). Alternatively, they can be created using the timeSpan function. There are as relationships set up for timeSpan objects to coerce them to and from character, numeric, and integer. For numbers, the integer part is the number of days, 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. Addition of numbers to timeSpan objects and subtraction of numbers from timeSpan objects works as though the timeSpan were converted to a number, the operation was performed, and the number was converted back to a timeSpan. Multiplication and division by numbers are also defined. Two timeSpan objects can be added, subtracted, and divided (for division the result is a number), and a timeSpan object can be added to or subtracted from a timeDate object. Only a few other mathematical functions make sense for timeSpan objects: floor , ceiling, min, max, sum, mean, and range. Multiplication, division, and operations that do not make sense directly for timeSpans result in numbers, via automatic coercion to class numeric. In addition to these mathematical operations, all of the standard comparison operators have methods for comparing two timeSpan objects.

INPUT FORMATS:

Input format strings are used in the conversion of character strings to timeSpan objects. They are read in from left to right, and each format specification encountered will be parsed, and the resulting amount of time added to the time span. If the entire input string is not matched by the format string, an NA will be put into the time span vector. (To skip characters in a string, use %c or %w.)

ARGUMENTS:

*
anything not in this list matches itself explicitly
%c
any single character, which is skipped, can be used with widths and delimeters such as "%3c" to skip 3 characters, and "%$c" for skipping the rest of the string.
%d
input number of days as integer
%H
input number of hours as integer
%M
input number of minutes as integer
%N
input number of milliseconds as integer
%S
input number of seconds as integer
%w
a whitespace-delimited word, which is skipped (no width or delimeter specification for this -- use %c for that).
%W
input number of weeks, as integer
%y
input number of 365-day years as integer.
%(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 timeSpan objects to character strings, and are stored in the format slot of the object. During output, if a given field width is too short to hold the output, the output string will become "NA". Note that since time spans can be positive or negative, you should use care in specifying field widths. The following format specifications can be used:

ARGUMENTS:

*
anything not in this list matches itself explicitly (including whitespace, unlike in input formats)
%d
total number of days in span as integer
%D
number of days subtracting off full 365-day years as integer: 1-364
%E
number of days subtracting off 7-day weeks as integer: 1-6
%H
number of hours subtracting off days as integer, 0-23
%M
number of minutes subtracting off hours as integer: 0-59
%N
number of milliseconds in span, subtracting off seconds as integer.
%S
number of seconds subtracting off minutes as integer: 0-59
%s
number of seconds subtracting off days as integer
%W
number of 7-day weeks in time span as integer
%y
number of 365-day years in span as integer
%%
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 the value is too long for the field width, the output string becomes "NA" for that time span.

SEE ALSO:

class, class, , function, .

EXAMPLES:

The default format for input is initially:
   "[%yy[ear[s]][,]] [%dd[ay[s]][,]] [%Hh[our[s]][,]]
      [%Mm[in[ute][s]][,]] [%Ss[ec[ond][s]][,]] [%NM[s][S]]"
This allows reading strings such as
   "378d 21h 04min 36s 365MS", "378 d", "-1y, -13d, -21h -4m"
The default format for output is initially:
   "%dd %Hh %Mm %Ss %NMS"
This results in output such as:
   "378d 21h 4m 36s 365MS"   "-378d -21h -4m -36s -365MS"