CODEWITHSUNDEEP
rgenericsreplicationr-s3
J. Mini
J. Mini

Reputation: 1610

Does the documentation for rep tell us that it is an internal generic function?

Because it is on the list of Internal Generic Functions, I know that rep is an internal generic function. Could this fact have been derived by only reading the documentation for rep? I have located the following two relevant-looking sections:

rep replicates the values in x. It is a generic function, and the (internal) default method is described here.

For the internal default method these can include:

Do either of these specifically tell the reader that rep is an internal generic function?

To be totally clear, I'm asking about the terminology that is used in these extracts. I'm not an expert on R's terminology, so what I'm asking is about what is implied by the words that they've used. For example, if the R documentation says that a function "is generic" and has an "internal default method", does that mean that the function is therefore an internal generic function?

A link to some sort of glossary of R terms, or the relevant section in one of the R manuals, would be a very strong component of a good answer. A simple yes or no will probably not suffice.

Upvotes: 1

Views: 245

Answers (1)

Ventrilocus
Ventrilocus

Reputation: 1488

Firstly, I think you would benefit from the following resource (15.7 Generic-Function OO, https://homerhanumat.github.io/r-notes/generic-function-oo.html).

Secondly, some definitions (extracted from https://homerhanumat.github.io/r-notes/glossary-12.html and https://colinfay.me/r-internals/internal-vs-primitive.html):

Generic function: "A function that dispatches an input object to one of a number of method-functions, based on the class of the input".

Generic-Function OO: "A type of object-oriented programming in which tasks are performed by generic functions. The method used to perform a particular task is determined by the class of the input object".

Primitive and Internal functions: "C code compiled into R at build time can be called directly in what are termed primitives or via the .Internal interface, which is very similar to the .External interface except in syntax".

Thus, we can say that:

Internal Generic function: Primitive and internal functions that are generic (e.g. function that dispatches an input object to one of a number of method-functions, based on the class of the input).

Now, answering your questions:

a) Is the documentation clear?

"It is a generic function, and the (internal) default method is described here". It clearly states that rep is a generic function. The "(internal)" sort of glimpses that it is a internal/primitive function. What is the need for the parenthesis around internal? I actually do not know. It would certainly be clearer if it stated: "rep falls under the category of internal generic functions (see InternalMethods). Details on the default methods are described here". However, for rep.int and rep_len it is a bit clearer ("Internally, they are generic"). Writing good documentation is always hard!

b) How to empirically find out whether a function is internal generic

Relying on documentation does not always guarantee success. This is certainly true for the huge diversity of R-packages offered at CRAN. But, this topic is not just a random R-package but low level R-programming language. Reading rep's source code you, we can confirm that rep is a primitive function:

> rep
function (x, ...)  .Primitive("rep")

And by running the following, we can confirm that rep is a generic function:

> methods(rep)
[1] rep.bibentry*       rep.Date            rep.factor          rep.numeric_version rep.POSIXct        
[6] rep.POSIXlt         rep.roman*

Therefore, rep must be an internal generic function. Just to provide a negative control (the output of methods for a function that is not generic), see below:

> methods(diag)
no methods found

c) R-CRAN resources

Finally, CRAN did do a great job compiling the definition of the R-programming language here (cran.r-project.org/doc/manuals/r-release/R-lang.html); There is much more information on section "5 Object-oriented programming". But resources provided above are a bit more didactical. CRAN offers several manuals which may be of your interest (cran.r-project.org/manuals.html).

Upvotes: 4

Related Questions