Add Enumeration::index_of API (#5482)

Add `Enumeration::index_of` API which returns an
`std::optional<uint64_t>` containing the internal index of a value in an
Enumeration if it exists.

User code who needs to extend an enumeration given a list of values need
to recreate the internal hash map structure to efficiently find which
values are missing from the enumeration. Also remapping the indexes from
a subset of values to the values the enumeration holds also requires the
creation of the values hash map. Providing access to the internal hash
map of the enumeration eliminates the need to recreate the map which
might me an expensive step.

---
TYPE: FEATURE 
DESC: Add `Enumeration::index_of` API

Author: XanthosXanthopoulos

test/src/unit-cppapi-enumerations.cc

@@ -282,6 +282,46 @@ TEST_CASE_METHOD(
   REQUIRE_THROWS_WITH(enmr.extend(add_values), matcher);
 }
 
+TEST_CASE_METHOD(
+    CPPEnumerationFx,
+    "CPP: Enumeration API - Var Size index_of",
+    "[enumeration][index_of]") {
+  std::vector<std::string> init_values = {"fred", "wilma"};
+  auto enmr = Enumeration::create(ctx_, enmr_name, init_values, true);
+
+  std::string_view val = "wilma";
+
+  REQUIRE(enmr.index_of(val).has_value() == true);
+  REQUIRE(enmr.index_of(val).value() == 1);
+}
+
+TEST_CASE_METHOD(
+    CPPEnumerationFx,
+    "CPP: Enumeration API - Fix Size Int64 index_of",
+    "[enumeration][index_of]") {
+  std::vector<int64_t> init_values = {1, 5, 6};
+  auto enmr =
+      Enumeration::create(ctx_, enmr_name, init_values, true, TILEDB_INT64);
+  std::string_view val = "wilma";
+  REQUIRE(enmr.index_of(val).has_value() == false);
+
+  REQUIRE(enmr.index_of<int32_t>(1).has_value() == false);
+  REQUIRE(enmr.index_of<int64_t>(1).has_value() == true);
+}
+
+TEST_CASE_METHOD(
+    CPPEnumerationFx,
+    "CPP: Enumeration API - Fix Size Float32 index_of",
+    "[enumeration][index_of]") {
+  std::vector<float_t> init_values = {1, 5, 6, -4};
+  auto enmr = Enumeration::create(ctx_, enmr_name, init_values, true);
+
+  REQUIRE(enmr.index_of<int32_t>(-4).has_value() == false);
+  REQUIRE(enmr.index_of<float_t>(-4).has_value() == true);
+  REQUIRE(enmr.index_of<float_t>(-4).value() == 3);
+  REQUIRE(enmr.index_of<double_t>(-4).has_value() == false);
+}
+
 TEST_CASE_METHOD(
     CPPEnumerationFx,
     "CPP: Enumeration API - Dump Basic",

tiledb/api/c_api/enumeration/enumeration_api.cc

@@ -125,6 +125,22 @@ capi_return_t tiledb_enumeration_get_name(
   return TILEDB_OK;
 }
 
+capi_return_t tiledb_enumeration_get_value_index(
+    tiledb_enumeration_t* enumeration,
+    const void* value,
+    uint64_t value_size,
+    int* exist,
+    uint64_t* index) {
+  ensure_enumeration_is_valid(enumeration);
+  ensure_output_pointer_is_valid(exist);
+  ensure_output_pointer_is_valid(index);
+
+  *index = enumeration->enumeration()->index_of(value, value_size);
+  *exist = *index != sm::constants::enumeration_missing_value ? 1 : 0;
+
+  return TILEDB_OK;
+}
+
 capi_return_t tiledb_enumeration_get_type(
     tiledb_enumeration_t* enumeration, tiledb_datatype_t* type) {
   ensure_enumeration_is_valid(enumeration);
@@ -269,6 +285,18 @@ CAPI_INTERFACE(
       ctx, enumeration, name);
 }
 
+CAPI_INTERFACE(
+    enumeration_get_value_index,
+    tiledb_ctx_t* ctx,
+    tiledb_enumeration_t* enumeration,
+    const void* value,
+    uint64_t value_size,
+    int* exist,
+    uint64_t* index) {
+  return api_entry_context<tiledb::api::tiledb_enumeration_get_value_index>(
+      ctx, enumeration, value, value_size, exist, index);
+}
+
 CAPI_INTERFACE(
     enumeration_get_type,
     tiledb_ctx_t* ctx,

tiledb/api/c_api/enumeration/enumeration_api_experimental.h

@@ -293,6 +293,37 @@ TILEDB_EXPORT capi_return_t tiledb_enumeration_get_offsets(
     const void** offsets,
     uint64_t* offsets_size) TILEDB_NOEXCEPT;
 
+/**
+ * Return the index of the given value in the enumeration
+ *
+ * **Example:**
+ *
+ * @code{.c}
+ * int32_t value = 10;
+ * int exist;
+ * uint64_t index;
+ * tiledb_enumeration_get_value_index(ctx, enumeration, &value, sizeof(int32_t),
+ * &exist, &index);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param enumeration The enumeration.
+ * @param value A pointer to the enumeration value data to check if is
+ * contained.
+ * @param value_size The length of the value buffer provided.
+ * @param exist The return pointer storing whether the value exists.
+ * @param index The return pointer storing the index of the value in the
+ * enumration if it exists.
+ * @return `TILEDB_OK` or `TILEDB_ERR`.
+ */
+TILEDB_EXPORT capi_return_t tiledb_enumeration_get_value_index(
+    tiledb_ctx_t* ctx,
+    tiledb_enumeration_t* enumeration,
+    const void* value,
+    uint64_t value_size,
+    int* exist,
+    uint64_t* index) TILEDB_NOEXCEPT;
+
 #ifndef TILEDB_REMOVE_DEPRECATIONS
 /**
  * Dumps the contents of an Enumeration in ASCII form to some output (e.g.,

tiledb/api/c_api/enumeration/test/unit_capi_enumeration.cc

@@ -585,3 +585,107 @@ TEST_CASE(
     REQUIRE(rc == TILEDB_ERR);
   }
 }
+
+TEST_CASE(
+    "C API: tiledb_enumeration_get_value_index argument validation",
+    "[capi][enumeration]") {
+  FixedSizeEnumeration fe;
+  VarSizeEnumeration ve;
+  NotAllEmptyStringEnumeration ne;
+  AllEmptyStringEnumeration ae;
+  int exist;
+  uint64_t index;
+
+  SECTION("found") {
+    uint32_t uint32_t_value = 3;
+    auto rc = tiledb_enumeration_get_value_index(
+        fe.ctx_.context,
+        fe.enumeration_,
+        &uint32_t_value,
+        sizeof(uint32_t),
+        &exist,
+        &index);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(exist == 1);
+    REQUIRE(index == 2);
+
+    std::string string_value = "bar";
+    rc = tiledb_enumeration_get_value_index(
+        ve.ctx_.context,
+        ve.enumeration_,
+        string_value.data(),
+        string_value.size(),
+        &exist,
+        &index);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(exist == 1);
+    REQUIRE(index == 1);
+
+    std::string empty_string_value = "";
+    rc = tiledb_enumeration_get_value_index(
+        ne.ctx_.context,
+        ne.enumeration_,
+        empty_string_value.data(),
+        empty_string_value.size(),
+        &exist,
+        &index);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(exist == 1);
+    REQUIRE(index == 1);
+
+    rc = tiledb_enumeration_get_value_index(
+        ae.ctx_.context,
+        ae.enumeration_,
+        empty_string_value.data(),
+        empty_string_value.size(),
+        &exist,
+        &index);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(exist == 1);
+    REQUIRE(index == 0);
+  }
+
+  SECTION("not found") {
+    uint32_t uint32_t_value = 10;
+    auto rc = tiledb_enumeration_get_value_index(
+        fe.ctx_.context,
+        fe.enumeration_,
+        &uint32_t_value,
+        sizeof(uint32_t),
+        &exist,
+        &index);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(exist == 0);
+
+    std::string string_value = "fun";
+    rc = tiledb_enumeration_get_value_index(
+        ve.ctx_.context,
+        ve.enumeration_,
+        string_value.data(),
+        string_value.size(),
+        &exist,
+        &index);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(exist == 0);
+
+    rc = tiledb_enumeration_get_value_index(
+        ne.ctx_.context,
+        ne.enumeration_,
+        string_value.data(),
+        string_value.size(),
+        &exist,
+        &index);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(exist == 0);
+
+    rc = tiledb_enumeration_get_value_index(
+        ae.ctx_.context,
+        ae.enumeration_,
+        string_value.data(),
+        string_value.size(),
+        &exist,
+        &index);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(exist == 0);
+  }
+}

tiledb/sm/cpp_api/enumeration_experimental.h

@@ -37,6 +37,8 @@
 #include "tiledb.h"
 #include "tiledb_experimental.h"
 
+#include <optional>
+
 namespace tiledb {
 
 class Enumeration {
@@ -198,6 +200,33 @@ class Enumeration {
     return ret;
   }
 
+  template <typename T, impl::enable_trivial<T>* = nullptr>
+  std::optional<uint64_t> index_of(T value) {
+    int exist = 0;
+    uint64_t index;
+    tiledb_ctx_t* c_ctx = ctx_.get().ptr().get();
+    ctx_.get().handle_error(tiledb_enumeration_get_value_index(
+        c_ctx, enumeration_.get(), &value, sizeof(T), &exist, &index));
+
+    return exist == 1 ? std::make_optional(index) : std::nullopt;
+  }
+
+  template <typename T, impl::enable_trivial<T>* = nullptr>
+  std::optional<uint64_t> index_of(std::basic_string_view<T> value) {
+    int exist = 0;
+    uint64_t index;
+    tiledb_ctx_t* c_ctx = ctx_.get().ptr().get();
+    ctx_.get().handle_error(tiledb_enumeration_get_value_index(
+        c_ctx,
+        enumeration_.get(),
+        value.data(),
+        value.size() * sizeof(T),
+        &exist,
+        &index));
+
+    return exist == 1 ? std::make_optional(index) : std::nullopt;
+  }
+
   /**
    * Get the context of the enumeration
    * @return Context The context of the enumeration.