Refine enumeration support

NAMESPACE

@@ -99,14 +99,17 @@ export(tiledb_array_schema_check)
 export(tiledb_array_schema_evolution)
 export(tiledb_array_schema_evolution_add_attribute)
 export(tiledb_array_schema_evolution_add_enumeration)
+export(tiledb_array_schema_evolution_add_enumeration_empty)
 export(tiledb_array_schema_evolution_array_evolve)
 export(tiledb_array_schema_evolution_drop_attribute)
 export(tiledb_array_schema_evolution_drop_enumeration)
+export(tiledb_array_schema_evolution_extend_enumeration)
 export(tiledb_array_schema_get_allows_dups)
 export(tiledb_array_schema_get_capacity)
 export(tiledb_array_schema_set_allows_dups)
 export(tiledb_array_schema_set_capacity)
 export(tiledb_array_schema_set_coords_filter_list)
+export(tiledb_array_schema_set_enumeration_empty)
 export(tiledb_array_schema_set_offsets_filter_list)
 export(tiledb_array_schema_set_validity_filter_list)
 export(tiledb_array_schema_version)

R/ArraySchema.R

@@ -873,3 +873,31 @@ describe <- function(arr) {
     .describe_attrs(obj$attr)
     .describe_schema(obj$array)
 }
+
+#' Add an empty Enumeration to a Schema
+#'
+#' @param schema An Array Schema
+#' @param attr An Attribute for which an empty Enumeration will be added
+#' @param enum_name A character value with the Enumeration name
+#' @param type_str A character value with the TileDB type, defaults to \sQuote{ASCII}
+#' @param cell_val_num An integer with number values per cell, defaults to \code{NA_integer_} to
+#' flag the \code{NA} value use for character values
+#' @param ordered A logical value indicated standard \code{factor} (when \code{FALSE}, the default)
+#' or \code{ordered} (when \code{TRUE})
+#' @param ctx Optional tiledb_ctx object
+#' @export
+tiledb_array_schema_set_enumeration_empty <- function(schema, attr, enum_name,
+                                                      type_str = "ASCII", cell_val_num = NA_integer_,
+                                                      ordered = FALSE, ctx = tiledb_get_context()) {
+    stopifnot("Argument 'schema' must be a 'tiledb_array_schema'" = is(schema, "tiledb_array_schema"),
+              "Argument 'attr' must be a 'tiledb_attribute'" = is(attr, "tiledb_attr"),
+              "Argument 'enum_name' must be character" = is.character(enum_name),
+              "Argument 'type_str' must be character" = is.character(type_str),
+              "Argument 'cell_val_num' must be integer" = is.integer(cell_val_num),
+              "Argument 'ordered' must be logical" = is.logical(ordered),
+              "Argument 'ctx' must be a 'tiledb_ctx'" = is(ctx, "tiledb_ctx"))
+    schema@ptr <- libtiledb_array_schema_set_enumeration_empty(ctx@ptr, schema@ptr, attr@ptr,
+                                                               enum_name, type_str, cell_val_num,
+                                                               ordered)
+    schema
+}

R/ArraySchemaEvolution.R

@@ -120,3 +120,61 @@ tiledb_array_schema_evolution_drop_enumeration <- function(object, attrname) {
     object@ptr <- libtiledb_array_schema_evolution_drop_enumeration(object@ptr, attrname)
     invisible(object)
 }
+
+#' Evolve an Array Schema by adding an empty Enumeration
+#'
+#' @param asc An ArraySchemaEvolution object
+#' @param enum_name A character value with the Enumeration name
+#' @param type_str A character value with the TileDB type, defaults to \sQuote{ASCII}
+#' @param cell_val_num An integer with number values per cell, defaults to \code{NA_integer_} to
+#' flag the \code{NA} value use for character values
+#' @param ordered A logical value indicating standard \code{factor} (when \code{FALSE}, the default)
+#' or \code{ordered} (when \code{TRUE})
+#' @param ctx Optional tiledb_ctx object
+#' @export
+tiledb_array_schema_evolution_add_enumeration_empty <- function(ase, enum_name, type_str = "ASCII",
+                                                                cell_val_num = NA_integer_,
+                                                                ordered = FALSE,
+                                                                ctx = tiledb_get_context()) {
+    stopifnot("Argument 'ase' must be an Array Schema Evolution object" =
+                  is(object, "tiledb_array_schema_evolution"),
+              "Argument 'enum_name' must be character" = is.character(enum_name),
+              "Argument 'type_str' must be character" = is.character(type_str),
+              "Argument 'cell_val_num' must be integer" = is.integer(cell_val_num),
+              "Argument 'ordered' must be logical" = is.logical(ordered),
+              "Argument 'ctx' must be a 'tiledb_ctx'" = is(ctx, "tiledb_ctx"))
+    ase@ptr <- libtiledb_array_schema_evolution_add_enumeration_empty(ctx@ptr, ase@ptr,
+                                                               enum_name, type_str, cell_val_num,
+                                                               ordered)
+    ase
+}
+
+#' Extend an Evolution via Array Schema Evolution
+#'
+#' @param ase An ArraySchemaEvolution object
+#' @param array A TileDB Array object
+#' @param enum_name A character value with the Enumeration name
+#' @param new_values A character vector with the new Enumeration values
+#' @param nullable A logical value indicating if the Enumeration can contain missing values
+#' (with a default of \code{FALSE})
+#' @param ordered A logical value indicating standard \code{factor} (when \code{FALSE}, the default)
+#' or \code{ordered} (when \code{TRUE})
+#' @param ctx Optional tiledb_ctx object
+#' @export
+tiledb_array_schema_evolution_extend_enumeration <- function(ase, array, enum_name,
+                                                             new_values, nullable = FALSE,
+                                                             ordered = FALSE,
+                                                             ctx = tiledb_get_context()) {
+    stopifnot("Argument 'ase' must be an Array Schema Evolution object" =
+                  is(ase, "tiledb_array_schema_evolution"),
+              "Argument 'array' must be a TileDB Array" = is(array, "tiledb_array"),
+              "Argument 'enum_name' must be character" = is.character(enum_name),
+              "Argument 'new_values' must be character" = is.character(new_values),
+              "Argument 'nullable' must be logical" = is.logical(nullable),
+              "Argument 'ordered' must be logical" = is.logical(ordered),
+              "Argument 'ctx' must be a 'tiledb_ctx'" = is(ctx, "tiledb_ctx"))
+    ase@ptr <- libtiledb_array_schema_evolution_extend_enumeration(ctx@ptr, ase@ptr, array@ptr,
+                                                                   enum_name, new_values,
+                                                                   nullable, ordered)
+    ase
+}

R/RcppExports.R

@@ -442,6 +442,10 @@ libtiledb_array_schema_set_enumeration <- function(ctx, schema, attr, enum_name,
     .Call(`_tiledb_libtiledb_array_schema_set_enumeration`, ctx, schema, attr, enum_name, values, nullable, ordered)
 }
 
+libtiledb_array_schema_set_enumeration_empty <- function(ctx, schema, attr, enum_name, type_str, cell_val_num, ordered) {
+    .Call(`_tiledb_libtiledb_array_schema_set_enumeration_empty`, ctx, schema, attr, enum_name, type_str, cell_val_num, ordered)
+}
+
 libtiledb_array_schema_evolution <- function(ctx) {
     .Call(`_tiledb_libtiledb_array_schema_evolution`, ctx)
 }
@@ -462,10 +466,18 @@ libtiledb_array_schema_evolution_add_enumeration <- function(ctx, ase, enum_name
     .Call(`_tiledb_libtiledb_array_schema_evolution_add_enumeration`, ctx, ase, enum_name, values, nullable, ordered)
 }
 
+libtiledb_array_schema_evolution_add_enumeration_empty <- function(ctx, ase, enum_name, type_str, cell_val_num, ordered = FALSE) {
+    .Call(`_tiledb_libtiledb_array_schema_evolution_add_enumeration_empty`, ctx, ase, enum_name, type_str, cell_val_num, ordered)
+}
+
 libtiledb_array_schema_evolution_drop_enumeration <- function(ase, attrname) {
     .Call(`_tiledb_libtiledb_array_schema_evolution_drop_enumeration`, ase, attrname)
 }
 
+libtiledb_array_schema_evolution_extend_enumeration <- function(ctx, ase, array, enum_name, new_values, nullable = FALSE, ordered = FALSE) {
+    .Call(`_tiledb_libtiledb_array_schema_evolution_extend_enumeration`, ctx, ase, array, enum_name, new_values, nullable, ordered)
+}
+
 libtiledb_array_create <- function(uri, schema) {
     .Call(`_tiledb_libtiledb_array_create`, uri, schema)
 }

inst/tinytest/test_arrayschemaevolution.R

@@ -71,3 +71,39 @@ v <- res[["val"]]$as_vector()
 expect_true(is.factor(v))
 expect_equal(levels(v), enums)
 expect_equal(as.integer(v), c(1:5,5:1))
+
+
+## -- testing 'create empty following by extending'
+if (tiledb_version(TRUE) < "2.17.3") exit_file("Needs TileDB 2.17.3 or later")
+uri <- tempfile()
+dom <- tiledb_domain(dims = tiledb_dim("rows", c(1L, 20L), 10L, "INT32"))
+attrs <- c(tiledb_attr("a", type = "INT32"), tiledb_attr("b", type = "INT32"))
+schema <- tiledb_array_schema(dom, attrs = attrs, sparse = TRUE)
+schema <- tiledb_array_schema_set_enumeration_empty(schema, attrs[[2]], "an_enum")
+tiledb_array_create(uri, schema)
+df <- data.frame(rows = 1:10, a = 100 + 0:9, b = rep(c(1L, 2L), each=5))
+A <- tiledb_array(uri)
+A[] <- df
+arr <- tiledb_array(uri, return_as="data.frame")[]
+expect_true(is.factor(arr[, "b"]))
+expect_equal(levels(arr[, "b"]), character()) # empty levels vector
+## now alter array
+ase <- tiledb_array_schema_evolution()
+arr <- tiledb_array(uri)
+arr <- tiledb_array_open(arr, "READ")
+ase <- tiledb_array_schema_evolution_extend_enumeration(ase, arr, "an_enum", c("red", "green"))
+tiledb_array_schema_evolution_array_evolve(ase, uri)
+arr <- tiledb_array(uri, return_as="data.frame")[]
+expect_equal(levels(arr[, "b"]), c("red", "green"))
+## append to array
+df <- data.frame(rows = 11:20, a = 100 + 10:19, b = rep(c(3L, 4L), each=5))
+A <- tiledb_array(uri)
+A[] <- df
+## and alter again
+ase <- tiledb_array_schema_evolution()
+arr <- tiledb_array(uri)
+arr <- tiledb_array_open(arr, "READ")
+ase <- tiledb_array_schema_evolution_extend_enumeration(ase, arr, "an_enum", c("blue", "orange"))
+tiledb_array_schema_evolution_array_evolve(ase, uri)
+arr <- tiledb_array(uri, return_as="data.frame")[]
+expect_equal(levels(arr[, "b"]), c("red", "green", "blue", "orange"))

src/RcppExports.cpp

@@ -1263,6 +1263,23 @@ BEGIN_RCPP
     return rcpp_result_gen;
 END_RCPP
 }
+// libtiledb_array_schema_set_enumeration_empty
+XPtr<tiledb::ArraySchema> libtiledb_array_schema_set_enumeration_empty(XPtr<tiledb::Context> ctx, XPtr<tiledb::ArraySchema> schema, XPtr<tiledb::Attribute> attr, const std::string enum_name, const std::string type_str, int cell_val_num, bool ordered);
+RcppExport SEXP _tiledb_libtiledb_array_schema_set_enumeration_empty(SEXP ctxSEXP, SEXP schemaSEXP, SEXP attrSEXP, SEXP enum_nameSEXP, SEXP type_strSEXP, SEXP cell_val_numSEXP, SEXP orderedSEXP) {
+BEGIN_RCPP
+    Rcpp::RObject rcpp_result_gen;
+    Rcpp::RNGScope rcpp_rngScope_gen;
+    Rcpp::traits::input_parameter< XPtr<tiledb::Context> >::type ctx(ctxSEXP);
+    Rcpp::traits::input_parameter< XPtr<tiledb::ArraySchema> >::type schema(schemaSEXP);
+    Rcpp::traits::input_parameter< XPtr<tiledb::Attribute> >::type attr(attrSEXP);
+    Rcpp::traits::input_parameter< const std::string >::type enum_name(enum_nameSEXP);
+    Rcpp::traits::input_parameter< const std::string >::type type_str(type_strSEXP);
+    Rcpp::traits::input_parameter< int >::type cell_val_num(cell_val_numSEXP);
+    Rcpp::traits::input_parameter< bool >::type ordered(orderedSEXP);
+    rcpp_result_gen = Rcpp::wrap(libtiledb_array_schema_set_enumeration_empty(ctx, schema, attr, enum_name, type_str, cell_val_num, ordered));
+    return rcpp_result_gen;
+END_RCPP
+}
 // libtiledb_array_schema_evolution
 XPtr<tiledb::ArraySchemaEvolution> libtiledb_array_schema_evolution(XPtr<tiledb::Context> ctx);
 RcppExport SEXP _tiledb_libtiledb_array_schema_evolution(SEXP ctxSEXP) {
@@ -1326,6 +1343,22 @@ BEGIN_RCPP
     return rcpp_result_gen;
 END_RCPP
 }
+// libtiledb_array_schema_evolution_add_enumeration_empty
+XPtr<tiledb::ArraySchemaEvolution> libtiledb_array_schema_evolution_add_enumeration_empty(XPtr<tiledb::Context> ctx, XPtr<tiledb::ArraySchemaEvolution> ase, const std::string& enum_name, const std::string type_str, int cell_val_num, bool ordered);
+RcppExport SEXP _tiledb_libtiledb_array_schema_evolution_add_enumeration_empty(SEXP ctxSEXP, SEXP aseSEXP, SEXP enum_nameSEXP, SEXP type_strSEXP, SEXP cell_val_numSEXP, SEXP orderedSEXP) {
+BEGIN_RCPP
+    Rcpp::RObject rcpp_result_gen;
+    Rcpp::RNGScope rcpp_rngScope_gen;
+    Rcpp::traits::input_parameter< XPtr<tiledb::Context> >::type ctx(ctxSEXP);
+    Rcpp::traits::input_parameter< XPtr<tiledb::ArraySchemaEvolution> >::type ase(aseSEXP);
+    Rcpp::traits::input_parameter< const std::string& >::type enum_name(enum_nameSEXP);
+    Rcpp::traits::input_parameter< const std::string >::type type_str(type_strSEXP);
+    Rcpp::traits::input_parameter< int >::type cell_val_num(cell_val_numSEXP);
+    Rcpp::traits::input_parameter< bool >::type ordered(orderedSEXP);
+    rcpp_result_gen = Rcpp::wrap(libtiledb_array_schema_evolution_add_enumeration_empty(ctx, ase, enum_name, type_str, cell_val_num, ordered));
+    return rcpp_result_gen;
+END_RCPP
+}
 // libtiledb_array_schema_evolution_drop_enumeration
 XPtr<tiledb::ArraySchemaEvolution> libtiledb_array_schema_evolution_drop_enumeration(XPtr<tiledb::ArraySchemaEvolution> ase, const std::string& attrname);
 RcppExport SEXP _tiledb_libtiledb_array_schema_evolution_drop_enumeration(SEXP aseSEXP, SEXP attrnameSEXP) {
@@ -1338,6 +1371,23 @@ BEGIN_RCPP
     return rcpp_result_gen;
 END_RCPP
 }
+// libtiledb_array_schema_evolution_extend_enumeration
+XPtr<tiledb::ArraySchemaEvolution> libtiledb_array_schema_evolution_extend_enumeration(XPtr<tiledb::Context> ctx, XPtr<tiledb::ArraySchemaEvolution> ase, XPtr<tiledb::Array> array, const std::string& enum_name, std::vector<std::string> new_values, bool nullable, bool ordered);
+RcppExport SEXP _tiledb_libtiledb_array_schema_evolution_extend_enumeration(SEXP ctxSEXP, SEXP aseSEXP, SEXP arraySEXP, SEXP enum_nameSEXP, SEXP new_valuesSEXP, SEXP nullableSEXP, SEXP orderedSEXP) {
+BEGIN_RCPP
+    Rcpp::RObject rcpp_result_gen;
+    Rcpp::RNGScope rcpp_rngScope_gen;
+    Rcpp::traits::input_parameter< XPtr<tiledb::Context> >::type ctx(ctxSEXP);
+    Rcpp::traits::input_parameter< XPtr<tiledb::ArraySchemaEvolution> >::type ase(aseSEXP);
+    Rcpp::traits::input_parameter< XPtr<tiledb::Array> >::type array(arraySEXP);
+    Rcpp::traits::input_parameter< const std::string& >::type enum_name(enum_nameSEXP);
+    Rcpp::traits::input_parameter< std::vector<std::string> >::type new_values(new_valuesSEXP);
+    Rcpp::traits::input_parameter< bool >::type nullable(nullableSEXP);
+    Rcpp::traits::input_parameter< bool >::type ordered(orderedSEXP);
+    rcpp_result_gen = Rcpp::wrap(libtiledb_array_schema_evolution_extend_enumeration(ctx, ase, array, enum_name, new_values, nullable, ordered));
+    return rcpp_result_gen;
+END_RCPP
+}
 // libtiledb_array_create
 std::string libtiledb_array_create(std::string uri, XPtr<tiledb::ArraySchema> schema);
 RcppExport SEXP _tiledb_libtiledb_array_create(SEXP uriSEXP, SEXP schemaSEXP) {
@@ -3566,12 +3616,15 @@ static const R_CallMethodDef CallEntries[] = {
     {"_tiledb_libtiledb_array_schema_check", (DL_FUNC) &_tiledb_libtiledb_array_schema_check, 1},
     {"_tiledb_libtiledb_array_schema_version", (DL_FUNC) &_tiledb_libtiledb_array_schema_version, 1},
     {"_tiledb_libtiledb_array_schema_set_enumeration", (DL_FUNC) &_tiledb_libtiledb_array_schema_set_enumeration, 7},
+    {"_tiledb_libtiledb_array_schema_set_enumeration_empty", (DL_FUNC) &_tiledb_libtiledb_array_schema_set_enumeration_empty, 7},
     {"_tiledb_libtiledb_array_schema_evolution", (DL_FUNC) &_tiledb_libtiledb_array_schema_evolution, 1},
     {"_tiledb_libtiledb_array_schema_evolution_add_attribute", (DL_FUNC) &_tiledb_libtiledb_array_schema_evolution_add_attribute, 2},
     {"_tiledb_libtiledb_array_schema_evolution_drop_attribute", (DL_FUNC) &_tiledb_libtiledb_array_schema_evolution_drop_attribute, 2},
     {"_tiledb_libtiledb_array_schema_evolution_array_evolve", (DL_FUNC) &_tiledb_libtiledb_array_schema_evolution_array_evolve, 2},
     {"_tiledb_libtiledb_array_schema_evolution_add_enumeration", (DL_FUNC) &_tiledb_libtiledb_array_schema_evolution_add_enumeration, 6},
+    {"_tiledb_libtiledb_array_schema_evolution_add_enumeration_empty", (DL_FUNC) &_tiledb_libtiledb_array_schema_evolution_add_enumeration_empty, 6},
     {"_tiledb_libtiledb_array_schema_evolution_drop_enumeration", (DL_FUNC) &_tiledb_libtiledb_array_schema_evolution_drop_enumeration, 2},
+    {"_tiledb_libtiledb_array_schema_evolution_extend_enumeration", (DL_FUNC) &_tiledb_libtiledb_array_schema_evolution_extend_enumeration, 7},
     {"_tiledb_libtiledb_array_create", (DL_FUNC) &_tiledb_libtiledb_array_create, 2},
     {"_tiledb_libtiledb_array_create_with_key", (DL_FUNC) &_tiledb_libtiledb_array_create_with_key, 3},
     {"_tiledb_libtiledb_array_open", (DL_FUNC) &_tiledb_libtiledb_array_open, 3},