feat: add combine arg to st_erase

R/st_erase.R

@@ -1,4 +1,4 @@
-#' Erase an area of a simple feature object
+#' Erase or trim geometry of a sf or sfc object
 #'
 #' This function extends [sf::st_difference()] by unioning the second parameter
 #' by default, checking validity of inputs, and optionally (when `flip = TRUE`)
@@ -7,14 +7,16 @@
 #'
 #' @param x A `sf`, `sfc`, or `bbox` object to erase or trim.
 #' @param y A `sf`, `sfc`, or `bbox` object to use to erase or trim.
-#' @param flip If `TRUE`, use st_intersection; if `FALSE` use st_difference,
-#'   Default: `FALSE`
-#' @param union If `TRUE`, use [sf::st_combine] and [sf::st_union] on y before
-#'   applying difference/intersection; defaults to `FALSE`.
+#' @param flip If `TRUE`, use [sf::st_intersection()] to "erase" geometry of x
+#'   that intersects y; if `FALSE` use [sf::st_difference()] to trim x to y
+#'   geometry, Default: `FALSE`.
+#' @param union If `TRUE`, use [sf::st_combine()] and [sf::st_union()] on y
+#'   before applying difference/intersection; defaults to `TRUE`.
 #' @inheritParams sf::st_difference
+#' @examples examples/st_erase.R
 #' @export
 #' @importFrom sf st_union st_combine st_intersection st_difference
-st_erase <- function(x, y, flip = FALSE, union = TRUE, ...) {
+st_erase <- function(x, y, flip = FALSE, union = TRUE, combine = FALSE, ...) {
   check_sf(x, ext = TRUE)
 
   if (is_bbox(x)) {
@@ -28,8 +30,12 @@ st_erase <- function(x, y, flip = FALSE, union = TRUE, ...) {
   y <- st_transform_ext(y, crs = x, class = "sfc")
 
   if (union) {
-    # FIXME: Is this identical to sf::st_union(sf::st_combine(y)) ?
-    y <- sf::st_combine(sf::st_union(y))
+    # FIXME: Is this identical to sf::st_combine(sf::st_union(y)) ?
+    if (combine) {
+      y <- sf::st_combine(y)
+    }
+
+    y <- sf::st_union(y)
   }
 
   y <- st_make_valid_ext(y)
@@ -44,12 +50,14 @@ st_erase <- function(x, y, flip = FALSE, union = TRUE, ...) {
 #' @rdname st_erase
 #' @name st_trim
 #' @export
-st_trim <- function(x, y, union = TRUE, ...) {
+st_trim <- function(x, y, union = TRUE, combine = FALSE, ...) {
   st_erase(
     x = x,
     y = y,
     flip = TRUE,
-    union = union
+    union = union,
+    combine = combine,
+    ...
   )
 }