diff --git a/NEWS.md b/NEWS.md index 8ae83022c..45877de0a 100644 --- a/NEWS.md +++ b/NEWS.md @@ -15,7 +15,7 @@ * 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()` @@ -23,6 +23,13 @@ * 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) diff --git a/R/utils.R b/R/utils.R index adc8eacbe..49b1f4829 100644 --- a/R/utils.R +++ b/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) diff --git a/tests/testthat/test-utils.R b/tests/testthat/test-utils.R index b81b495a3..3f45a5f63 100644 --- a/tests/testthat/test-utils.R +++ b/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", { diff --git a/vignettes/openxlsx2.Rmd b/vignettes/openxlsx2.Rmd index 2bf247541..56a08da5f 100644 --- a/vignettes/openxlsx2.Rmd +++ b/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.