EVOLUTION-MANAGER
Edit File: vec_chop.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: Chopping</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_chop {vctrs}"><tr><td>vec_chop {vctrs}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Chopping</h2> <h3>Description</h3> <ul> <li> <p><code>vec_chop()</code> provides an efficient method to repeatedly slice a vector. It captures the pattern of <code>map(indices, vec_slice, x = x)</code>. When no indices are supplied, it is generally equivalent to <code><a href="../../base/html/list.html">as.list()</a></code>. </p> </li> <li> <p><code>list_unchop()</code> combines a list of vectors into a single vector, placing elements in the output according to the locations specified by <code>indices</code>. It is similar to <code><a href="vec_c.html">vec_c()</a></code>, but gives greater control over how the elements are combined. When no indices are supplied, it is identical to <code>vec_c()</code>, but typically a little faster. </p> </li></ul> <p>If <code>indices</code> selects every value in <code>x</code> exactly once, in any order, then <code>list_unchop()</code> is the inverse of <code>vec_chop()</code> and the following invariant holds: </p> <div class="sourceCode"><pre>list_unchop(vec_chop(x, indices), indices) == x </pre></div> <h3>Usage</h3> <pre> vec_chop(x, indices = NULL) list_unchop( x, ..., indices = NULL, ptype = NULL, name_spec = NULL, name_repair = c("minimal", "unique", "check_unique", "universal", "unique_quiet", "universal_quiet"), error_arg = "x", error_call = current_env() ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x</code></td> <td> <p>A vector</p> </td></tr> <tr valign="top"><td><code>indices</code></td> <td> <p>For <code>vec_chop()</code>, a list of positive integer vectors to slice <code>x</code> with, or <code>NULL</code>. If <code>NULL</code>, <code>x</code> is split into its individual elements, equivalent to using an <code>indices</code> of <code>as.list(vec_seq_along(x))</code>. </p> <p>For <code>list_unchop()</code>, a list of positive integer vectors specifying the locations to place elements of <code>x</code> in. Each element of <code>x</code> is recycled to the size of the corresponding index vector. The size of <code>indices</code> must match the size of <code>x</code>. If <code>NULL</code>, <code>x</code> is combined in the order it is provided in, which is equivalent to using <code><a href="vec_c.html">vec_c()</a></code>.</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>ptype</code></td> <td> <p>If <code>NULL</code>, the default, the output type is determined by computing the common type across all elements of <code>x</code>. Alternatively, you can supply <code>ptype</code> to give the output a known type.</p> </td></tr> <tr valign="top"><td><code>name_spec</code></td> <td> <p>A name specification for combining inner and outer names. This is relevant for inputs passed with a name, when these inputs are themselves named, like <code>outer = c(inner = 1)</code>, or when they have length greater than 1: <code>outer = 1:2</code>. By default, these cases trigger an error. You can resolve the error by providing a specification that describes how to combine the names or the indices of the inner vector with the name of the input. This specification can be: </p> <ul> <li><p> A function of two arguments. The outer name is passed as a string to the first argument, and the inner names or positions are passed as second argument. </p> </li> <li><p> An anonymous function as a purrr-style formula. </p> </li> <li><p> A glue specification of the form <code>"{outer}_{inner}"</code>. </p> </li> <li><p> An <code><a href="../../rlang/html/zap.html">rlang::zap()</a></code> object, in which case both outer and inner names are ignored and the result is unnamed. </p> </li></ul> <p>See the <a href="name_spec.html">name specification topic</a>.</p> </td></tr> <tr valign="top"><td><code>name_repair</code></td> <td> <p>How to repair names, see <code>repair</code> options in <code><a href="vec_as_names.html">vec_as_names()</a></code>.</p> </td></tr> <tr valign="top"><td><code>error_arg</code></td> <td> <p>An argument name as a string. This argument will be mentioned in error messages as the input that is at the origin of a problem.</p> </td></tr> <tr valign="top"><td><code>error_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>Value</h3> <ul> <li> <p><code>vec_chop()</code>: A list of size <code>vec_size(indices)</code> or, if <code>indices == NULL</code>, <code>vec_size(x)</code>. </p> </li> <li> <p><code>list_unchop()</code>: A vector of type <code>vec_ptype_common(!!!x)</code>, or <code>ptype</code>, if specified. The size is computed as <code>vec_size_common(!!!indices)</code> unless the indices are <code>NULL</code>, in which case the size is <code>vec_size_common(!!!x)</code>. </p> </li></ul> <h3>Dependencies of <code>vec_chop()</code></h3> <ul> <li> <p><code><a href="vec_slice.html">vec_slice()</a></code> </p> </li></ul> <h3>Dependencies of <code>list_unchop()</code></h3> <ul> <li> <p><code><a href="vec_c.html">vec_c()</a></code> </p> </li></ul> <h3>Examples</h3> <pre> vec_chop(1:5) vec_chop(1:5, list(1, 1:2)) vec_chop(mtcars, list(1:3, 4:6)) # If `indices` selects every value in `x` exactly once, # in any order, then `list_unchop()` inverts `vec_chop()` x <- c("a", "b", "c", "d") indices <- list(2, c(3, 1), 4) vec_chop(x, indices) list_unchop(vec_chop(x, indices), indices = indices) # When unchopping, size 1 elements of `x` are recycled # to the size of the corresponding index list_unchop(list(1, 2:3), indices = list(c(1, 3, 5), c(2, 4))) # Names are retained, and outer names can be combined with inner # names through the use of a `name_spec` lst <- list(x = c(a = 1, b = 2), y = 1) list_unchop(lst, indices = list(c(3, 2), c(1, 4)), name_spec = "{outer}_{inner}") # An alternative implementation of `ave()` can be constructed using # `vec_chop()` and `list_unchop()` in combination with `vec_group_loc()` ave2 <- function(.x, .by, .f, ...) { indices <- vec_group_loc(.by)$loc chopped <- vec_chop(.x, indices) out <- lapply(chopped, .f, ...) list_unchop(out, indices = indices) } breaks <- warpbreaks$breaks wool <- warpbreaks$wool ave2(breaks, wool, mean) identical( ave2(breaks, wool, mean), ave(breaks, wool, FUN = mean) ) </pre> <hr /><div style="text-align: center;">[Package <em>vctrs</em> version 0.5.0 <a href="00Index.html">Index</a>]</div> </body></html>