more tests, more cleanups, update NEWS

NEWS.md

@@ -15,14 +15,21 @@
 
   * remove deprecated arguments
     * `xy` argument
-    * arguments `col`, `row`, `cols`, `rows`. `start_col`, `start_row` and `gridExpand` were deprecated in favor of `dims`. Numeric vectors can be converted to `dims` using `rowcol_to_dims()`
+    * arguments `col`, `row`, `cols`, `rows`. `start_col`, `start_row` and `gridExpand` were deprecated in favor of `dims`. Row and column vectors can be converted to `dims` using `wb_dims()`.
 
   * deprecating function
     * `convertToExcelDate()` for `convert_to_excel_date()`
 
   * make `get_cell_refs()`, `get_date_origin()`, `guess_col_type()`, and `write_file()` internal functions
   * make classes `styles_mgr()`, `wbSheetData`, `wbWorksheet`, `wbChartsheet`, `wbComment`, `wbHyperlink` internal
 
+## New features
+
+* `wb_dims()` was added as a more convenient replacement for `rowcol_to_dims()`. The new function can take either numeric (for rows or columns) or character (column) vectors, in addition it is able to create dimensions for R objects that are coerceable to data frame. This allows the following variants:
+* `wb_dims(1:5, letters)`
+* `wb_dims(1:5, 1:26)`
+* `wb_dims(matrix(1, 5, 26))` with an added row for column names
+
 ## Refactoring
 
 * Cleanup / revisit documentation and vignettes  ([682](https://github.com/JanMarvin/openxlsx2/pull/682), @olivroy)

R/utils.R

@@ -279,8 +279,20 @@ wb_dims <- function(...) {
   cnam_null <- is.null(col_names)
   rnam_null <- is.null(row_names)
 
+  srow <- args$start_row
+  scol <- args$start_col
+
+  scol_null <- is.null(scol)
+  srow_null <- is.null(srow)
+
+  if (srow_null) srow <- 0 else srow <- srow - 1L
+  if (scol_null) scol <- 0 else scol <- col2int(scol) - 1L
+
+  x <- args[[1]]
+  exp_name <- inherits(x, "data.frame") || inherits(x, "matrix")
+
   # wb_dims(rows, cols)
-  if (length(args) == 2 && cnam_null && rnam_null) {
+  if (length(args) >= 2 && !exp_name) {
     rows <- 1L
     cols <- 2L
 
@@ -295,13 +307,10 @@ wb_dims <- function(...) {
     }
 
     rows <- args[[rows]]
-    cols <- args[[cols]]
+    cols <- col2int(args[[cols]])
 
   } else {
 
-    x <- args[[1]]
-    exp_name <- inherits(x, "data.frame") || inherits(x, "matrix")
-
     if (cnam_null) col_names <- exp_name
     if (rnam_null) row_names <- FALSE
 
@@ -315,6 +324,9 @@ wb_dims <- function(...) {
 
   }
 
+  rows <- rows + srow
+  cols <- cols + scol
+
   if (length(rows) == 1 && length(cols) == 1) {
     # A1
     dims <- rowcol_to_dim(rows, cols)

tests/testthat/test-utils.R

@@ -69,6 +69,9 @@ test_that("wb_dims() works", {
   expect_equal(wb_dims(1:10, LETTERS), "A1:Z10")
   expect_equal(wb_dims(1:10, 1:26), "A1:Z10")
 
+  expect_equal(wb_dims(1:2, 1:4, start_row = 2, start_col = "B"), "B2:E3")
+  expect_equal(wb_dims(mtcars, start_row = 2, start_col = "B"), "B2:L34")
+
 })
 
 test_that("create_char_dataframe", {

vignettes/openxlsx2.Rmd

@@ -172,6 +172,33 @@ wb$save("mtcars.xlsx")
 try(wb$save("mtcars.xlsx", overwrite = FALSE))
 ```
 
+## `dims`
+
+In `openxlsx2` functions that interact with worksheet cells are using `dims` as argument and require the users to provide these. `dims` are cells or cell ranges in A1 notation. The single argument `dims` hereby replaces `col`/`row`, `cols`/`rows` and `xy`. Since A1 notation is rather simple in the first few columns it might get confusing after the 26. Therefore we provide a wrapper to construct it:
+
+```{r}
+# various options
+wb_dims(4)
+
+wb_dims(row = 4, col = 4)
+
+wb_dims(row = 4:10, col = 5:9)
+
+wb_dims(row = 4:10, col = "A:D")
+
+wb_dims(mtcars)
+
+# in a wb chain
+wb <- wb_workbook()$
+  add_worksheet()$
+  add_data(x = mtcars)$
+  add_fill(
+    dims = wb_dims(mtcars, start_row = 5),
+    color = wb_color("yellow")
+  )
+```
+
+
 ## A note on speed and memory usage
 
 The current state of `openxlsx2` is that it is reasonably fast. That is, it works well with reasonably large input data when reading or writing. It may not work well with data that tests the limits of the openxml specification. Things may slow down on the R side of things, and performance and usability will depend on the speed and size of the local operating system's CPU and memory.