Usage of `…` (three-dots or dot-dot-dot) in functions

Question

Where can I find documentation on the usage of ... in functions? Examples would be useful.

Answer 1

The word used to describe ... is "ellipsis." Knowing this should make searching for information about the construct easier. For example, the first hit on Google is another question on this site: How to use R's ellipsis feature when writing your own function?

Answer 2

A little example to get you started.

f <- function(x, ...)
{
  dots <- list(...)                   #1
  if(length(dots) == 0) return(NULL) 
  cat("The arguments in ... are\n")
  print(dots)
  f(...)                              #2
}

f(1,2,3,"a", list("monkey"))

The function, f, stores all but the first input argument in the ellipsis variable. For accessing its contents, it is easiest to convert it to a list (1). The main use however is for passing arguments to subfunctions, which requires no conversion (2).

Answer 3

You should head over to "R Language Definition", section 2.1.9 Dot-dot-dot. It comes bundled with R installation. Run help.start() in an interactive session to bring HTML help up, and click on The R Language Definition link. You can use PDF or HTML version from the main site as well.

Anyway, ... is used to match unspecified formal arguments of a function.

args(sapply)                                                                                                               
function (X, FUN, ..., simplify = TRUE, USE.NAMES = TRUE)                                                                    
NULL   

sapply(mtcars, mean, trim = .5)                                                                                            
    mpg     cyl    disp      hp    drat      wt    qsec      vs      am    gear                                              
 19.200   6.000 196.300 123.000   3.695   3.325  17.710   0.000   0.000   4.000                                              
   carb                                                                                                                      
  2.000 

As you can see, I passed trim = .5 though it's not specified as a formal argument of sapply function.

(note that this example is trivial, you can use sapply(mtcars, median) to achieve the same result)