EVOLUTION-MANAGER
Edit File: pluck.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: Pluck or chuck a single element from a vector or environment</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 pluck {purrr}"><tr><td>pluck {purrr}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Pluck or chuck a single element from a vector or environment</h2> <h3>Description</h3> <p><code>pluck()</code> and <code>chuck()</code> implement a generalised form of <code>[[</code> that allow you to index deeply and flexibly into data structures. <code>pluck()</code> consistently returns <code>NULL</code> when an element does not exist, <code>chuck()</code> always throws an error in that case. </p> <h3>Usage</h3> <pre> pluck(.x, ..., .default = NULL) chuck(.x, ...) pluck(.x, ...) <- value </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>.x, x</code></td> <td> <p>A vector or environment</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>A list of accessors for indexing into the object. Can be an integer position, a string name, or an accessor function (except for the assignment variants which only support names and positions). If the object being indexed is an S4 object, accessing it by name will return the corresponding slot. </p> <p>These dots support <a href="../../rlang/html/list2.html">tidy dots</a> features. In particular, if your accessors are stored in a list, you can splice that in with <code style="white-space: pre;">!!!</code>.</p> </td></tr> <tr valign="top"><td><code>.default</code></td> <td> <p>Value to use if target is empty or absent.</p> </td></tr> <tr valign="top"><td><code>value</code></td> <td> <p>A value to replace in <code>.x</code> at the pluck location.</p> </td></tr> </table> <h3>Details</h3> <ul> <li><p> You can pluck or chuck with standard accessors like integer positions and string names, and also accepts arbitrary accessor functions, i.e. functions that take an object and return some internal piece. </p> <p>This is often more readable than a mix of operators and accessors because it reads linearly and is free of syntactic cruft. Compare: <code>accessor(x[[1]])$foo</code> to <code>pluck(x, 1, accessor, "foo")</code>. </p> </li> <li><p> These accessors never partial-match. This is unlike <code>$</code> which will select the <code>disp</code> object if you write <code>mtcars$di</code>. </p> </li></ul> <h3>See Also</h3> <p><code><a href="attr_getter.html">attr_getter()</a></code> for creating attribute getters suitable for use with <code>pluck()</code> and <code>chuck()</code>. <code><a href="modify_in.html">modify_in()</a></code> for applying a function to a pluck location. </p> <h3>Examples</h3> <pre> # Let's create a list of data structures: obj1 <- list("a", list(1, elt = "foo")) obj2 <- list("b", list(2, elt = "bar")) x <- list(obj1, obj2) # pluck() provides a way of retrieving objects from such data # structures using a combination of numeric positions, vector or # list names, and accessor functions. # Numeric positions index into the list by position, just like `[[`: pluck(x, 1) x[[1]] pluck(x, 1, 2) x[[1]][[2]] # Supply names to index into named vectors: pluck(x, 1, 2, "elt") x[[1]][[2]][["elt"]] # By default, pluck() consistently returns `NULL` when an element # does not exist: pluck(x, 10) try(x[[10]]) # You can also supply a default value for non-existing elements: pluck(x, 10, .default = NA) # If you prefer to consistently fail for non-existing elements, use # the opinionated variant chuck(): chuck(x, 1) try(chuck(x, 10)) try(chuck(x, 1, 10)) # The map() functions use pluck() by default to retrieve multiple # values from a list: map(x, 2) # Pass multiple indexes with a list: map(x, list(2, "elt")) # This is equivalent to: map(x, pluck, 2, "elt") # You can also supply a default: map(x, list(2, "elt", 10), .default = "superb default") # Or use the strict variant: try(map(x, chuck, 2, "elt", 10)) # You can also assign a value in a pluck location with pluck<-: pluck(x, 2, 2, "elt") <- "quuux" x # This is a shortcut for the prefix function assign_in(): y <- assign_in(x, list(2, 2, "elt"), value = "QUUUX") y # pluck() also supports accessor functions: my_element <- function(x) x[[2]]$elt # The accessor can then be passed to pluck: pluck(x, 1, my_element) pluck(x, 2, my_element) # Even for this simple data structure, this is more readable than # the alternative form because it requires you to read both from # right-to-left and from left-to-right in different parts of the # expression: my_element(x[[1]]) # If you have a list of accessors, you can splice those in with `!!!`: idx <- list(1, my_element) pluck(x, !!!idx) </pre> <hr /><div style="text-align: center;">[Package <em>purrr</em> version 0.3.4 <a href="00Index.html">Index</a>]</div> </body></html>