[Rd] Wishlist: In documentation, say that `+.Date`(Date, difftime) should be called directly or remove 'or an object of class "difftime"' (PR#14072)

[suharto_anggono at yahoo.com]

Full_Name: Suharto Anggono
Version: 2.8.1
OS: Windows
Submission from: (NULL) (125.161.134.206)


About PR#14067, now I understand why (Date + difftime) does not use '+.Date'.
But, before I understand, it was surprising. The surprise is also reflected in
the post "Problem with +(POSIXt, difftime) dispatching -- WAS: How to create
sequence of constant time interval" in R-help 2009-02-17.

This is taken from the documentation of Ops.Date.

Usage

date + x
...

Arguments
date 	date objects
...
x 	a numeric vector (in days) or an object of class "difftime".
...

Reading the documentation above suggests me that I can use (Date + difftime),
which I expect to use date/time arithmetic. PR#13369 also mentions that.

So, the documentation should mention that, to add "Date" with "difftime",
'+.Date' should be called directly, better with example. Alternatively, the
clause 'or an object of class "difftime"' should be removed.

It would be nice if (Date + difftime) could use '+.Date'. But, I think it would
not be easy. One way is making a virtual class that includes "Date", "POSIXct",
and "difftime", say "DateTimeComp", so that the 'class' attribute of
"Date" is c("DateTimeComp", "Date");
"POSIXct" is c("DateTimeComp", "POSIXt", "POSIXct");
"POSIXlt" is c("DateTimeComp", "POSIXt", "POSIXlt");
"difftime" is c("DateTimeComp", "difftime").
Then, define '+.DateTimeComp' or 'Ops.DateTimeComp' that ensures that (Date +
difftime) uses '+.Date'. If it is chosen to define 'Ops.DateTimeComp', the
definition could be like this.

function (e1, e2)
{
    if (nargs() == 1)
        return(NextMethod(.Generic))
    if (.Generic == "+" || .Generic == "-") {
        if ((inherits(e1, "Date") && inherits(e2, "POSIXt")) ||
            (inherits(e1, "POSIXt") && inherits(e2, "Date")))
            stop("binary ", .Generic,
                " between Date and POSIXt objects is not defined")
        if (inherits(e1, "Date") || inherits(e2, "Date"))
            return(do.call(paste(.Generic, "Date", sep = "."), list(e1, e2)))
        if (inherits(e1, "POSIXt") || inherits(e2, "POSIXt"))
            return(do.call(paste(.Generic, "POSIXt", sep = "."), list(e1, e2)))
    }
    else {
        h1 <- inherits(e1, c("Date", "POSIXt", "difftime"), which = TRUE)
        h2 <- inherits(e2, c("Date", "POSIXt", "difftime"), which = TRUE)
        if (sum(h1 | h2) > 1)
            stop(.Generic, " not defined")
    }
    NextMethod(.Generic)
}

But, that would require many changes and might break someone's code that access
the 'class' attribute directly.