timeSpan
class represents time spans in S.
list
) (from
groupVec
).
character
) (from
groupVec
).
CLASS
) (from
groupVec
).
character
) output format string.
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.
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 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.)
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:
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"