From 29f284600d98eaeed484c14afdf9bae40b34b427 Mon Sep 17 00:00:00 2001
From: your name <eli.pousson@gmail.com>
Date: Thu, 14 Sep 2023 21:15:57 -0400
Subject: [PATCH] docs: add st_erase example

---
 R/st_erase.R        |  2 +-
 examples/st_erase.R | 19 +++++++++++++++++++
 man/st_erase.Rd     | 36 +++++++++++++++++++++++++++++-------
 3 files changed, 49 insertions(+), 8 deletions(-)
 create mode 100644 examples/st_erase.R

diff --git a/R/st_erase.R b/R/st_erase.R
index 639e1ae..384919d 100644
--- a/R/st_erase.R
+++ b/R/st_erase.R
@@ -13,7 +13,7 @@
 #' @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
+#' @example examples/st_erase.R
 #' @export
 #' @importFrom sf st_union st_combine st_intersection st_difference
 st_erase <- function(x, y, flip = FALSE, union = TRUE, combine = FALSE, ...) {
diff --git a/examples/st_erase.R b/examples/st_erase.R
new file mode 100644
index 0000000..67fb27d
--- /dev/null
+++ b/examples/st_erase.R
@@ -0,0 +1,19 @@
+nc <- read_sf_ext(system.file("shape/nc.shp", package = "sf"))
+
+nc <- st_transform_ext(nc, 3657)
+
+plot(
+  st_erase(
+    st_buffer(nc[1, ], 1000),
+    nc[1, ]
+  ),
+  max.plot = 1
+)
+
+plot(
+  st_trim(
+    nc,
+    st_buffer(nc[1, ], 2000)
+  ),
+  max.plot = 1
+)
diff --git a/man/st_erase.Rd b/man/st_erase.Rd
index 6cf29d0..cd4131d 100644
--- a/man/st_erase.Rd
+++ b/man/st_erase.Rd
@@ -3,22 +3,23 @@
 \name{st_erase}
 \alias{st_erase}
 \alias{st_trim}
-\title{Erase an area of a simple feature object}
+\title{Erase or trim geometry of a sf or sfc object}
 \usage{
-st_erase(x, y, flip = FALSE, union = TRUE, ...)
+st_erase(x, y, flip = FALSE, union = TRUE, combine = FALSE, ...)
 
-st_trim(x, y, union = TRUE, ...)
+st_trim(x, y, union = TRUE, combine = FALSE, ...)
 }
 \arguments{
 \item{x}{A \code{sf}, \code{sfc}, or \code{bbox} object to erase or trim.}
 
 \item{y}{A \code{sf}, \code{sfc}, or \code{bbox} object to use to erase or trim.}
 
-\item{flip}{If \code{TRUE}, use st_intersection; if \code{FALSE} use st_difference,
-Default: \code{FALSE}}
+\item{flip}{If \code{TRUE}, use \code{\link[sf:geos_binary_ops]{sf::st_intersection()}} to "erase" geometry of x
+that intersects y; if \code{FALSE} use \code{\link[sf:geos_binary_ops]{sf::st_difference()}} to trim x to y
+geometry, Default: \code{FALSE}.}
 
-\item{union}{If \code{TRUE}, use \link[sf:geos_combine]{sf::st_combine} and \link[sf:geos_combine]{sf::st_union} on y before
-applying difference/intersection; defaults to \code{FALSE}.}
+\item{union}{If \code{TRUE}, use \code{\link[sf:geos_combine]{sf::st_combine()}} and \code{\link[sf:geos_combine]{sf::st_union()}} on y
+before applying difference/intersection; defaults to \code{TRUE}.}
 
 \item{...}{arguments passed on to \link[s2]{s2_options}}
 }
@@ -28,3 +29,24 @@ by default, checking validity of inputs, and optionally (when \code{flip = TRUE}
 using \code{\link[sf:geos_binary_ops]{sf::st_intersection()}} instead of \link[sf:geos_binary_ops]{sf::st_difference}. \code{\link[=st_trim]{st_trim()}} is
 equivalent to \code{\link[=st_erase]{st_erase()}} with flip set to \code{TRUE}.
 }
+\examples{
+nc <- read_sf_ext(system.file("shape/nc.shp", package = "sf"))
+
+nc <- st_transform_ext(nc, 3657)
+
+plot(
+  st_erase(
+    st_buffer(nc[1, ], 1000),
+    nc[1, ]
+  ),
+  max.plot = 1
+)
+
+plot(
+  st_trim(
+    nc,
+    st_buffer(nc[1, ], 2000)
+  ),
+  max.plot = 1
+)
+}