thisisnic commented on a change in pull request #11915:
URL: https://github.com/apache/arrow/pull/11915#discussion_r773222241
##########
File path: r/vignettes/developers/bindings.Rmd
##########
@@ -0,0 +1,225 @@
+# Writing Bindings
+
+```{r, include=FALSE}
+library(arrow, warn.conflicts = FALSE)
+library(dplyr, warn.conflicts = FALSE)
+```
+
+When writing bindings between C++ compute functions and R functions, the aim
is
+to expose the C++ functionality via the same interface as existing R
functions. The syntax and
+functionality should match that of the existing R functions
+(though there are some exceptions) so that users are able to use existing
tidyverse
+or base R syntax, whilst taking advantage of the speed and functionality of
the
+underlying arrow package.
+
+One of main ways in which users interact with arrow is via
+[dplyr](https://dplyr.tidyverse.org/) syntax called on Arrow objects. For
+example, when a user calls `dplyr::mutate()` on an Arrow Tabular,
+Dataset, or arrow data query object, the Arrow implementation of `mutate()` is
+used and under the hood, translates the dplyr code into Arrow C++ code.
+
+When using `dplyr::mutate()` or `dplyr::filter()`, you may want to use
functions
+from other packages. The example below uses `stringr::str_detect()`.
+
+```{r}
+library(dplyr)
+library(stringr)
+starwars %>%
+ filter(str_detect(name, "Darth"))
+```
+This functionality has also been implemented in Arrow, e.g.:
+
+```{r}
+library(arrow)
+arrow_table(starwars) %>%
+ filter(str_detect(name, "Darth")) %>%
+ collect()
+```
+
+This is possible as a **binding** has been created between the call to the
+stringr function `str_detect()` and the Arrow C++ code, here as a direct
mapping
+to `match_substring_regex`. You can see this for yourself by inspecting the
+arrow data query object without retrieving the results via `collect()`.
+
+
+```{r}
+arrow_table(starwars) %>%
+ filter(str_detect(name, "Darth"))
+```
+
+In the following sections, we'll walk through how to create a binding between
an
+R function and an Arrow C++ function.
+
+# Walkthrough
+
+Imagine you are writing the bindings for the C++ function
+[`starts_with()`](https://arrow.apache.org/docs/cpp/compute.html#containment-tests)
+and want to bind it to the (base) R function `startsWith()`.
+
+First, take a look at the docs for both of those functions.
+
+## Examining the R function
+
+Here are the docs for R's `startsWith()` (also available at
https://stat.ethz.ch/R-manual/R-devel/library/base/html/startsWith.html)
+
+```{r, echo=FALSE, out.width="50%"}
+knitr::include_graphics("./startswithdocs.png")
+```
Review comment:
I agree with "least bad" - would be happy to cut it out entirely if
anyone suggests another approach to conveying this information that works
better!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
