Relative Time Class

DESCRIPTION:

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.

SEE ALSO:

class, class, function.