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.

For python users learning R, a quick answer would be that `...` is the R equivalent of python's keyword input (`def func(**kwargs)`) — cacti5, May 09 '18 at 20:25

score 79 · Accepted Answer · edited May 23 '17 at 12:10

79

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?

edited May 23 '17 at 12:10

Community

1
1

answered May 04 '11 at 22:33

John Zwinck

239,568
38
324
436

8

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 – MichaelChirico Aug 19 '19 at 13:52
1

Regarding help files, `?dots` does not work for me, but `?'...'` does. – coip Sep 12 '19 at 23:49

score 56 · Answer 2 · answered May 05 '11 at 10:53

56

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

answered May 05 '11 at 10:53

Richie Cotton

118,240
47
247
360

Why in #2 call the same f function again? – JP Zhang Sep 09 '18 at 15:20
1

@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. – Richie Cotton Sep 10 '18 at 16:02
3

This would be a great example to demonstrate `...length()` as well – MichaelChirico Aug 19 '19 at 13:53

score 20 · Answer 3 · answered May 05 '11 at 00:04

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)

@qed `trim` is an argument to the `mean` function. The `...` in `sapply` are the mechanism for `trim` to be passed to `mean`. — Richie Cotton, Mar 16 '15 at 10:34

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

3 Answers3

Linked

Related