build_quarto_site(unfreeze = TRUE) for release 1.1.9

_freeze/analysis/using-Rcpp/execute-results/html.json

@@ -3,9 +3,7 @@
   "result": {
     "engine": "knitr",
     "markdown": "---\ntitle: \"Using Rcpp\"\nauthor: \"John Benninghoff\"\ndate: '2023-12-21'\nfile-modified: '2023-12-31'\ncategories: notes\norder: 104\noutput:\n  html_notebook:\n    theme:\n      version: 5\n      preset: bootstrap\n    css: assets/extra.css\n    pandoc_args: --shift-heading-level-by=1\n    toc: yes\n    toc_float:\n      collapsed: no\n      smooth_scroll: no\n---\n\n\nNotes on using [Rcpp](https://www.rcpp.org) to implement [Poker-Hand-Evaluator](https://github.com/HenryRLee/PokerHandEvaluator) in the [cards](https://jabenninghoff.github.io/cards/) package.\n\n\n::: {.cell}\n\n```{.r .cell-code}\n# no libraries\n```\n:::\n\n\n# Background\n\nRcpp provides an interface to C++, which allows\n[rewriting R code in C++](https://adv-r.hadley.nz/rcpp.html) to improve performance. The cards\npackage implements functions that simulate dealing and evaluating poker hands in R and PH Evaluator\nusing python via [reticulate](https://rstudio.github.io/reticulate/). Will the C++ version of PH\nEvaluator be faster?\n\nThe [Thirteen Simple Steps for Creating An R Package with an External C++ Library](https://CRAN.R-project.org/package=Rcpp/vignettes/Rcpp-libraries.pdf)\nvignette provides good high-level guidance on integrating a C++ library into an R package using base\nR; additional work is needed to implement Rcpp using roxygen2. The source code for the\n[Corels](https://CRAN.R-project.org/package=corels) package referenced in the vignette can be found\non GitHub: <https://github.com/corels/rcppcorels>.\n\n# Test Build\n\nTo start, I followed PH Evaluator's\n[instructions](https://github.com/HenryRLee/PokerHandEvaluator/tree/master/cpp) to build and test\nthe `pheval` library, which required installation of `cmake` using Homebrew (`brew install cmake`).\n\n# Example Function\n\nAs a next step, I implemented a simple example function to ensure Rcpp was working properly. After\nsome research, I added the following code:\n\n```cpp\n#include <Rcpp.h>\nusing namespace Rcpp;\n\n//' Leading NA\n//'\n//' This function returns a logical vector identifying if\n//' there are leading NA, marking the leading NAs as TRUE and\n//' everything else as FALSE.\n//'\n//' Code from [Rcpp and Roxygen2](https://www.r-bloggers.com/2016/08/rcpp-and-roxygen2/).\n//'\n//' Installed with help from [usethis::use_rcpp()] and roxygen2 instructions on\n//'   [Rcpp](https://roxygen2.r-lib.org/articles/roxygen2.html#rcpp).\n//'\n//' Steps to install:\n//'\n//' 1. Create `src/leading_na.cpp` (this file)\n//' 1. Run [usethis::use_rcpp()], add `@importFrom Rcpp sourceCpp` and\n//'    `@useDynLib cards, .registration = TRUE` to `package.R` as directed\n//' 1. Run [desc::desc_normalize()] and [devtools::document()]\n//'\n//' @param x An integer vector\n//' @export\n// [[Rcpp::export]]\nLogicalVector leading_na(IntegerVector x) {\n  int n = x.size();\n  LogicalVector leading_na(n);\n\n  int i = 0;\n  while((i < n) &&(x[i] == NA_INTEGER)) {\n    leading_na[i] = TRUE;\n    i++;\n  }\n  return leading_na;\n}\n```\n\nAfter the first two steps,\n[`devtools::document()`](https://devtools.r-lib.org/reference/document.html) automates the addition\nof the `leading_na()` function, R documentation, and Rcpp support to the package.\n\n# Stub Function\n\nAs a next step, I implemented a stub function with help from\n[Rcpp for everyone](https://teuder.github.io/rcpp4everyone_en/), specifically the chapter on\n[Data types](https://teuder.github.io/rcpp4everyone_en/070_data_types.html):\n\n```cpp\n#include <Rcpp.h>\nusing namespace Rcpp;\n\n//' Evaluate a poker hand using PH Evaluator\n//'\n//' Evaluate the rank category of a five card poker hand using\n//'   [PH Evaluator](https://github.com/HenryRLee/PokerHandEvaluator).\n//'\n//' Currently implemented as a stub function that always returns \"poker_hand\".\n//'\n//' @return string hand rank\n//' @export\n// [[Rcpp::export]]\nString eval_hand_phe() {\n  return \"poker_hand\";\n}\n```\n\nThe stub works, and suggests an approach for a first implementation using Rcpp: create a function\nthat calls `phevaluator::EvaluateCards()` and returns a string based on `Rank.category()` or\n`Rank.describeCategory`, following\n[`cpp_example.cc`](https://github.com/HenryRLee/PokerHandEvaluator/blob/master/cpp/examples/cpp_example.cc). A more complete implementation would use\n[Rcpp Modules](https://CRAN.R-project.org/package=Rcpp/vignettes/Rcpp-modules.pdf) to expose\nthe C++ classes and methods in PH Evaluator, with help from the\n[RcppStudent](https://github.com/coatless-r-n-d/rcpp-modules-student) R package.\n\nAdditional examples implementing C++ libraries in Rcpp I found include\n[RcppAnnoy](https://github.com/eddelbuettel/rcppannoy), written by Rcpp author and maintainer Dirk\nEddelbuettel, [rxylib](https://github.com/R-Lum/rxylib), and\n[RcppSundials](https://github.com/AleMorales/RcppSundials.R).\n\n## Add Headers\n\nTo start the first implementation, I added the headers from `cpp_example.cc`:\n\n```cpp\n#include <Rcpp.h>\nusing namespace Rcpp;\n\n#include <phevaluator/phevaluator.h>\n#include <iostream>\n#include <cassert>\n\n//' Evaluate a poker hand using PH Evaluator\n//'\n//' Evaluate the rank category of a five card poker hand using\n//'   [PH Evaluator](https://github.com/HenryRLee/PokerHandEvaluator).\n//'\n//' Implemented following\n//'   [`cpp_example.cc`](https://github.com/HenryRLee/PokerHandEvaluator/blob/master/cpp/examples/cpp_example.cc)\n//'   and [RcppAnnoy](https://github.com/eddelbuettel/rcppannoy).\n//'\n//' Currently implemented as a stub function that always returns \"poker_hand\".\n//'\n//' @param hand a hand of cards (an integer vector of length 5).\n//' @return string hand rank.\n//' @export\n// [[Rcpp::export]]\nString eval_hand_phe(IntegerVector hand) {\n  // phevaluator::Rank rank = phevaluator::EvaluateCards(hand[0], hand[1], hand[2], hand[3], hand[4]);\n  // return rank.describeCategory();\n  return \"poker_hand\";\n}\n```\n\nTo get the updated code to compile, I had to add `src/Makevars`, which I copied from RcppAnnoy, and\nalso added the `cpp/include` directory from PH Evaluator to `inst/`.\n\n`src/Makevars`:\n\n```Makefile\nPKG_CPPFLAGS = -I../inst/include/\n```\n\nWhile this code compiled, to get the commented code working, I'd need to add the code from\n`cpp/src`. Just dumping the files from PH Evaluator into `src/` didn't work, but the rxylib\n[`Makevars`](https://github.com/R-Lum/rxylib/blob/master/src/Makevars) file offered a clue: adapt\nthe [`Makefile`](https://github.com/HenryRLee/PokerHandEvaluator/blob/master/cpp/Makefile) from PH\nEvaluator to the R `Makevars` format to properly build the library objects. Put another way, follow\nhow rxylib translated\n[`xlib/Makefile.am`](https://github.com/wojdyr/xylib/blob/master/xylib/Makefile.am) to `Makevars`.\nThe Stack Overflow\n[question](https://stackoverflow.com/questions/43597632/understanding-the-contents-of-the-makevars-file-in-r-macros-variables-r-ma)\nreferenced in rxylib provided additional details on the `Makevars` file format.\n\n# Full Implementation\n\nAfter some experimentation, I added the following files from PH Evaluator's `cpp/src` to `src/`:\n\n```\n7462.c\ndptables.c\nevaluator5.c\nevaluator5.cc\nhash.c\nhash.h\nhashtable.c\nhashtable5.c\nrank.c\ntables.h\ntables_bitwise.c\n```\n\nThese were the minimal files needed to support the first implementation, which only had to support\nevaluation of 5 card hands.\n\nI also added a line to `src/Makevars` to enable the C++ 17 standard used by PH Evaluator:\n\n```Makefile\nPKG_CPPFLAGS = -I../inst/include/\nCXX_STD = CXX17\n```\n\nThis *nearly* compiled, but failed with an error:\n\n```\n   duplicate symbol '_evaluate_5cards' in:\n       /Users/agamemnon/GitHub/cards/src/evaluator5.o\n       /Users/agamemnon/GitHub/cards/src/evaluator5.o\n```\n\nUltimately this error was the result of two files with the same name but different file extensions\n(`evaluator5.c` and `evaluator5.cc`). Renaming `evaluator5.c` to `evaluator_5_c.c` fixed the issue,\nand the code below compiled and tested properly!\n\n```cpp\n#include <Rcpp.h>\nusing namespace Rcpp;\n\n#include <phevaluator/phevaluator.h>\n#include <iostream>\n#include <cassert>\n\n//' Evaluate a poker hand using PH Evaluator\n//'\n//' Evaluate the rank category of a five card poker hand using\n//'   [PH Evaluator](https://github.com/HenryRLee/PokerHandEvaluator).\n//'\n//' Implemented following\n//'   [Rcpp-libraries](https://cran.r-project.org/web/packages/Rcpp/vignettes/Rcpp-libraries.pdf),\n//'   PH Evaluator\n//'   [`cpp_example.cc`](https://github.com/HenryRLee/PokerHandEvaluator/blob/master/cpp/examples/cpp_example.cc),\n//'   and [RcppAnnoy](https://github.com/eddelbuettel/rcppannoy), with help from\n//'   R-Bloggers [Rcpp and Roxygen2](https://www.r-bloggers.com/2016/08/rcpp-and-roxygen2/),\n//'   [usethis::use_rcpp()], roxygen2 instructions on\n//'   [Rcpp](https://roxygen2.r-lib.org/articles/roxygen2.html#rcpp),\n//'   [Rcpp for everyone](https://teuder.github.io/rcpp4everyone_en/), the rxylib\n//'   [`Makefile`](https://github.com/R-Lum/rxylib/blob/master/src/Makevars) and\n//'   [Stack Overflow](https://stackoverflow.com/questions/43597632/understanding-the-contents-of-the-makevars-file-in-r-macros-variables-r-ma).\n//'\n//' `eval_hand_phe` returns one of the rank categories \"Straight Flush\", \"Four of a Kind\",\n//'   \"Full House\", \"Flush\", \"Straight\", \"Three of a Kind\", \"Two Pair\", \"One Pair\", or \"High Card\".\n//'\n//' \"Royal Flush\" and \"Jacks or Better\" are not currently supported.\n//'\n//' @param hand a hand of cards (an integer vector of length 5).\n//' @return string hand rank.\n//' @examples\n//' hand <- deal_hand(new_deck())\n//' print_hand(hand)\n//' eval_hand_phe(hand)\n//' @export\n// [[Rcpp::export]]\nString eval_hand_phe(IntegerVector hand) {\n  phevaluator::Rank rank = phevaluator::EvaluateCards(hand[0], hand[1], hand[2], hand[3], hand[4]);\n  return rank.describeCategory();\n}\n```\n\nAfter this, I removed the example function, added a C/C++ benchmark, and published cards 0.3.0.\n\n## Follow-up\n\nI did some additional research, and there doesn't seem to be a simple way to change R to compile using `filename.cc.o` instead of `filename.o`, as it goes against the intent of the R developers,\nas described in this Stack Overflow\n[article](https://stackoverflow.com/questions/23414448/r-makevars-file-to-overwrite-r-cmds-default-g-options):\n\n> The clear recommendation on r-devel (please check the archives) is that you should avoid Makefile\nlogic if you can. IIRC this echoed in the Writing R Extension manual.\n\nSo, it seems the right answer is to rename the files to avoid this conflict. Additionally, after\nreading a tidyverse blog post on\n[New CRAN requirements for packages with C and C++](https://www.tidyverse.org/blog/2023/03/cran-checks-compiled-code/),\nI learned that the R C++ standard was now C++17, so I technically did not need that line in the\n`Makevars` file, but I decided to keep it as it was an upstream requirement.\n\nI also discovered an example [package](https://github.com/coatless-r-n-d/rcpp-headers-subdirs) that\nexplained how to put code in a subdirectory of `src/`, which I plan to use for the second version\nusing Rcpp Modules.\n\nI later added a script to copy (or update) the PH Evaluator source and header files to the cards\npackage, to automate future updates if needed.\n\nAfter reading through the\n[Creating R Packages](https://rstudio.github.io/r-manuals/r-exts/Creating-R-packages.html) chapter\nof [Writing R Extensions](https://rstudio.github.io/r-manuals/r-exts/) and evaluating my options,\nI am inclined to use a simple approach to creating a \"phevaluator\" package, copying the necessary\nfiles into `src/` (with a shell script for reproducibility), use a minimal `Makevars` file, and use\n[Rcpp Modules](https://CRAN.R-project.org/package=Rcpp/vignettes/Rcpp-modules.pdf) to expose\nthe C++ classes and methods in PH Evaluator, following the approach used by the\n[RcppStudent](https://github.com/coatless-r-n-d/rcpp-modules-student) R package.\n",
-    "supporting": [
-      "using-Rcpp_files"
-    ],
+    "supporting": [],
     "filters": [
       "rmarkdown/pagebreak.lua"
     ],

_freeze/index/execute-results/html.json

@@ -1,6 +1,7 @@
 {
   "hash": "563e23491bddd6a987c17ff03600d6b1",
   "result": {
+    "engine": "knitr",
     "markdown": "---\ntitle: \"rtraining\"\nlisting:\n  type: default\n  contents: analysis\n  sort-ui: true\n  filter-ui: true\n  max-description-length: 500\n  date-format: iso\n  categories: true\n  feed:\n    items: 100\n    language: en-us\n---\n\n\n**R Training:** My notes and experiences learning R and RStudio, bundled as an R package (work-in-progress), and published to GitHub Pages using Quarto.\n\nFeel free to use and/or fork this project!\n\n\n::: {.cell}\n\n:::\n\n\n## Notebooks\n\nNotebooks in this package:\n",
     "supporting": [],
     "filters": [