[Rd] guidelines for consistency of vector functions

[Tony Plate]

Moving on from the discussion of the fact that length(x)==9 for any 
POSIXlt object x (which seems diabolically confusing, given that 'c' and 
'[' are defined for POSIXlt and have the vector-like behavior one would 
expect), what about having some guidelines for coding and documentation 
of vector-like classes?

(1) a vector-like class should implement functions in groups:
    level 1: 'c', '[', 'length'
    level 2: 'x[i] <- value', 'rep', 'unique', 'duplicated'
    level 3: 'head', 'tail', 'sort'
    NA group: 'is.na' 'x[i] <- NA' 'is.na(x) <- TRUE'
    character coercion: 'as.character', 'as.<CLASS>.character'
    names group: 'names()' 'names()<-'

[should '==', 'all.equal' be included anywhere]

If any member of a group is implemented, then it is considered good 
style to implement the others.

(2) conformance or deviation from this guideline should be documented on 
the help page for the class.

These could go in a section of R-ext, and a function that automatically 
checks conformance could also be supplied as part of R.  A rough version 
of such a function is attached.

This would have the following benefits:

(1) developers would have guidelines and tools to help them write 
classes that behave in a way that users expect

(2) users would know better what to expect, both in general, and in 
specific cases where developers followed the documentation guidelines.

(3) observance of the guidelines would be an indicator of software 
quality (no evidence of any attention to the guidelines would be a sign 
that the code was more of an experiment than a piece of software that 
was carefully engineered for widespread use.)

All of the above is a rough draft that could be discussed further (e.g., 
should '[.<-' go in level 1 or level 2?) if there was any interest in 
pursuing this suggestion.

Comments?

-- Tony Plate

PS:

Here's a few examples of running an automatic vector-functionality 
tester on some vector-like classes in R ("basic"="level 1", 
"extra"="level 2", and "bonus"="level 3" functions) (this might be hard 
to read if line wrapping happens -- I've attached text files):

 > source("testVectorFunctionality.R")
 > library(chron)
 > if (exists("length.POSIXlt")) remove(list="length.POSIXlt")
 >
 > ### 'character' passes the functionality tests
 > res <- testVectorFunctionality(CLASS="character", verbose=FALSE)
Passed all 17 basic tests, 17 extra tests, and 5 bonus tests
 >
 > ### 'numeric' passes the functionality tests
 > res <- testVectorFunctionality(CLASS="numeric", verbose=FALSE)
Passed all 17 basic tests, 17 extra tests, and 5 bonus tests
 >
 > ### 'integer' passes the functionality tests
 > res <- testVectorFunctionality(CLASS="integer", verbose=FALSE)
Passed all 17 basic tests, 17 extra tests, and 5 bonus tests
 >
 > ### 'Date' passes the functionality tests
 > res <- testVectorFunctionality(from.numeric=function(i) 
as.Date("2001/01/01") + i, verbose=FALSE)
Passed all 17 basic tests, 17 extra tests, and 5 bonus tests
 >
 > ### chron 'times' passes the basic, but not the extra functionality tests
 > res <- testVectorFunctionality(from.numeric=function(i) 
chron(times=i), verbose=FALSE)
Failed 0 of 17 basic tests, 12 of 17 extra tests, and 0 of 0 bonus tests
 > res <- testVectorFunctionality(from.numeric=function(i) 
chron(times=i), verbose=TRUE)
Testing basic vector functionality for class 'times'
Testing extra vector functionality for class 'times'
   Failed consistency check: unique(xa) == xa
   Failed consistency check: unique(xb) == xb
   Failed consistency check: unique(x0) == x0
   Failed consistency check: unique(x1) == x1
   Failed consistency check: unique(xA) == xA[!duplicated(xA)]
   Failed consistency check: rep(x1, 3) == c(x1, x1, x1)
   Failed consistency check: rep(xa, 3) == c(xa, xa, xa)
   Failed consistency check: rep(xb, 2) == c(xb, xb)
   Failed consistency check: rep(x1, 0) == x1[0]
   Failed consistency check: rep(xa, each = 3) == xa[rep(seq(len = 
xa.len), each = 3)]
   Failed consistency check: rep(xb, each = 2) == xb[rep(seq(len = 
xb.len), each = 2)]
   Failed consistency check: rep(xa, length.out = xa.len + 1) == c(xa, 
xa[1])
In 17 basic consistency tests on 'times', had the following outcomes: ok:17
   'ok' tests (17) involved: '[':4, c:9, length:9
In 17 extra consistency tests on 'times', had the following outcomes: 
failure:12, ok:5
   'failure' tests (12) involved: duplicated:1, rep:7, unique:5
   'ok' tests (5) involved: duplicated:5
Did not perform any bonus consistency tests on 'times'
 >
 > ### chron 'dates' does not pass the basic functionality tests
 > res <- testVectorFunctionality(from.numeric=function(i) chron(i), 
verbose=FALSE)
Failed 6 of 17 basic tests, 0 of 0 extra tests, and 0 of 0 bonus tests
 > res <- testVectorFunctionality(from.numeric=function(i) chron(i), 
verbose=TRUE)
Testing basic vector functionality for class ['dates', 'times']
   Failed consistency check: c(x1) == x1
   Failed consistency check: c(x1, x0) == x1
   Failed consistency check: c(x0, x1) == x1
   Failed consistency check: c(xa) == xa
   Failed consistency check: c(xa, x0) == xa
   Failed consistency check: c(x0, xa) == xa
In 17 basic consistency tests on ['dates', 'times'], had the following 
outcomes: failure:6, ok:11
   'failure' tests (6) involved: c:6
   'ok' tests (11) involved: '[':4, c:3, length:9
Did not perform any extra consistency tests on ['dates', 'times']
Did not perform any bonus consistency tests on ['dates', 'times']
 > # The reason for the failure with c() is that it removes names on the 
origin in chron 'dates'
 > eval(quote(all.equal(c(x1), x1)), res$bindings)
[1] "Attributes: < Component 3: names for current but not for target >"
 > attr(eval(quote(x1), res$bindings), "origin")
month   day  year
     1     1  1970
 > attr(eval(quote(c(x1)), res$bindings), "origin")
[1]    1    1 1970
 >
 > ### POSIXct passes the functionality tests
 > res <- testVectorFunctionality(from.numeric=function(i) 
as.POSIXct("2001/01/01") + 24*3600*i, verbose=FALSE)
Passed all 17 basic tests, 17 extra tests, and 5 bonus tests
 >
 > ### POSIXlt fails the basic functionality tests because length() for 
POSIXlt always returns 9
 > res <- testVectorFunctionality(from.numeric=function(i) 
as.POSIXlt(as.POSIXlt("2001/01/01") + 24*3600*i), verbose=FALSE)
Failed 9 of 17 basic tests, 0 of 0 extra tests, and 0 of 0 bonus tests
 > res <- testVectorFunctionality(from.numeric=function(i) 
as.POSIXlt(as.POSIXlt("2001/01/01") + 24*3600*i), verbose=TRUE)
Testing basic vector functionality for class ['POSIXt', 'POSIXlt']
   Failed consistency check: length(x1) == 1L
   Failed consistency check: length(x0) == 0L
   Failed consistency check: length(xa) == xa.len
   Failed consistency check: length(xb) == xb.len
   Failed consistency check: length(c(x1, xa)) == xa.len + x1.len
   Failed consistency check: length(c(x0, xa)) == xa.len
   Failed consistency check: length(c(xa, xb)) == xa.len + xb.len
   Failed consistency check: xa[-length(xa)] == xa[seq(len = xa.len - 1)]
   Failed consistency check: length(xa[0]) == 0L
In 17 basic consistency tests on ['POSIXt', 'POSIXlt'], had the 
following outcomes: failure:9, ok:8
   'failure' tests (9) involved: '[':2, c:3, length:9
   'ok' tests (8) involved: '[':2, c:6
Did not perform any extra consistency tests on ['POSIXt', 'POSIXlt']
Did not perform any bonus consistency tests on ['POSIXt', 'POSIXlt']
 >
 > ### define length() for POSIXlt and now POSIXlt passes the 
functionality tests
 > length.POSIXlt <- function(x) length(x$sec)
 > res <- testVectorFunctionality(from.numeric=function(i) 
as.POSIXlt(as.POSIXlt("2001/01/01") + 24*3600*i), verbose=FALSE)
Passed all 17 basic tests, 17 extra tests, and 5 bonus tests
 >

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: TestRuns.txt
Url: https://stat.ethz.ch/pipermail/r-devel/attachments/20071216/fd6d51fc/attachment.txt 
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: testVectorFunctionality.R
Url: https://stat.ethz.ch/pipermail/r-devel/attachments/20071216/fd6d51fc/attachment.pl