Usage of `...` (three-dots or dot-dot-dot) in functions [duplicate]

Question

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

Pignus

For python users learning R, a quick answer would be that ... is the R equivalent of python's keyword input (def func(**kwargs)) – Devisor

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?

Drilling

Actually the official name in R is dots, e.g. the help page is named ?dots and "ellipsis" isn't even mentioned on the page – Dessiedessma

Regarding help files, ?dots does not work for me, but ?'...' does. – Kattegat

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).

Firer

Why in #2 call the same f function again? – Downstate

@JiapengZhang It's an example of a recursive function. f() gets called repeatedly with different arguments each time. Run the code and see if you can understand what is happening. – Firer

This would be a great example to demonstrate ...length() as well – Dessiedessma

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)

Legato

If it's not specified, how do you know it's legal or valid? – Hammertoe

@Hammertoe trim is an argument to the mean function. The ... in sapply are the mechanism for trim to be passed to mean. – Firer