new http_response_encoding parameter for reading records

closes #354

cc: @lrasmus

NEWS.md

@@ -7,6 +7,7 @@ Upcoming Versions
 * `redcap_metadata_read()` now uses json (instead of csv) to transfer the dictionary between server & client.  This accommodates super-wide dictionaries with 35k+ variables.  The user shouldn't notice a difference, and still will receive a data.frame. (#335, @januz & @datalorax)
 * Include a few more `testthat::skip_on_cran()` calls to comply with CRAN's ["fail gracefully"](https://cran.r-project.org/web/packages/policies.html) policy.  Similarly, skip remaining examples that depend on external resources. (#352)
 * `retrieve_credential_local()` can now user `username` to identify the desired credential row (#364)
+* `redcap_read()` and `redcap_read_oneshot()` gain the `http_response_encoding` parameter that's passed to [`httr::content()`](https://httr.r-lib.org/reference/content.html).  The default value remains "UTF-8".  (#354, @lrasmus)
 
 ### Test Suite 
 

R/redcap-read-oneshot.R

@@ -62,6 +62,8 @@
 #' data type for each column.  Ignored if `col_types` is not null.
 #' @param guess_max A positive integer passed to [readr::read_csv()] that
 #' specifies the maximum number of records to use for guessing column types.
+#' @param http_response_encoding  The encoding value passed to
+#' [httr::content()].  Defaults to 'UTF-8'.
 #' @param verbose A boolean value indicating if `message`s should be printed
 #' to the R console during the operation.  The verbose output might contain
 #' sensitive information (*e.g.* PHI), so turn this off if the output might
@@ -177,6 +179,7 @@ redcap_read_oneshot <- function(
   col_types                     = NULL,
   guess_type                    = TRUE,
   guess_max                     = 1000L,
+  http_response_encoding        = "UTF-8",
   verbose                       = TRUE,
   config_options                = NULL
 ) {
@@ -205,6 +208,8 @@ redcap_read_oneshot <- function(
 
   checkmate::assert_logical(  guess_type                , any.missing=FALSE, len=1)
   checkmate::assert_integerish(guess_max                , any.missing=FALSE, len=1, lower=1)
+  checkmate::assert_character(http_response_encoding    , any.missing=FALSE,     len=1)
+
   checkmate::assert_logical(  verbose                   , any.missing=FALSE, len=1, null.ok=TRUE)
   checkmate::assert_list(     config_options            , any.missing=TRUE ,        null.ok=TRUE)
 
@@ -246,7 +251,12 @@ redcap_read_oneshot <- function(
   if (0L < nchar(events_collapsed )) post_body$events   <- events_collapsed
 
   # This is the important line that communicates with the REDCap server.
-  kernel <- kernel_api(redcap_uri, post_body, config_options)
+  kernel <- kernel_api(
+    redcap_uri      = redcap_uri,
+    post_body       = post_body,
+    config_options  = config_options,
+    encoding        = http_response_encoding
+  )
 
   if (kernel$success) {
     col_types <-

R/redcap-read.R

@@ -74,6 +74,8 @@
 #' returned as character.  If true, [readr::read_csv()] guesses the intended
 #' data type for each column.
 #' @param guess_max Deprecated.
+#' @param http_response_encoding  The encoding value passed to
+#' [httr::content()].  Defaults to 'UTF-8'.
 #' @param verbose A boolean value indicating if `message`s should be printed
 #' to the R console during the operation.  The verbose output might contain
 #' sensitive information (*e.g.* PHI), so turn this off if the output might
@@ -190,6 +192,7 @@ redcap_read <- function(
   col_types                     = NULL,
   guess_type                    = TRUE,
   guess_max                     = NULL, # Deprecated parameter
+  http_response_encoding        = "UTF-8",
   verbose                       = TRUE,
   config_options                = NULL,
   id_position                   = 1L
@@ -217,8 +220,10 @@ redcap_read <- function(
   checkmate::assert_posixct(  datetime_range_end        , any.missing=TRUE , len=1, null.ok=TRUE)
 
   checkmate::assert_logical(  guess_type                , any.missing=FALSE,     len=1)
-
   if (!is.null(guess_max)) warning("The `guess_max` parameter in `REDCapR::redcap_read()` is deprecated.")
+
+  checkmate::assert_character(http_response_encoding    , any.missing=FALSE,     len=1)
+
   checkmate::assert_logical(  verbose                   , any.missing=FALSE,     len=1, null.ok=TRUE)
   checkmate::assert_list(     config_options            , any.missing=TRUE ,            null.ok=TRUE)
   checkmate::assert_integer(  id_position               , any.missing=FALSE,     len=1, lower=1L)
@@ -264,6 +269,7 @@ redcap_read <- function(
     datetime_range_begin   = datetime_range_begin,
     datetime_range_end     = datetime_range_end,
     guess_type         = guess_type,
+    http_response_encoding = http_response_encoding,
     verbose            = verbose,
     config_options     = config_options
   )
@@ -334,6 +340,7 @@ redcap_read <- function(
       col_types                   = col_types,
       guess_type                  = FALSE,
       # guess_max                   = guess_max, # Not used, because guess_type is FALSE
+      http_response_encoding      = http_response_encoding,
       verbose                     = verbose,
       config_options              = config_options
     )