

substitute {base}                            R Documentation

_S_u_b_s_t_i_t_u_t_i_n_g _a_n_d _Q_u_o_t_i_n_g _E_x_p_r_e_s_s_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n_:

     `substitute' returns the parse tree for the (unevalu-
     ated) expression `expr', substituting any variables
     bound in `env'.
     `quote' simply returns the parse tree for the expres-
     sion.

_U_s_a_g_e_:

     substitute(expr, env=<<see below>>)
     quote(expr)

_A_r_g_u_m_e_n_t_s_:

    expr: Any syntactically valid R expression

     env: An environment or a list object. Defaults to the
          current evaluation environment.

_D_e_t_a_i_l_s_:

     The typical use of `substitute' is to create informa-
     tive labels for data sets and plots.  The `myplot'
     example below shows a simple use of this facility.  It
     uses the functions `deparse' and `substitute' to create
     labels for a plot which are character string versions
     of the actual arguments to the function `myplot'.

     Substitution takes place by examining each component of
     the parse tree as follows: If it is not a bound symbol
     in `env', it is unchanged. If it is a promise object,
     i.e. a formal argument to a function or explicitly cre-
     ated using `delay()', the expression slot of the
     promise replaces the symbol. If it is an ordinary vari-
     able, its value is substituted, unless `env' is `.Glob-
     alEnv' in which case the symbol is left unchanged.

_V_a_l_u_e_:

     The `mode' of the result is generally `"call"' but may
     in principle be any type. In particular, single-vari-
     able expressions have mode `"name"' and constants have
     the appropriate base mode.

_N_o_t_e_:

     Substitute works on a purely lexical basis. There is no
     guarantee that the resulting expression makes any
     sense.

     Substituting and quoting often causes confusion when
     the argument is `expression(...)'. The result is a call
     to the `expression' constructor function and needs to
     be evaluated with `eval' to give the actual expression
     object.

_S_e_e _A_l_s_o_:

     `missing' for argument ``missingness''.

_E_x_a_m_p_l_e_s_:

     (s.e <- substitute(expression(a + b), list(a = 1)))  #> expression(1 + b)
     (s.s <- substitute( a + b,            list(a = 1)))  #> 1 + b
     c(mode(s.e), typeof(s.e)) #  "call", "language"
     c(mode(s.s), typeof(s.s)) #   (the same)
     # but:
     (e.s.e <- eval(s.e))          #>  expression(1 + b)
     c(mode(e.s.e), typeof(e.s.e)) #  "expression", "expression"

     substitute(x <- x + 1, list(x=1)) # nonsense

     myplot <- function(x, y)
             plot(x, y, xlab=deparse(substitute(x)),
                     ylab=deparse(substitute(y)))

     ## Simple examples about lazy evaluation, etc:

     f1 <- function(x, y = x)             { x <- x + 1; y }
     s1 <- function(x, y = substitute(x)) { x <- x + 1; y }
     s2 <- function(x, y) { if(missing(y)) y <- substitute(x); x <- x + 1; y }
     a <- 10
     f1(a)# 11
     s1(a)# 11
     s2(a)# a
     typeof(s2(a))# "symbol"

