R: Evaluate an expression with tidyselect semantics

eval_rename {tidyselect} | R Documentation

## Evaluate an expression with tidyselect semantics

### Description

`eval_select()` and `eval_rename()` evaluate defused R code (i.e. quoted expressions) according to the special rules of the tidyselect syntax. They power functions like `dplyr::select()`, `dplyr::rename()`, or `tidyr::pivot_longer()`.

See the Get started vignette to learn how to use `eval_select()` and `eval_rename()` in your packages.

### Usage

    eval_rename(
      expr,
      data,
      env = caller_env(),
      ...,
      strict = TRUE,
      name_spec = NULL
    )

    eval_select(
      expr,
      data,
      env = caller_env(),
      ...,
      include = NULL,
      exclude = NULL,
      strict = TRUE,
      name_spec = NULL
    )

### Arguments

`expr` | Defused R code describing a selection according to the tidyselect syntax.
`data` | A named list, data frame, or atomic vector. Technically, `data` can be any vector with `names()` and `"[["` implementations.
`env` | The environment in which to evaluate `expr`. Discarded if `expr` is a quosure.
`...` | These dots are for future extensions and must be empty.
`strict` | If `TRUE`, out-of-bounds errors are thrown if `expr` attempts to select or rename a variable that doesn't exist. If `FALSE`, failed selections or renamings are ignored.
`name_spec` | A name specification describing how to combine or propagate names. This is used only in case nested `c()` expressions like `c(foo = c(bar = starts_with("foo")))`. See the `name_spec` argument of `vctrs::vec_c()` for a description of valid name specs.
`include, exclude` | Character vector of column names to always include or exclude from the selection.

### Details

The select and rename variants take the same types of inputs and have the same type of return value. However `eval_rename()` has a few extra constraints. It requires named inputs, and will fail if a data frame column is renamed to another existing column name. See the selecting versus renaming section in the syntax vignette for a description of the differences.

### Value

A named vector of numeric locations, one for each of the selected elements.

The names are normally the same as in the input data, except when the user supplied named selections with `c()`. In the latter case, the names reflect the new names chosen by the user.

A given element may be selected multiple times under different names, in which case the vector might contain duplicate locations.

### See Also

https://tidyselect.r-lib.org/articles/syntax.html or `vignette("syntax", package = "tidyselect")` for a technical description of the rules of evaluation.

### Examples

    library(rlang)

    # Interpret defused code as selection:
    x <- expr(mpg:cyl)
    eval_select(x, mtcars)

    # Interpret defused code as a renaming selection. All inputs must
    # be named within `c()`:
    try(eval_rename(expr(mpg), mtcars))
    eval_rename(expr(c(foo = mpg)), mtcars)

    # The evaluators return a named vector of locations. Here are
    # examples of using these location vectors to implement `select()`
    # and `rename()`:
    select <- function(.x, ...) {
      pos <- eval_select(expr(c(...)), .x)
      set_names(.x[pos], names(pos))
    }
    rename <- function(.x, ...) {
      pos <- eval_rename(expr(c(...)), .x)
      names(.x)[pos] <- names(pos)
      .x
    }

    select(mtcars, mpg:cyl)
    rename(mtcars, foo = mpg)

[Package tidyselect version 1.0.0 Index]