The timeRelative class represents relative times.
(character) a string vector representing the relative time.
(positionsCalendar) a vector of holiday dates.
All alignment and other operations are done in the local time zone of the time/date object.
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.
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.
The timeRelative class stores a representation of relative
times. 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 the timeDate object with which they are
combined.
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 following form:
"[+-][a]#abb" |
This vector is composed of a required sign (either "+" or "-"),
followed by an optional "a" that, if present, means to align the result
(see below; it is also possible to specify 0 if aligning),
followed by a positive integer and one of the relative time field abbreviations
from the following list:
add/subtract milliseconds. "a" aligns to the nearest # milliseconds within
the second, where # must be a divisor of 1000 and less than 1000
(for example, 500 aligns to even seconds or 1/2 seconds). 0 is not allowed.
add/subtract seconds. "a" aligns to nearest # seconds within
the minute, where # must be a divisor of 60 and less than 60
(for example, 15 aligns to 0, 15, 30, or 45 seconds past the minute).
0 goes to the beginning of the current second, independent of sign.
add/subtract minutes. "a" aligns to nearest # minutes within
the hour, where # must be a divisor of 60 and less than 60
(for example, 15 aligns to 0, 15, 30, or 45 minutes after the hour).
0 goes to the beginning of the current minute, independent of sign.
add/subtract hours. "a" aligns to nearest # hours within
the day, where # must be a divisor of 24 and less than 24
(for example, 6 aligns to midnight, 6AM, noon, or 6PM).
0 goes to the beginning of the current hour, independent of sign.
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 (for example, 2 aligns to the 1st, 3rd, 5th,
and so on, with the time midnight). 0 goes to the beginning of the
current day, independent of sign.
add/subtract weekdays. "a" causes the first added or subtracted
weekday possibly to 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.
add/subtract business days (weekdays that are not holidays).
"a" causes the first added or subtracted
business day possibly to 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.
add/subtract Sundays. "a" causes the first added or subtracted
Sunday possibly to 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.
add/subtract Mondays. "a" causes the first added or subtracted
Monday possibly to 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.
add/subtract Tuesdays. "a" causes the first added or subtracted
Tuesday possibly to 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.
add/subtract Wednesdays. "a" causes the first added or subtracted
Wednesday possibly to 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.
add/subtract Thursdays. "a" causes the first added or subtracted
Thursday possibly to 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.
add/subtract Fridays. "a" causes the first added or subtracted
Friday possibly to 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.
add/subtract Saturdays. "a" causes the first added or subtracted
Saturday possibly to 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.
add/subtract weeks. "a" is not allowed.
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 is 1, 11, or 21, adding
# partial or entire ten-day periods to get 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.
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. (For example, 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.
add/subtract quarters. "a" aligns to nearest # quarters within
the year, and # must be either 1 or 2.
(For example, 2 aligns to Jan 1 or Jul 1 at midnight.)
0 goes to the beginning of the current quarter, independent of sign.
add/subtract years. "a" aligns to nearest # years.
(For example, 5 aligns to Jan 1 at midnight in 1995, 2000, 2005, and so on.)
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 manner.)
For example, for a date/time of May 13, 2012 4:32 PM (a Sunday),
the relative time element is: "+a3hr +12hr -1day".
The first field of the relative time specifies adding up to three hours, and aligning to the nearest three-hour boundary. This operation advances the time to 6:00 PM.
The second field specifies adding twelve hours, which advances the time to 6:00 AM on May 14.
The third field specifies subtracting a whole day, which leaves us at 6:00 AM on May 13.
You can add relative time objects to time/date objects, or you can
subtract relative time objects from time/date objects. Also, you can add
them to each other, subtract them from each other, or multiplt them 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.
timeDate class, timeSpan class,
timeRelative function.