EVOLUTION-MANAGER
Edit File: vec_as_location.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: Create a vector of locations</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_location {vctrs}"><tr><td>vec_as_location {vctrs}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Create a vector of locations</h2> <h3>Description</h3> <p>These helpers provide a means of standardizing common indexing methods such as integer, character or logical indexing. </p> <ul> <li> <p><code>vec_as_location()</code> accepts integer, character, or logical vectors of any size. The output is always an integer vector that is suitable for subsetting with <code>[</code> or <code><a href="vec_slice.html">vec_slice()</a></code>. It might be a different size than the input because negative selections are transformed to positive ones and logical vectors are transformed to a vector of indices for the <code>TRUE</code> locations. </p> </li> <li> <p><code>vec_as_location2()</code> accepts a single number or string. It returns a single location as a integer vector of size 1. This is suitable for extracting with <code>[[</code>. </p> </li> <li> <p><code>num_as_location()</code> and <code>num_as_location2()</code> are specialized variants that have extra options for numeric indices. </p> </li></ul> <h3>Usage</h3> <pre> vec_as_location( i, n, names = NULL, ..., missing = c("propagate", "remove", "error"), arg = caller_arg(i), call = caller_env() ) num_as_location( i, n, ..., missing = c("propagate", "remove", "error"), negative = c("invert", "error", "ignore"), oob = c("error", "remove", "extend"), zero = c("remove", "error", "ignore"), arg = caller_arg(i), call = caller_env() ) vec_as_location2( i, n, names = NULL, ..., missing = c("error", "propagate"), arg = caller_arg(i), call = caller_env() ) num_as_location2( i, n, ..., negative = c("error", "ignore"), missing = c("error", "propagate"), arg = caller_arg(i), call = caller_env() ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>i</code></td> <td> <p>An integer, character or logical vector specifying the locations or names of the observations to get/set. Specify <code>TRUE</code> to index all elements (as in <code>x[]</code>), or <code>NULL</code>, <code>FALSE</code> or <code>integer()</code> to index none (as in <code>x[NULL]</code>).</p> </td></tr> <tr valign="top"><td><code>n</code></td> <td> <p>A single integer representing the total size of the object that <code>i</code> is meant to index into.</p> </td></tr> <tr valign="top"><td><code>names</code></td> <td> <p>If <code>i</code> is a character vector, <code>names</code> should be a character vector that <code>i</code> will be matched against to construct the index. Otherwise, not used. The default value of <code>NULL</code> will result in an error if <code>i</code> is 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>missing</code></td> <td> <p>How should missing <code>i</code> values be handled? </p> <ul> <li> <p><code>"error"</code> throws an error. </p> </li> <li> <p><code>"propagate"</code> returns them as is. </p> </li> <li> <p><code>"remove"</code> removes them. </p> </li></ul> <p>By default, vector subscripts propagate missing values but scalar subscripts error on them. </p> <p>Propagated missing values can't be combined with negative indices when <code>negative = "invert"</code>, because they can't be meaningfully inverted.</p> </td></tr> <tr valign="top"><td><code>arg</code></td> <td> <p>The argument name to be displayed in error messages.</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> <tr valign="top"><td><code>negative</code></td> <td> <p>How should negative <code>i</code> values be handled? </p> <ul> <li> <p><code>"error"</code> throws an error. </p> </li> <li> <p><code>"ignore"</code> returns them as is. </p> </li> <li> <p><code>"invert"</code> returns the positive location generated by inverting the negative location. When inverting, positive and negative locations can't be mixed. This option is only applicable for <code>num_as_location()</code>. </p> </li></ul> </td></tr> <tr valign="top"><td><code>oob</code></td> <td> <p>How should out-of-bounds <code>i</code> values be handled? </p> <ul> <li> <p><code>"error"</code> throws an error. </p> </li> <li> <p><code>"remove"</code> removes both positive and negative out-of-bounds locations. </p> </li> <li> <p><code>"extend"</code> allows positive out-of-bounds locations if they directly follow the end of a vector. This can be used to implement extendable vectors, like <code>letters[1:30]</code>. </p> </li></ul> </td></tr> <tr valign="top"><td><code>zero</code></td> <td> <p>How should zero <code>i</code> values be handled? </p> <ul> <li> <p><code>"error"</code> throws an error. </p> </li> <li> <p><code>"remove"</code> removes them. </p> </li> <li> <p><code>"ignore"</code> returns them as is. </p> </li></ul> </td></tr> </table> <h3>Value</h3> <ul> <li> <p><code>vec_as_location()</code> and <code>num_as_location()</code> return an integer vector that can be used as an index in a subsetting operation. </p> </li> <li> <p><code>vec_as_location2()</code> and <code>num_as_location2()</code> return an integer of size 1 that can be used a scalar index for extracting an element. </p> </li></ul> <h3>Examples</h3> <pre> x <- array(1:6, c(2, 3)) dimnames(x) <- list(c("r1", "r2"), c("c1", "c2", "c3")) # The most common use case validates row indices vec_as_location(1, vec_size(x)) # Negative indices can be used to index from the back vec_as_location(-1, vec_size(x)) # Character vectors can be used if `names` are provided vec_as_location("r2", vec_size(x), rownames(x)) # You can also construct an index for dimensions other than the first vec_as_location(c("c2", "c1"), ncol(x), colnames(x)) </pre> <hr /><div style="text-align: center;">[Package <em>vctrs</em> version 0.5.0 <a href="00Index.html">Index</a>]</div> </body></html>