Support CurrentDomain and NDRectangle (#735)

* Snapshot with NDRectangle functionality

* Refine test file

* Add CurrentDomain

* Roll micro version, update NEWS [ci skip]

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: tiledb
 Type: Package
-Version: 0.28.2.2
+Version: 0.28.2.3
 Title: Modern Database Engine for Complex Data Based on Multi-Dimensional Arrays
 Authors@R: c(person("TileDB, Inc.", role = c("aut", "cph")),
   person("Dirk", "Eddelbuettel", email = "[email protected]", role = "cre"))

NAMESPACE

@@ -143,6 +143,11 @@ export(tiledb_config_unset)
 export(tiledb_ctx)
 export(tiledb_ctx_set_tag)
 export(tiledb_ctx_stats)
+export(tiledb_current_domain)
+export(tiledb_current_domain_get_ndrectangle)
+export(tiledb_current_domain_get_type)
+export(tiledb_current_domain_is_empty)
+export(tiledb_current_domain_set_ndrectangle)
 export(tiledb_datatype_R_type)
 export(tiledb_delete_metadata)
 export(tiledb_dense)
@@ -215,6 +220,9 @@ export(tiledb_group_uri)
 export(tiledb_has_metadata)
 export(tiledb_is_supported_fs)
 export(tiledb_ndim)
+export(tiledb_ndrectangle)
+export(tiledb_ndrectangle_get_range)
+export(tiledb_ndrectangle_set_range)
 export(tiledb_num_metadata)
 export(tiledb_object_ls)
 export(tiledb_object_mv)
@@ -314,12 +322,14 @@ exportClasses(tiledb_array_schema_evolution)
 exportClasses(tiledb_attr)
 exportClasses(tiledb_config)
 exportClasses(tiledb_ctx)
+exportClasses(tiledb_current_domain)
 exportClasses(tiledb_dim)
 exportClasses(tiledb_domain)
 exportClasses(tiledb_filter)
 exportClasses(tiledb_filter_list)
 exportClasses(tiledb_fragment_info)
 exportClasses(tiledb_group)
+exportClasses(tiledb_ndrectangle)
 exportClasses(tiledb_query)
 exportClasses(tiledb_query_condition)
 exportClasses(tiledb_subarray)

NEWS.md

@@ -12,6 +12,8 @@
 
 * Fragments can now be removed by supplying a vector of fragment URIs (#734)
 
+* `NDRectangle` and `CurrentDomain` objects are supported (with 2.25.0 or newer) (#735)
+
 ## Build and Test Systems
 
 * The nighly valgrind matrix now includes release 2.25.0 (#729)

R/CurrentDomain.R

@@ -0,0 +1,96 @@
+#  MIT License
+#
+#  Copyright (c) 2017-2024 TileDB Inc.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in all
+#  copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+#  SOFTWARE.
+
+#' An S4 class for a TileDB CurrentDomain object
+#'
+#' @slot ptr An external pointer to the underlying CurrentDomain object
+#' @exportClass tiledb_current_domain
+setClass("tiledb_current_domain",
+         slots = list(ptr = "externalptr"))
+
+#' Creates a `tiledb_current_domain` object
+#'
+#' @param ctx (optional) A TileDB Ctx object
+#' @return The `tiledb_current_domain` object
+#' @examples
+#' \dontshow{ctx <- tiledb_ctx(limitTileDBCores())}
+#' cd <-tiledb_current_domain()
+#'
+#' @export
+tiledb_current_domain <- function(ctx = tiledb_get_context()) {
+    stopifnot("The first argment must be a TileDB Ctx object" = is(ctx, "tiledb_ctx"),
+              "This function needs TileDB 2.25.0 or later" = tiledb_version(TRUE) >= "2.25.0")
+    ptr <- libtiledb_current_domain_create(ctx@ptr)
+    return(new("tiledb_current_domain", ptr = ptr))
+}
+
+#' Get `tiledb_current_domain` data type as string
+#'
+#' @param cd A TileDB CurrentDomain object
+#' @return The datatype (as string) of the `tiledb_current_domain` object
+#' @export
+tiledb_current_domain_get_type <- function(cd) {
+    stopifnot("The first argment must be a TileDB CurrentDomain object" =
+                  is(cd, "tiledb_current_domain"),
+              "This function needs TileDB 2.25.0 or later" = tiledb_version(TRUE) >= "2.25.0")
+    libtiledb_current_domain_type(cd@ptr)
+}
+
+#' Set a `tiledb_ndrectangle` in a `tiledb_current_domain` object
+#'
+#' @param cd A TileDB CurrentDomain object
+#' @param ndr A TileDB NDRectangle object
+#' @return The modifiled TileDB CurrendDomain object
+#' @export
+tiledb_current_domain_set_ndrectangle <- function(cd, ndr) {
+    stopifnot("The first argment must be a TileDB CurrentDomain object" =
+                  is(cd, "tiledb_current_domain"),
+              "The second argument must be a TileDB NDRectangle object" = is(ndr, "tiledb_ndrectangle"),
+              "This function needs TileDB 2.25.0 or later" = tiledb_version(TRUE) >= "2.25.0")
+    libtiledb_current_domain_set_ndrectangle(cd@ptr, ndr@ptr)
+}
+
+#' Get a `tiledb_ndrectangle` from a `tiledb_current_domain` object
+#'
+#' @param cd A TileDB CurrentDomain object
+#' @return The corresponding TileDB NDRectangle object
+#' @export
+tiledb_current_domain_get_ndrectangle <- function(cd) {
+    stopifnot("The first argment must be a TileDB CurrentDomain object" =
+                  is(cd, "tiledb_current_domain"),
+              "This function needs TileDB 2.25.0 or later" = tiledb_version(TRUE) >= "2.25.0")
+    ptr <- libtiledb_current_domain_get_ndrectangle(cd@ptr)
+    tpstr <- libtiledb_current_domain_type(cd@ptr)
+    return(new("tiledb_ndrectangle", ptr = ptr, datatype = tpstr))
+}
+
+#' Test `tiledb_current_domain` object for being empty
+#'
+#' @param cd A TileDB CurrentDomain object
+#' @return A boolean indicating whether the object is empty or not
+#' @export
+tiledb_current_domain_is_empty <- function(cd) {
+    stopifnot("The first argment must be a TileDB CurrentDomain object" =
+                  is(cd, "tiledb_current_domain"),
+              "This function needs TileDB 2.25.0 or later" = tiledb_version(TRUE) >= "2.25.0")
+    libtiledb_current_domain_is_empty(cd@ptr)
+}

R/NDRectangle.R

@@ -0,0 +1,102 @@
+#  MIT License
+#
+#  Copyright (c) 2017-2024 TileDB Inc.
+#
+#  Permission is hereby granted, free of charge, to any person obtaining a copy
+#  of this software and associated documentation files (the "Software"), to deal
+#  in the Software without restriction, including without limitation the rights
+#  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+#  copies of the Software, and to permit persons to whom the Software is
+#  furnished to do so, subject to the following conditions:
+#
+#  The above copyright notice and this permission notice shall be included in all
+#  copies or substantial portions of the Software.
+#
+#  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+#  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+#  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+#  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+#  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+#  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+#  SOFTWARE.
+
+#' An S4 class for a TileDB NDRectangle object
+#'
+#' @slot ptr An external pointer to the underlying NDRectangle object
+#' @slot datatype A character variable with the TileDB type of the corresponding domain
+#' @exportClass tiledb_ndrectangle
+setClass("tiledb_ndrectangle",
+         slots = list(ptr = "externalptr",
+                      datatype = "character"))
+
+#' Creates a `tiledb_ndrectangle` object
+#'
+#' @param domain A TileDB Domain object for which the NDRectangle object is created
+#' @param ctx (optional) A TileDB Ctx object
+#' @return The `tiledb_ndrectangle` object
+#' @examples
+#' \dontshow{ctx <- tiledb_ctx(limitTileDBCores())}
+#' dom <-tiledb_domain(dim = tiledb_dim("d1", c(1L, 100L), type = "INT32"))
+#' ndr <- tiledb_ndrectangle(dom)
+#'
+#' @export
+tiledb_ndrectangle <- function(dom, ctx = tiledb_get_context()) {
+    stopifnot("The first argument must be a TileDB Domain object" = is(dom, "tiledb_domain"),
+              "The second argment must be a TileDB Ctx object" = is(ctx, "tiledb_ctx"),
+              "This function needs TileDB 2.25.0 or later" = tiledb_version(TRUE) >= "2.25.0")
+    typestr <- datatype(dom)
+    ptr <- libtiledb_ndrectangle_create(ctx@ptr, dom@ptr)
+    return(new("tiledb_ndrectangle", ptr = ptr, datatype = typestr))
+}
+
+#' Set a range on a `tiledb_ndrectangle` object
+#'
+#' @param ndr A TileDB NDRectangle object
+#' @param dimname A character variable with the dimension for which to set a range
+#' @param start The lower end of the range to be set
+#' @param end The upper end of the range to be set
+#' @return The modified `tiledb_ndrectangle` object
+#'
+#' Start and end values have to be of the same data type as the type of the selected
+#' dimension. The set of allowed type includes the different integer types as well as
+#' string dimensions.
+#' @examples
+#' \dontshow{ctx <- tiledb_ctx(limitTileDBCores())}
+#' dom <-tiledb_domain(dim = tiledb_dim("d1", c(1L, 100L), type = "INT32"))
+#' ndr <- tiledb_ndrectangle(dom)
+#' ndr <- tiledb_ndrectangle_set_range(ndr, "d1", 50, 500)
+#'
+#' @export
+tiledb_ndrectangle_set_range <- function(ndr, dimname, start, end) {
+    stopifnot("The first argument must be a TileDB NDRectangle object" = is(ndr, "tiledb_ndrectangle"),
+              "The second argument must a single character object" = is.character(dimname) &&
+                  length(dimname) == 1,
+              "The third argument must be scalar" = length(start) == 1,
+              "The fourth argument must be scalar" = length(end) == 1,
+              "The fourth and first argument must be of the same class" = class(start) == class(end),
+              "This function needs TileDB 2.25.0 or later" = tiledb_version(TRUE) >= "2.25.0")
+    ndr@ptr <- libtiledb_ndrectangle_set_range(ndr@ptr, ndr@datatype, dimname, start, end)
+    invisible(ndr)
+}
+
+#' Get a range from a `tiledb_ndrectangle` object
+#'
+#' @param ndr A TileDB NDRectangle object
+#' @param dimname A character variable with the dimension for which to get a range
+#' @return The `tiledb_ndrectangle` range as a two-element vector
+#' @examples
+#' \dontshow{ctx <- tiledb_ctx(limitTileDBCores())}
+#' dom <- tiledb_domain(dim = tiledb_dim("d1", c(1L, 100L), type = "INT32"))
+#' ndr <- tiledb_ndrectangle(dom)
+#' ndr <- tiledb_ndrectangle_set_range(ndr, "d1", 50, 500)
+#' tiledb_ndrectangle_get_range(ndr, "d1")
+#'
+#' @export
+tiledb_ndrectangle_get_range <- function(ndr, dimname) {
+    stopifnot("The first argument must be a TileDB NDRectangle object" = is(ndr, "tiledb_ndrectangle"),
+              "The second argument must a single character object" = is.character(dimname) &&
+                  length(dimname) == 1,
+              "This function needs TileDB 2.25.0 or later" = tiledb_version(TRUE) >= "2.25.0")
+    rng <- libtiledb_ndrectangle_get_range(ndr@ptr, dimname, ndr@datatype)
+    rng
+}

R/RcppExports.R

@@ -1172,6 +1172,38 @@ libtiledb_mime_type_from_str <- function(mime_type) {
     .Call(`_tiledb_libtiledb_mime_type_from_str`, mime_type)
 }
 
+libtiledb_ndrectangle_create <- function(ctx, dom) {
+    .Call(`_tiledb_libtiledb_ndrectangle_create`, ctx, dom)
+}
+
+libtiledb_ndrectangle_set_range <- function(ndr, datatype, dimname, start, end) {
+    .Call(`_tiledb_libtiledb_ndrectangle_set_range`, ndr, datatype, dimname, start, end)
+}
+
+libtiledb_ndrectangle_get_range <- function(ndr, dimname, dtype) {
+    .Call(`_tiledb_libtiledb_ndrectangle_get_range`, ndr, dimname, dtype)
+}
+
+libtiledb_current_domain_create <- function(ctx) {
+    .Call(`_tiledb_libtiledb_current_domain_create`, ctx)
+}
+
+libtiledb_current_domain_type <- function(cd) {
+    .Call(`_tiledb_libtiledb_current_domain_type`, cd)
+}
+
+libtiledb_current_domain_set_ndrectangle <- function(cd, ndr) {
+    .Call(`_tiledb_libtiledb_current_domain_set_ndrectangle`, cd, ndr)
+}
+
+libtiledb_current_domain_get_ndrectangle <- function(cd) {
+    .Call(`_tiledb_libtiledb_current_domain_get_ndrectangle`, cd)
+}
+
+libtiledb_current_domain_is_empty <- function(cd) {
+    .Call(`_tiledb_libtiledb_current_domain_is_empty`, cd)
+}
+
 vecbuf_to_shmem <- function(dir, name, buf, sz, numvar) {
     invisible(.Call(`_tiledb_vecbuf_to_shmem`, dir, name, buf, sz, numvar))
 }

inst/include/tiledb.h

@@ -122,4 +122,17 @@ namespace tiledb {
 }
 #endif
 
+#if TILEDB_VERSION_MAJOR == 2 && TILEDB_VERSION_MINOR < 25
+// we need a placeholder as tiledb::NDRectangle as it is in function signatures
+namespace tiledb {
+    class NDRectangle {
+    };
+}
+// we need a placeholder as tiledb::CurrentDomain as it is in function signatures
+namespace tiledb {
+    class CurrentDomain {
+    };
+}
+#endif
+
 #endif // __tiledb_h__

inst/tinytest/test_current_domain.R

@@ -0,0 +1,21 @@
+library(tinytest)
+library(tiledb)
+
+ctx <- tiledb_ctx(limitTileDBCores())
+
+if (tiledb_version(TRUE) < "2.25.0") exit_file("These tests needs TileDB 2.25.0 or later")
+
+expect_silent(intdim <- tiledb_dim("dim", c(1L, 100L), type = "INT32"))
+expect_silent(intdom <- tiledb_domain(dim = intdim))
+expect_silent(ndr <- tiledb_ndrectangle(intdom))
+expect_silent(tiledb_ndrectangle_set_range(ndr, "dim", 41L, 42L))   # wrong type
+
+expect_silent(cd <- tiledb_current_domain())
+expect_true(tiledb_current_domain_is_empty(cd))
+expect_error(tiledb_current_domain_get_type(cd))
+
+expect_silent(tiledb_current_domain_set_ndrectangle(cd, ndr))
+expect_silent(newndr <- tiledb_current_domain_get_ndrectangle(cd))
+expect_silent(newtp <- tiledb_current_domain_get_type(cd))
+expect_true(is(newndr, "tiledb_ndrectangle"))
+expect_equal(tiledb_ndrectangle_get_range(newndr, "dim"), c(41L, 42L))

inst/tinytest/test_ndrectangle.R

@@ -0,0 +1,47 @@
+
+library(tinytest)
+library(tiledb)
+
+ctx <- tiledb_ctx(limitTileDBCores())
+
+if (tiledb_version(TRUE) < "2.25.0") exit_file("These tests needs TileDB 2.25.0 or later")
+
+## INT32
+expect_silent(intdim <- tiledb_dim("dim", c(1L, 100L), type = "INT32"))
+expect_true(is(intdim, "tiledb_dim"))
+expect_silent(intdom <- tiledb_domain(dim = intdim))
+expect_true(is(intdom, "tiledb_domain"))
+
+expect_error(ndr <- tiledb_ndrectangle(intdim))
+expect_silent(ndr <- tiledb_ndrectangle(intdom))
+expect_true(is(ndr, "tiledb_ndrectangle"))
+
+expect_error(tiledb_ndrectangle_set_range(intdim, "dim", 1, 2)) # wrong type
+expect_error(tiledb_ndrectangle_set_range(ndr, "notdim", 1, 2)) # wrong name
+expect_error(tiledb_ndrectangle_set_range(ndr, "dim", 1, 2L))   # wrong type
+expect_error(tiledb_ndrectangle_set_range(ndr, "dim", 1L, 2))   # wrong type
+expect_silent(ndr <- tiledb_ndrectangle_set_range(ndr, "dim", 1L, 20L))
+
+expect_error(tiledb_ndrectangle_get_range(intdim, "dim")) # wrong type
+expect_error(tiledb_ndrectangle_set_range(ndr, "notdim")) # wrong name
+expect_equal(tiledb_ndrectangle_get_range(ndr, "dim"), c(1L, 20L))
+
+
+## ASCII
+expect_silent(strdim <- tiledb_dim("strdim", c(NULL, NULL), NULL, type = "ASCII"))
+expect_true(is(strdim, "tiledb_dim"))
+expect_silent(strdom <- tiledb_domain(dim = strdim))
+expect_true(is(strdom, "tiledb_domain"))
+
+expect_silent(ndr <- tiledb_ndrectangle(strdom))
+expect_true(is(ndr, "tiledb_ndrectangle"))
+
+expect_error(tiledb_ndrectangle_set_range(ndr, "notdim", 1, 2)) # wrong name
+expect_error(tiledb_ndrectangle_set_range(ndr, "strdim", 1, 2L))   # wrong type
+expect_error(tiledb_ndrectangle_set_range(ndr, "strdim", 1L, 2))   # wrong type
+expect_silent(ndr <- tiledb_ndrectangle_set_range(ndr, "strdim", "aa", "zz"))
+
+expect_error(tiledb_ndrectangle_set_range(ndr, "notdim")) # wrong name
+## for reasons that are unclear this passes under dev aka 2.26.0 but creates CI issues with 2.25.0-rc0
+if (tiledb_version(TRUE) < "2.26.0") exit_file("These tests needs TileDB 2.26.0 or later")
+expect_equal(tiledb_ndrectangle_get_range(ndr, "strdim"), c("aa", "zz"))