write REDCapR:::collapse_vector()

ref #209

R/utilities.R

@@ -1,5 +1,5 @@
 #' @name replace_nas_with_explicit
-## I'm intentionally not exporting this function.
+## We're intentionally not exporting this function.
 #'
 #' @title Create explicit factor level for missing values.
 #'
@@ -43,3 +43,42 @@ replace_nas_with_explicit <- function( scores, new_na_label="Unknown", create_fa
 
   return( scores )
 }
+
+
+#' @name collapse_vector
+## We're intentionally not exporting this function.
+#'
+#' @title Collapse a vector of values into a single string when necessary.
+#'
+#' @description REDCap's API frequently specifies a series of values separated by commas.
+#' In the R world, it's easier to keep these values as separate elements in a vector.
+#' This functions squashes them together in a single character element (presumably right before the return value is passed to the API)
+#'
+#' @param elements An array of values.  Can be `NULL`.  Required.
+#' @param collapsed A single character element, where the values are separated by commas.  Can be `NULL`.  Required.
+
+#' @return A single character element, where the values are separated by commas.  Can be blank. (*i.e.*, `""`).
+#'
+#' @author Will Beasley
+#'
+#' @examples
+#' library(REDCapR) #Load the package into the current R session.
+#' REDCapR:::collapse_vector(elements=NULL, collapsed=NULL)
+#' REDCapR:::collapse_vector(elements=letters, collapsed=NULL)
+#' REDCapR:::collapse_vector(elements=NULL, collapsed="4,5,6")
+
+collapse_vector <- function( elements, collapsed ) {
+  checkmate::assert_character(collapsed, len=1, any.missing=T, null.ok=T)
+
+  if( (is.null(collapsed) | length(collapsed)==0L) | all(nchar(collapsed)==0L) ) {
+
+    #This is an empty string if `elements` (eg, fields`) is NULL.
+    collapsed <- dplyr::if_else(
+      is.null(elements),
+      "",
+      paste0(elements, collapse=",")
+    )
+  }
+
+  return( collapsed )
+}

tests/testthat/test-utilities-collapse_vector.R

@@ -0,0 +1,31 @@
+library(testthat)
+context("collapse_vector")
+
+test_that("both NULL", {
+  elements  <- NULL
+  collapsed <- NULL
+  expected  <- ""
+
+  observed  <- REDCapR:::collapse_vector(elements, collapsed)
+  expect_equal(observed, expected)
+})
+test_that("collapsed NULL", {
+  elements  <- letters
+  collapsed <- NULL
+  expected  <- "a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z"
+
+  observed  <- REDCapR:::collapse_vector(elements, collapsed)
+  expect_equal(observed, expected)
+})
+test_that("elements NULL", {
+  elements  <- NULL
+  collapsed <- "4,5,6"
+  expected  <- collapsed
+
+  observed  <- REDCapR:::collapse_vector(elements, collapsed)
+  expect_equal(observed, expected)
+})
+
+#' REDCapR:::collapse_vector(elements=NULL, collapsed=NULL)
+#' REDCapR:::collapse_vector(elements=letters, collapsed=NULL)
+#' REDCapR:::collapse_vector(elements=NULL, collapsed="4,5,6")

tests/testthat/test-utilities-replace_nas_with_explicit.R

@@ -1,13 +1,17 @@
 library(testthat)
-context("collapse_vector")
+context("Replace NAs")
 
-test_that("both NULL", {
-  elements  <- NULL
-  collapsed <- NULL
-  expected  <- ""
+test_that("replace_nas_character_standard", {
+  a <- letters
+  missing_indices <- c(3, 6, 8, 25)
+  a[missing_indices] <- NA_character_
 
-  observed <- REDCapR:::collapse_vector(elements, collapsed)
-  expect_equal(observed, expected)
+  expected <- c("a", "b", "Unknown", "d", "e", "Unknown", "g", "Unknown", "i", "j", "k", "l", "m",
+                "n", "o", "p", "q", "r", "s", "t", "u", "v", "w", "x", "Unknown", "z")
+
+  a <- REDCapR:::replace_nas_with_explicit(a)
+  expect_equal(a, expected, label="The correct letters should have been replaced.")
+  expect_equal(class(a), "character", "The returned array should remain a character.")
 })
 
 test_that("replace_nas_factor_standard", {