-
Notifications
You must be signed in to change notification settings - Fork 255
/
pluck.Rd
116 lines (97 loc) · 3.6 KB
/
pluck.Rd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/pluck.R
\name{pluck}
\alias{pluck}
\alias{chuck}
\alias{pluck<-}
\title{Pluck or chuck a single element from a vector or environment}
\usage{
pluck(.x, ..., .default = NULL)
chuck(.x, ...)
pluck(.x, ...) <- value
}
\arguments{
\item{.x, x}{A vector or environment}
\item{...}{A list of accessors for indexing into the object. Can be
an positive integer, a negative integer (to index from the right),
a string (to index into names), 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.
\link[rlang:dyn-dots]{Dynamic dots} are supported. In particular, if
your accessors are stored in a list, you can splice that in with
\verb{!!!}.}
\item{.default}{Value to use if target is \code{NULL} or absent.}
\item{value}{A value to replace in \code{.x} at the pluck location.
Use \code{zap()} to instead remove the element.}
}
\description{
\code{pluck()} and \code{chuck()} implement a generalised form of \code{[[} that
allow you to index deeply and flexibly into data structures.
\code{pluck()} consistently returns \code{NULL} when an element does not
exist while \code{chuck()} always throws (or chucks) an error.
}
\details{
\itemize{
\item 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.
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} to \code{pluck(x, 1, accessor, "foo")}.
\item These accessors never partial-match. This is unlike \code{$} which
will select the \code{disp} object if you write \code{mtcars$di}.
}
}
\examples{
# 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)
# same as x[[1]]
# Index from the back
pluck(x, -1)
# same as x[[2]]
pluck(x, 1, 2)
# same as x[[1]][[2]]
# Supply names to index into named vectors:
pluck(x, 1, 2, "elt")
# same as 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)
# pluck() also supports accessor functions:
my_element <- function(x) x[[2]]$elt
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)
}
\seealso{
\code{\link[=attr_getter]{attr_getter()}} for creating attribute getters suitable
for use with \code{pluck()} and \code{chuck()}. \code{\link[=modify_in]{modify_in()}} for
applying a function to a pluck location.
}