splusTimeDate (version 2.5.0-137)

timeRelative-class: Relative Time Class

Description

The timeRelative class represents relative times.

Notes

1. All alignment and other operations are done in the local time zone of the time/date object.
2. Theholidaysslot of the relative time object is used to define which dates besides weekends are not business days; these dates are taken in theholidaysslots 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.

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:

lll{ "[+-][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: [object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object],[object Object] 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.

See Also

timeDate class, timeSpan class, timeRelative function.