Strict pluck #482

NAMESPACE

@@ -39,6 +39,7 @@ export(as_vector)
 export(at_depth)
 export(attr_getter)
 export(auto_browse)
+export(chuck)
 export(compact)
 export(compose)
 export(cross)

NEWS.md

@@ -64,6 +64,10 @@ reduce2_right(.x = letters[1:4], .y = paste2, .f = c("-", ".", "-")) # working
 
 ## Minor improvements and fixes
 
+* New `chuck()` function. This is a strict variant of `pluck()` that
+  throws errors when an element does not exist instead of returning
+  `NULL` (@daniel-barnett, #482).
+
 * The tibble package is now in Suggests rather than Imports. This
   brings the hard dependency of purrr to just rlang and magrittr.
 

R/pluck.R

@@ -1,32 +1,9 @@
-#' Pluck out a single element from a vector or environment
+#' Pluck or chuck a single element from a vector or environment
 #'
-#' @description
-#'
-#' This is a generalised form of `[[` which allows you to index deeply
-#' and flexibly into data structures. It supports R 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.
-#'
-#' `pluck()` 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 `pluck(x, 1,
-#' accessor, "foo")`.
-#'
-#' Furthermore, `pluck()` never partial-matches unlike `$` which will
-#' select the `disp` object if you write `mtcars$di`.
-#'
-#' `attr_getter()` generates an attribute accessor function;
-#' i.e., it generates a function for extracting an attribute with
-#' a given name. Unlike the base R `attr()` function with default
-#' options, it doesn't use partial matching.
-#'
-#' @details
-#'
-#' Since it handles arbitrary accessor functions, `pluck()` is a type
-#' of composition operator. However, it is indexing-oriented thanks to
-#' its handling of strings and integers. By the same token is also
-#' explicit regarding the intent of the composition (e.g. extraction).
+#' `pluck()` and `chuck()` implement a generalised form of `[[` that
+#' allow you to index deeply and flexibly into data structures.
+#' `pluck()` consistently returns `NULL` when an element does not
+#' exist, `chuck()` always throws an error in that case.
 #'
 #' @param .x A vector or environment
 #' @param ... A list of accessors for indexing into the object. Can be
@@ -38,8 +15,24 @@
 #'   particular, if your accessors are stored in a list, you can
 #'   splice that in with `!!!`.
 #' @param .default Value to use if target is empty or absent.
-#' @keywords internal
-#' @export
+#'
+#' @details
+#' * 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 `pluck(x, 1,
+#'   accessor, "foo")`.
+#'
+#' * These accessors never partial-match. This is unlike `$` which
+#'   will select the `disp` object if you write `mtcars$di`.
+#'
+#'
+#' @seealso [attr_getter()] for creating attribute getters suitable
+#'   for use with `pluck()` and `chuck()`.
 #' @examples
 #' # pluck() supports integer positions, string names, and functions.
 #' # Using functions, you can easily extend pluck(). Let's create a
@@ -61,30 +54,57 @@
 #' # 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)
+#' @export
+pluck <- function(.x, ..., .default = NULL) {
+  .Call(
+    pluck_impl,
+    x = .x,
+    index = list2(...),
+    missing = .default,
+    strict = FALSE
+  )
+}
+#' @rdname pluck
+#' @export
+chuck <- function(.x, ...) {
+  .Call(
+    pluck_impl,
+    x = .x,
+    index = list2(...),
+    missing = NULL,
+    strict = TRUE
+  )
+}
+
+#' Create an attribute getter function
+#'
+#' `attr_getter()` generates an attribute accessor function; i.e., it
+#' generates a function for extracting an attribute with a given
+#' name. Unlike the base R `attr()` function with default options, it
+#' doesn't use partial matching.
+#'
+#' @param attr An attribute name as string.
 #'
-#' # This technique is used for plucking into attributes with
-#' # attr_getter(). It takes an attribute name and returns a function
-#' # to access the attribute:
+#' @seealso [pluck()]
+#' @examples
+#' # attr_getter() takes an attribute name and returns a function to
+#' # access the attribute:
+#' get_rownames <- attr_getter("row.names")
+#' get_rownames(mtcars)
+#'
+#' # These getter functions are handy in conjunction with pluck() for
+#' # extracting deeply into a data structure. Here we'll first
+#' # extract by position, then by attribute:
 #' obj1 <- structure("obj", obj_attr = "foo")
 #' obj2 <- structure("obj", obj_attr = "bar")
 #' x <- list(obj1, obj2)
 #'
-#' # pluck() is handy for extracting deeply into a data structure.
-#' # Here we'll first extract by position, then by attribute:
 #' pluck(x, 1, attr_getter("obj_attr"))  # From first object
 #' pluck(x, 2, attr_getter("obj_attr"))  # From second object
-#'
-#'
-#' # If you have a list of accessors, you can splice those in with `!!!`:
-#' idx <- list(1, attr_getter("obj_attr"))
-#' pluck(x, !!!idx)
-pluck <- function(.x, ..., .default = NULL) {
-  .Call(extract_impl, .x, list2(...), .default)
-}
-
 #' @export
-#' @rdname pluck
-#' @param attr An attribute name as string.
 attr_getter <- function(attr) {
   force(attr)
   function(x) attr(x, attr, exact = TRUE)