jul: Julian Date Objects

In tis: Time Indexes and Time Indexed Series

Description

The function jul is used to create jul (julian date) objects, which are useful for date calculations.

as.jul and asJul coerce an object to class "jul", the difference being that as.jul calls the constructor jul, while asJul simply forces the class of its argument to be "jul" without any checking as to whether or not it makes sense to do so.

is.jul tests whether an object inherits from class "jul".

Usage

jul(x, ...)
## S3 method for class 'Date'
jul(x, ...)
## S3 method for class 'IDate'
jul(x, ...)
## S3 method for class 'ti'
jul(x, offset = 1, ...)
## S3 method for class 'yearmon'
jul(x, offset = 0, ...)
## S3 method for class 'yearqtr'
jul(x, offset = 0, ...)
## Default S3 method:
jul(x, ...)
as.jul(x, ...)
asJul(x)
is.jul(x)

Arguments

x	object to be tested (is.jul) or converted into a jul object. As described in the details below, the constructor function jul can deal with several different kinds of x.
...	other args to be passed to the method called by the generic function. jul.default may pass these args to as.Date.
offset	For jul.ti, a number in the range [0,1] telling where in the period represented by x to find the day. 0 returns the first day of the period, while the default value 1 returns the last day of the period. For example, if x has tif = "wmonday" so that x represents a week ending on Monday, than any offset in the range [0, 1/7] will return the Tuesday of that week, while offset in the range (1/7, 2/7] will return the Wednesday of that week, offset in the range (6/7, 1] will return the Monday that ends the week, and so on. jul.yearmon and jul.yearqtr work on yearmon and yearqtr objects from zoo. Note that the default offset for these functions is 0, not 1, as that is how the other index-to-date functions in zoo work, i.e, if ym is a yearmon object, then as.Date(ym) and as.jul(ym) should give the same date.

Details

The jul's for any pair of valid dates differ by the number of days between them. R's Date class defines a Date as a number of days elapsed since January 1, 1970, but jul uses the encoding from the Numerical Recipes book, which has Jan 1, 1970 = 2440588, and the code for converting between ymd and jul representations is a straightforward port of the code from that tome.

Adding an integer to, or subtracting an integer from a jul results in another jul, and one jul can be subtracted from another. Two jul's can also be compared with the operators (==, !=, <. >, <=, >=).

The jul class implements methods for a number of generic functions, including "[", as.Date, as.POSIXct, as.POSIXlt, c, format, max, min, print, rep, seq, ti, time, ymd.

jul is a generic function with specialized methods to handle Date and ti objects. A recent addition is a method to handle IDate objects as defined in the data.table package.

The default method (jul.default) deals with character x by calling as.Date on it. Otherwise, it proceeds as follows:

If x is numeric, isYmd is used to see if it could be yyyymmdd date, then isTime is called to see if x could be a decimal time (a number between 1799 and 2200). If all else fails, as.Date(x) is called to attempt to create a Date object that can then be used to construct a jul.

Value

is.jul returns TRUE or FALSE.

as.jul and asJul return objects with class "jul".

jul constructs a jul object like x.

jul with no arguments returns the jul for the current day.

Note

The return value from asJul is not guaranteed to be a valid jul object. For example, asJul("a") will not throw an error, and it will return the string "a" with a class attribute "jul", but that's not a valid julian date.

The Julian calendar adopted by the Roman Republic was not accurate with respect to the rotational position of the Earth around the sun. By 1582 it had drifted ten days off. To fix this, Pope Gregory XIII decreed that the day after October 4, 1582 would be October 15, and that thereafter, leap years would be omitted in years divisible by 100 but not divisible by 400. This modification became known as the Gregorian calendar. England and the colonies did not switch over until 1752, by which time the drift had worsened by another day, so that England had to skip over 11 days, rather than 10.

The algorithms used in jul2ymd and ymd2jul cut over at the end of October 1582.

References

Press, W. H., Teukolsky, S. A., Vetterling, W. T., and Flannery, B. P. (1992). Numerical Recipes: The Art of Scientific Computing (Second Edition). Cambridge University Press.

See Also

jul, ymd, ti, as.Date

Examples

dec31 <- jul(20041231)
jan30 <- jul("2005-1-30")
jan30 - dec31              ## 30
feb28 <- jan30 + 29
jul()                      ## current date

tis documentation built on Sept. 29, 2021, 1:06 a.m.