| % File src/library/base/man/dots.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2020 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{dots} |
| \title{\dots, \code{..1}, etc used in Functions} |
| \alias{dots} |
| \alias{...} |
| \alias{..1} |
| \alias{..2} |
| \alias{...elt} |
| \alias{...length} |
| \alias{...names} |
| \description{ |
| \code{\dots} and \code{..1}, \code{..2} etc are used to refer to |
| arguments passed down from a calling function. These (and the |
| following) can only be used \emph{inside} a function which has |
| \code{...} among its formal arguments. |
| |
| \code{...elt(n)} is a functional way to get \code{..<n>} and |
| basically the same as \code{eval(paste0("..", n))}, just more elegant |
| and efficient. |
| Note that \code{switch(n, ...)} is very close, differing by returning |
| \code{NULL} invisibly instead of an error when \code{n} is zero or |
| too large. |
| |
| \code{...length()} returns the number of expressions in \code{\dots}, and |
| \code{...names()} the \code{\link{names}}. |
| These are the same as \code{length(list(...))} or \code{names(list(...))} |
| but without evaluating the expressions in \code{...} (which happens with |
| \code{list(...)}). |
| |
| Evaluating elements of \code{\dots} with \code{..1}, \code{..2}, |
| \code{...elt(n)}, etc. propagates \link[=invisible]{visibility}. This |
| is consistent with the evaluation of named arguments which also |
| propagates visibility. |
| } |
| \usage{ |
| ...length() |
| ...names() |
| ...elt(n) |
| } |
| \arguments{ |
| \item{n}{a positive integer, not larger than the number of expressions |
| in \dots, which is the same as \code{...length()} which is the same |
| as \code{length(list(...))}, but the latter evaluates all |
| expressions in \code{\dots}.} |
| } |
| \seealso{ |
| \code{\dots} and \code{..1}, \code{..2} are \emph{reserved} words in |
| \R, see \code{\link{Reserved}}. |
| |
| For more, see the |
| \ifelse{html}{\href{/doc/manual/R-intro.html#The-three-dots-argument}{Introduction to R}}{\sQuote{Introduction to R}} |
| manual for usage of these syntactic elements, |
| and \link[methods]{dotsMethods} for their use in formal (S4) methods. |
| } |
| \examples{ |
| tst <- function(n, ...) ...elt(n) |
| tst(1, pi=pi*0:1, 2:4) ## [1] 0.000000 3.141593 |
| tst(2, pi=pi*0:1, 2:4) ## [1] 2 3 4 |
| try(tst(1)) # -> Error about '...' not containing an element. |
| |
| tst.dl <- function(x, ...) ...length() |
| tst.dns <- function(x, ...) ...names() |
| tst.dl(1:10) # 0 (because the first argument is 'x') |
| tst.dl(4, 5) # 1 |
| tst.dl(4, 5, 6) # 2 namely '5, 6' |
| tst.dl(4, 5, 6, 7, sin(1:10), "foo"/"bar") # 5. Note: no evaluation! |
| tst.dns(4, foo=5, 6, bar=7, sini = sin(1:10), "foo"/"bar") |
| ## "foo" "" "bar" "sini" "" |
| |
| ## From R 4.1.0 to 4.1.2, ...names() sometimes did not match names(list(...)); |
| ## check and show (these examples all would've failed): |
| chk.n2 <- function(...) stopifnot(identical(print(...names()), names(list(...)))) |
| chk.n2(4, foo=5, 6, bar=7, sini = sin(1:10), "bar") |
| chk.n2() |
| chk.n2(1,2) |
| } |
| \keyword{programming} |
| \keyword{documentation} |