EVOLUTION-MANAGER
Edit File: vec_as_names.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Retrieve and repair names</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for vec_as_names {vctrs}"><tr><td>vec_as_names {vctrs}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Retrieve and repair names</h2> <h3>Description</h3> <p><code>vec_as_names()</code> takes a character vector of names and repairs it according to the <code>repair</code> argument. It is the r-lib and tidyverse equivalent of <code><a href="../../base/html/make.names.html">base::make.names()</a></code>. </p> <p>vctrs deals with a few levels of name repair: </p> <ul> <li> <p><code>minimal</code> names exist. The <code>names</code> attribute is not <code>NULL</code>. The name of an unnamed element is <code>""</code> and never <code>NA</code>. For instance, <code>vec_as_names()</code> always returns minimal names and data frames created by the tibble package have names that are, at least, <code>minimal</code>. </p> </li> <li> <p><code>unique</code> names are <code>minimal</code>, have no duplicates, and can be used where a variable name is expected. Empty names, <code>...</code>, and <code>..</code> followed by a sequence of digits are banned. </p> <ul> <li><p> All columns can be accessed by name via <code>df[["name"]]</code> and <code>df$`name` </code> and <code>with(df, `name`)</code>. </p> </li></ul> </li> <li> <p><code>universal</code> names are <code>unique</code> and syntactic (see Details for more). </p> <ul> <li><p> Names work everywhere, without quoting: <code>df$name</code> and <code>with(df, name)</code> and <code>lm(name1 ~ name2, data = df)</code> and <code>dplyr::select(df, name)</code> all work. </p> </li></ul> </li></ul> <p><code>universal</code> implies <code>unique</code>, <code>unique</code> implies <code>minimal</code>. These levels are nested. </p> <h3>Usage</h3> <pre> vec_as_names( names, ..., repair = c("minimal", "unique", "universal", "check_unique", "unique_quiet", "universal_quiet"), repair_arg = NULL, quiet = FALSE, call = caller_env() ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>names</code></td> <td> <p>A character vector.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>These dots are for future extensions and must be empty.</p> </td></tr> <tr valign="top"><td><code>repair</code></td> <td> <p>Either a string or a function. If a string, it must be one of <code>"check_unique"</code>, <code>"minimal"</code>, <code>"unique"</code>, <code>"universal"</code>, <code>"unique_quiet"</code>, or <code>"universal_quiet"</code>. If a function, it is invoked with a vector of minimal names and must return minimal names, otherwise an error is thrown. </p> <ul> <li><p> Minimal names are never <code>NULL</code> or <code>NA</code>. When an element doesn't have a name, its minimal name is an empty string. </p> </li> <li><p> Unique names are unique. A suffix is appended to duplicate names to make them unique. </p> </li> <li><p> Universal names are unique and syntactic, meaning that you can safely use the names as variables without causing a syntax error. </p> </li></ul> <p>The <code>"check_unique"</code> option doesn't perform any name repair. Instead, an error is raised if the names don't suit the <code>"unique"</code> criteria. </p> <p>The options <code>"unique_quiet"</code> and <code>"universal_quiet"</code> are here to help the user who calls this function indirectly, via another function which exposes <code>repair</code> but not <code>quiet</code>. Specifying <code>repair = "unique_quiet"</code> is like specifying <code style="white-space: pre;">repair = "unique", quiet = TRUE</code>. When the <code>"*_quiet"</code> options are used, any setting of <code>quiet</code> is silently overridden.</p> </td></tr> <tr valign="top"><td><code>repair_arg</code></td> <td> <p>If specified and <code>repair = "check_unique"</code>, any errors will include a hint to set the <code>repair_arg</code>.</p> </td></tr> <tr valign="top"><td><code>quiet</code></td> <td> <p>By default, the user is informed of any renaming caused by repairing the names. This only concerns unique and universal repairing. Set <code>quiet</code> to <code>TRUE</code> to silence the messages. </p> <p>Users can silence the name repair messages by setting the <code>"rlib_name_repair_verbosity"</code> global option to <code>"quiet"</code>.</p> </td></tr> <tr valign="top"><td><code>call</code></td> <td> <p>The execution environment of a currently running function, e.g. <code>caller_env()</code>. The function will be mentioned in error messages as the source of the error. See the <code>call</code> argument of <code><a href="../../rlang/html/abort.html">abort()</a></code> for more information.</p> </td></tr> </table> <h3><code>minimal</code> names</h3> <p><code>minimal</code> names exist. The <code>names</code> attribute is not <code>NULL</code>. The name of an unnamed element is <code>""</code> and never <code>NA</code>. </p> <p>Examples: </p> <div class="sourceCode"><pre>Original names of a vector with length 3: NULL minimal names: "" "" "" Original names: "x" NA minimal names: "x" "" </pre></div> <h3><code>unique</code> names</h3> <p><code>unique</code> names are <code>minimal</code>, have no duplicates, and can be used (possibly with backticks) in contexts where a variable is expected. Empty names, <code>...</code>, and <code>..</code> followed by a sequence of digits are banned. If a data frame has <code>unique</code> names, you can index it by name, and also access the columns by name. In particular, <code>df[["name"]]</code> and <code>df$`name`</code> and also <code>with(df, `name`)</code> always work. </p> <p>There are many ways to make names <code>unique</code>. We append a suffix of the form <code>...j</code> to any name that is <code>""</code> or a duplicate, where <code>j</code> is the position. We also change <code>..#</code> and <code>...</code> to <code>...#</code>. </p> <p>Example: </p> <div class="sourceCode"><pre>Original names: "" "x" "" "y" "x" "..2" "..." unique names: "...1" "x...2" "...3" "y" "x...5" "...6" "...7" </pre></div> <p>Pre-existing suffixes of the form <code>...j</code> are always stripped, prior to making names <code>unique</code>, i.e. reconstructing the suffixes. If this interacts poorly with your names, you should take control of name repair. </p> <h3><code>universal</code> names</h3> <p><code>universal</code> names are <code>unique</code> and syntactic, meaning they: </p> <ul> <li><p> Are never empty (inherited from <code>unique</code>). </p> </li> <li><p> Have no duplicates (inherited from <code>unique</code>). </p> </li> <li><p> Are not <code>...</code>. Do not have the form <code>..i</code>, where <code>i</code> is a number (inherited from <code>unique</code>). </p> </li> <li><p> Consist of letters, numbers, and the dot <code>.</code> or underscore <code style="white-space: pre;">_</code> characters. </p> </li> <li><p> Start with a letter or start with the dot <code>.</code> not followed by a number. </p> </li> <li><p> Are not a <a href="../../base/html/Reserved.html">reserved</a> word, e.g., <code>if</code> or <code>function</code> or <code>TRUE</code>. </p> </li></ul> <p>If a vector has <code>universal</code> names, variable names can be used "as is" in code. They work well with nonstandard evaluation, e.g., <code>df$name</code> works. </p> <p>vctrs has a different method of making names syntactic than <code><a href="../../base/html/make.names.html">base::make.names()</a></code>. In general, vctrs prepends one or more dots <code>.</code> until the name is syntactic. </p> <p>Examples: </p> <div class="sourceCode"><pre> Original names: "" "x" NA "x" universal names: "...1" "x...2" "...3" "x...4" Original names: "(y)" "_z" ".2fa" "FALSE" universal names: ".y." "._z" "..2fa" ".FALSE" </pre></div> <h3>See Also</h3> <p><code><a href="../../rlang/html/names2.html">rlang::names2()</a></code> returns the names of an object, after making them <code>minimal</code>. </p> <h3>Examples</h3> <pre> # By default, `vec_as_names()` returns minimal names: vec_as_names(c(NA, NA, "foo")) # You can make them unique: vec_as_names(c(NA, NA, "foo"), repair = "unique") # Universal repairing fixes any non-syntactic name: vec_as_names(c("_foo", "+"), repair = "universal") </pre> <hr /><div style="text-align: center;">[Package <em>vctrs</em> version 0.5.0 <a href="00Index.html">Index</a>]</div> </body></html>