dragosmg commented on a change in pull request #11915:
URL: https://github.com/apache/arrow/pull/11915#discussion_r766703443
##########
File path: r/vignettes/developers/bindings.Rmd
##########
@@ -0,0 +1,189 @@
+When writing bindings between C++ compute functions and R functions, the aim
is
+to expose the C++ functionality via existing R functions. The syntax and
+functionality should (usually) exactly match that of the existing R functions
+(though with some exceptions) so that users are able to use existing tidyverse
+or base R syntax, or call existing S3 methods on objects, whilst taking
+advantage of the speed and functionality of the underlying arrow package.
+
+# Implementing bindings for S3 generics
+
+# Implementing bindings to work within dplyr pipelines
+
+One of main ways in which users interact with arrow is via dplyr 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, e.g.
+
+```{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 stringr function
+`str_detect()` and the Arrow C++ function `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, let's take a look at the docs for both of those functions.
+
+First, here’s 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")
+```
+
+It takes 2 parameters; `x` - the input, and `prefix` - the characters to check
+if `x` starts with.
+
+Now, let’s go to
+[the compute function
documentation](https://arrow.apache.org/docs/cpp/compute.html#containment-tests)
+and look for the Arrow C++ library’s `starts_with()` function:
+
+```{r, echo=FALSE, out.width="50%"}
+knitr::include_graphics("./starts_with_docs.png")
+```
+We can see that `starts_with()` is a unary function, which means that it takes
a
+single data input. The data input must be a string-like class, and the
returned
+value is boolean, both of which match up to R’s `startsWith()`.
+
+There is an options class associated with `starts_with()` - called
[`MatchSubstringOptions`](https://arrow.apache.org/docs/cpp/api/compute.html#_CPPv4N5arrow7compute21MatchSubstringOptionsE)
+- so let’s take a look at that.
+
+```{r, echo=FALSE, out.width="50%"}
+knitr::include_graphics("./matchsubstringoptions.png")
+```
+
+Options classes allow the user to control the behaviour of the function. In
+this case, there are two possible options which can be supplied - `pattern`
and
+`ignore_case`, which are described in the docs shown above.
+
+What conclusions can be drawn from what we’ve seen so far?
+
+Base R’s `startsWith()` and Arrow’s `starts_with()` operate on equivalent data
+types, return equivalent data types, and as there are no options implemented
in
Review comment:
_Options_ are the _arguments_ in R speak?
--
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]
