class.time.span: Time Span Class

timeSpan-classR Documentation

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

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

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"

splusTimeDate documentation built on July 7, 2022, 5:05 p.m.