The
timeRelative class represents relative times in S-PLUS.
SLOTS:
ARGUMENTS:
.Data
(
character) string vector representing the relative time.
holidays
(
positionsCalendar) vector of holiday dates.
DETAILS:
The
timeRelative class stores a representation of relative
times in S-PLUS. Unlike
timeSpan, which stores absolute
time differences, the
timeRelative class stores relative times
in units such as weekdays, months, and business days, whose
absolute time value depends on what
timeDate object they are
combined with. Both
timeRelative and
timeSpan extend the
virtual
timeInterval class.
The
.Data slot in a
timeRelative object holds a character
vector that represents the relative time. Each element of the
vector is a character string consisting of whitespace-separated
fields in the form
"[+-][a]#abb", with a required sign,
either
"+" or
"-"; followed by an optional
"a" that, if present,
means to align the result (see below); followed by a positive integer
(it is also possible to specify 0 if aligning)
and one of the relative time field abbreviations from this list:
ARGUMENTS:
ms
add/subtract milliseconds; a aligns to nearest # milliseconds within
the second, where # must be a divisor of 1000 and less than 1000
(e.g. 500 aligns to even seconds or 1/2 seconds); 0 is not allowed.
sec
add/subtract seconds; a aligns to nearest # seconds within
the minute, where # must be a divisor of 60 and less than 60
(e.g. 15 aligns to 0, 15, 30, or 45 seconds past the minute);
0 goes to the beginning of the current second, independent of sign.
min
add/subtract minutes; a aligns to nearest # minutes within
the hour, where # must be a divisor of 60 and less than 60
(e.g. 15 aligns to 0, 15, 30, or 45 minutes after the hour);
0 goes to the beginning of the current minute, independent of sign.
hr
add/subtract hours; a aligns to nearest # hours within
the day, where # must be a divisor of 24 and less than 24
(e.g. 6 aligns to midnight, 6AM, noon, or 6PM);
0 goes to the beginning of the current hour, independent of sign.
day
add/subtract days; a aligns to nearest # days within
the month, starting with the first, where # must be a less than the
number of days in the month (e.g. 2 aligns to the 1st, 3rd, 5th, etc,
with the time midnight);
0 goes to the beginning of the current day, independent of sign.
wkd
add/subtract weekdays; a causes the first added or subtracted
weekday to possibly be a fraction of a day to move to the next
or previous midnight on a weekday morning, and then whole
additional days are added or subtracted to make up # weekdays;
0 goes to the beginning of the day, or the closest weekday before
if it is not a weekday, independent of sign.
biz
add/subtract business days (weekdays that are not holidays);
a causes the first added or subtracted
business day to possibly be a fraction of a day to move the next or previous
midnight on a business day morning, and then whole
additional days are added or subtracted to make up # business days;
0 goes to the beginning of the day, or the closest business day before
if it is not a business day, independent of sign.
sun
add/subtract Sundays; a causes the first added or subtracted
Sunday to possibly be a fraction of a day or week
to move the next or previous
midnight on a Sunday morning, and then whole additional
weeks are added or subtracted to make up # Sundays;
0 goes to the beginning of the day, or the closest Sunday
before if it is not the right day, independent of sign.
mon
add/subtract Mondays; a causes the first added or subtracted
Monday to possibly be a fraction of a day or week
to move the next or previous
midnight on a Monday morning, and then whole additional
weeks are added or subtracted to make up # Mondays;
0 goes to the beginning of the day, or the closest Monday
before if it is not the right day, independent of sign.
tue
add/subtract Tuesdays; a causes the first added or subtracted
Tuesday to possibly be a fraction of a day or week
to move the next or previous
midnight on a Tuesday morning, and then whole additional
weeks are added or subtracted to make up # Tuesdays;
0 goes to the beginning of the day, or the closest Tuesday
before if it is not the right day, independent of sign.
wed
add/subtract Wednesdays; a causes the first added or subtracted
Wednesday to possibly be a fraction of a day or week
to move the next or previous
midnight on a Wednesday morning, and then whole additional
weeks are added or subtracted to make up # Wednesdays;
0 goes to the beginning of the day, or the closest Wednesday
before if it is not the right day, independent of sign.
thu
add/subtract Thursdays; a causes the first added or subtracted
Thursday to possibly be a fraction of a day or week
to move the next or previous
midnight on a Thursday morning, and then whole
additional weeks are added or subtracted to make up # Thursdays;
0 goes to the beginning of the day, or the closest Thursday
before if it is not the right day, independent of sign.
fri
add/subtract Fridays; a causes the first added or subtracted
Friday to possibly be a fraction of a day or week
to move the next or previous
midnight on a Friday morning, and then whole
additional weeks are added or subtracted to make up # Fridays;
0 goes to the beginning of the day, or the closest Friday
before if it is not the right day, independent of sign.
sat
add/subtract Saturdays; a causes the first added or subtracted
Saturday to possibly be a fraction of a day or week
to move the next or previous
midnight on a Saturday morning, and then whole
additional weeks are added or subtracted to make up # Saturdays;
0 goes to the beginning of the day, or the closest Saturday
before if it is not the right day, independent of sign.
wk
add/subtract weeks; a is not allowed.
tdy
add/subtract "ten-day" periods of months (ten-day periods
begin on the first, 11th, and 21st of the month but not the 31st).
Without a, the day number of the result will be 1, 11, or 21, adding
# partial or entire ten-day periods to grt there.
If a is used, # must be either 1, 2, or 3, and the time will be midnight;
0 goes to the beginning of the current ten-day period, independent of sign.
mth
add/subtract months; a aligns to nearest # months within
the year, starting with January, and # must be a divisor of 12 and
less than 12 (e.g. 3 aligns to Jan 1, Apr 1, Jul 1, Oct 1 at midnight);
0 goes to the beginning of the current month, independent of sign.
qtr
add/subtract quarters; a aligns to nearest # quarters within
the year, and # must be either 1 or 2
(e.g. 2 aligns to Jan 1 or Jul 1 at midnight);
0 goes to the beginning of the current quarter, independent of sign.
yr
add/subtract years; a aligns to nearest # years
(e.g. 5 aligns to Jan 1 at midnight in 1995, 2000, 2005, etc.)
0 goes to the beginning of the current year, independent of sign.
When relative time objects are added to time/date objects,
the fields from an element of the relative time object
are parsed and added to the corresponding element of the
time/date object from left
to right (if either the time/date object or the relative time object
is shorter than the other, it is reused cyclically in the standard
S-PLUS manner). A short example will illustrate how it works.
Let's say we have a date/time of May 10, 1998 4:32 PM (a Sunday),
and the relative time element is
"+a3hr +12hr -1day". The first field
of the relative time says to add up to three hours to align to the
nearest three-hour boundary. This will advance the time to 6:00 PM.
The second field says to add twelve hours, which will advance the time
to 6:00 AM on May 11. The third field subtracts a whole day, which
leaves us at 6:00 AM on May 10.
Relative time objects can be added to and subtracted from
time/date objects, and they can also be added and subtracted from
each other and multiplied by integers. When they are negated,
the sign of each field is reversed; when they are added together,
they are concatenated, so that if
x is a time/date object and
y and
z are relative time objects,
(x + y) + z == x + (y + z);
however
y + z is not the same as
z + y.
NOTES:
(1) All alignment and other operations are done in the local time
zone of the time/date object. (2) The
holidays slot of the
relative time object is used to define which dates besides weekends
are not business
days; these dates are taken in the
holidays slots time
zone. (3) When adding units of time without the
"a" flag in the field,
the smaller units of time are not changed; for example, when adding
days, the time of day stays the same, and when adding months, the day of
the month and the time of day stay the same.