timeRelative-class {splusTimeDate} | R Documentation |
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"
.
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
.
Slots
- Data
-
(
character
) a string vector representing the relative time. - holidays
-
(
positionsCalendar
) a vector of holiday dates.
Notes
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 theholidays
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.
See Also
timeDate
class, timeSpan
class,
timeRelative
function.