timeRelative-class
Relative Time Class

Description

The timeRelative class represents relative times.

Details

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:
ms
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.
sec
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.
min
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.
hr
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.
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 (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.
wkd
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.
biz
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.
sun
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.
mon
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.
tue
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.
wed
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.
thu
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.
fri
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.
sat
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.
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 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.
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. (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.
qtr
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.
yr
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".
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.
Slots
Data
(character) a string vector representing the relative time.
holidays
(positionsCalendar) a vector of holiday dates.
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
timeDate class, timeSpan class, timeRelative function.
Package splusTimeDate version 6.0.0-69
Package Index