timeSpan-class
Time Span Class
Description
The timeSpan class represents time spans.
Details
The timeSpan class is constructed 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 user can directly change the format specified by the format
slot (see below), but it is not recommended to change
the groupVec slots directly.
Slots
columns
(list) (from groupVec).
names
(character) (from groupVec).
classes
(character) (from groupVec).
format
(character) output format string.
Time span functions
You can create objects of class timeSpan by using either the
new function (in which case they are set up to have length 0 and
the default format from timeDateOptions("tspan.out.format")),
or by using the timeSpan function.
as relationships are established 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. Adding or subtracting numbers to or from
timeSpan objects works as though the timeSpan is
converted to a number, the operation is performed, and the number is
converted back to a timeSpan.
Multiplication and division by numbers are also defined.
You can add, subtract, and divide two timeSpan objects.
(For division, the result is a number.) You can add or subtract
a timeSpan object to or from a timeDate object.
Only a few other mathematical functions make sense for timeSpan objects.
These are floor, ceiling, min, max, sum, mean, and range.
Multiplication, division, and operations that do not
make sense directly for timeSpan objects 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 is 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 is inserted into the time span vector. (To skip characters in a
string, use %c or %w.)
*
anything not in this list matches itself explicitly.
%c
any single character, which is skipped. This can be used with
widths and delimiters such as "%3c" (to skip 3 characters)
and "%\$c" (to skip 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
delimiter specification. For that, use %c).
%W
input number of weeks as integer.
%y
input number of 365-day years as integer.
%(digits)(char)
For 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)
For 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)
For 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 becomes "NA". Note that since time spans can
be positive or negative, you should use care in specifying field widths.
You can use the following format specifications:
*
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
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"