Add tiledb_group_get_member_by(index|name)_v2.

doc/policy/api_changes.md

@@ -74,6 +74,11 @@ Function removal shall be announced one release cycle before removal, following
 
 - `tiledb_query_submit_async`
 
+### 2.15.0..2.16.0
+
+- `tiledb_group_get_member_by_index`
+- `tiledb_group_get_member_by_name`
+
 ## Deprecation History Generation
 
 <details>

test/src/unit-capi-group.cc

@@ -86,7 +86,7 @@ struct GroupFx {
   std::string get_golden_ls(const std::string& path);
   static std::string random_name(const std::string& prefix);
   std::vector<std::pair<tiledb::sm::URI, tiledb_object_t>> read_group(
-      tiledb_group_t* group) const;
+      tiledb_group_t* group, bool use_get_member_by_index_v2 = true) const;
   void set_group_timestamp(
       tiledb_group_t* group, const uint64_t& timestamp) const;
   void write_group_metadata(const char* group_uri) const;
@@ -230,20 +230,46 @@ void GroupFx::vacuum(const char* group_uri) const {
 }
 
 std::vector<std::pair<tiledb::sm::URI, tiledb_object_t>> GroupFx::read_group(
-    tiledb_group_t* group) const {
+    tiledb_group_t* group, bool use_get_member_by_index_v2) const {
   std::vector<std::pair<tiledb::sm::URI, tiledb_object_t>> ret;
   uint64_t count = 0;
-  char* uri;
-  tiledb_object_t type;
-  char* name;
   int rc = tiledb_group_get_member_count(ctx_, group, &count);
   REQUIRE(rc == TILEDB_OK);
-  for (uint64_t i = 0; i < count; i++) {
-    rc = tiledb_group_get_member_by_index(ctx_, group, i, &uri, &type, &name);
-    REQUIRE(rc == TILEDB_OK);
-    ret.emplace_back(uri, type);
-    std::free(uri);
-    std::free(name);
+  if (use_get_member_by_index_v2) {
+    for (uint64_t i = 0; i < count; i++) {
+      std::string uri;
+      tiledb_object_t type;
+      tiledb_string_t *uri_handle, *name_handle;
+      rc = tiledb_group_get_member_by_index_v2(
+          ctx_, group, i, &uri_handle, &type, &name_handle);
+      REQUIRE(rc == TILEDB_OK);
+      const char* uri_str;
+      size_t uri_size;
+      rc = tiledb_string_view(uri_handle, &uri_str, &uri_size);
+      CHECK(rc == TILEDB_OK);
+      uri = std::string(uri_str, uri_size);
+      rc = tiledb_string_free(&uri_handle);
+      CHECK(rc == TILEDB_OK);
+      if (name_handle) {
+        rc = tiledb_string_free(&name_handle);
+        CHECK(rc == TILEDB_OK);
+      }
+      ret.emplace_back(uri, type);
+    }
+  } else {
+    // When tiledb_group_get_member_by_index gets removed, the else part can
+    // simply be removed.
+    for (uint64_t i = 0; i < count; i++) {
+      std::string uri;
+      tiledb_object_t type;
+      char *uri_ptr, *name_ptr;
+      // NOTE: The following function leaks memory.
+      rc = tiledb_group_get_member_by_index(
+          ctx_, group, i, &uri_ptr, &type, &name_ptr);
+      REQUIRE(rc == TILEDB_OK);
+      uri = uri_ptr == nullptr ? "" : std::string(uri_ptr);
+      ret.emplace_back(uri, type);
+    }
   }
   return ret;
 }
@@ -549,6 +575,13 @@ TEST_CASE_METHOD(
 
 TEST_CASE_METHOD(
     GroupFx, "C API: Group, write/read", "[capi][group][metadata][read]") {
+  bool use_get_member_by_index_v2 = true;
+  SECTION("Using tiledb_group_get_member_by_index_v2") {
+    use_get_member_by_index_v2 = true;
+  }
+  SECTION("Using tiledb_group_get_member_by_index") {
+    use_get_member_by_index_v2 = false;
+  }
   // Create and open group in write mode
   // TODO: refactor for each supported FS.
   std::string temp_dir = fs_vec_[0]->temp_dir();
@@ -618,12 +651,12 @@ TEST_CASE_METHOD(
   REQUIRE(rc == TILEDB_OK);
 
   std::vector<std::pair<tiledb::sm::URI, tiledb_object_t>> group1_received =
-      read_group(group1);
+      read_group(group1, use_get_member_by_index_v2);
   REQUIRE_THAT(
       group1_received, Catch::Matchers::UnorderedEquals(group1_expected));
 
   std::vector<std::pair<tiledb::sm::URI, tiledb_object_t>> group2_received =
-      read_group(group2);
+      read_group(group2, use_get_member_by_index_v2);
   REQUIRE_THAT(
       group2_received, Catch::Matchers::UnorderedEquals(group2_expected));
 

tiledb/CMakeLists.txt

@@ -117,6 +117,7 @@ if (TILEDB_CPP_API)
     ${TILEDB_CORE_INCLUDE_DIR}/tiledb/sm/cpp_api/query_experimental.h
     ${TILEDB_CORE_INCLUDE_DIR}/tiledb/sm/cpp_api/schema_base.h
     ${TILEDB_CORE_INCLUDE_DIR}/tiledb/sm/cpp_api/stats.h
+    ${TILEDB_CORE_INCLUDE_DIR}/tiledb/sm/cpp_api/capi_string.h
     ${TILEDB_CORE_INCLUDE_DIR}/tiledb/sm/cpp_api/subarray.h
     ${TILEDB_CORE_INCLUDE_DIR}/tiledb/sm/cpp_api/subarray_experimental.h
     ${TILEDB_CORE_INCLUDE_DIR}/tiledb/sm/cpp_api/type.h

tiledb/api/c_api/group/group_api.cc

@@ -41,6 +41,7 @@
 #include "../buffer/buffer_api_internal.h"
 #include "../config/config_api_internal.h"
 #include "../context/context_api_internal.h"
+#include "../string/string_api_internal.h"
 
 #include "group_api_internal.h"
 
@@ -306,6 +307,10 @@ capi_return_t tiledb_group_get_member_by_index(
   ensure_output_pointer_is_valid(type);
   ensure_output_pointer_is_valid(name);
 
+  LOG_WARN(
+      "tiledb_group_get_member_by_index is deprecated. Please use "
+      "tiledb_group_get_member_by_index_v2 instead.");
+
   char* tmp_uri = nullptr;
   char* tmp_name = nullptr;
 
@@ -343,6 +348,34 @@ capi_return_t tiledb_group_get_member_by_index(
   return TILEDB_OK;
 }
 
+capi_return_t tiledb_group_get_member_by_index_v2(
+    tiledb_group_handle_t* group,
+    uint64_t index,
+    tiledb_string_t** uri,
+    tiledb_object_t* type,
+    tiledb_string_t** name) {
+  ensure_group_is_valid(group);
+  ensure_output_pointer_is_valid(uri);
+  ensure_output_pointer_is_valid(type);
+  ensure_output_pointer_is_valid(name);
+
+  auto&& [uri_str, object_type, name_str] =
+      group->group().member_by_index(index);
+
+  *uri = tiledb_string_handle_t::make_handle(uri_str);
+  *type = static_cast<tiledb_object_t>(object_type);
+  try {
+    *name = name_str.has_value() ?
+                tiledb_string_handle_t::make_handle(*name_str) :
+                nullptr;
+  } catch (...) {
+    tiledb_string_handle_t::break_handle(*uri);
+    throw;
+  }
+
+  return TILEDB_OK;
+}
+
 capi_return_t tiledb_group_get_member_by_name(
     tiledb_group_handle_t* group,
     const char* name,
@@ -353,6 +386,10 @@ capi_return_t tiledb_group_get_member_by_name(
   ensure_output_pointer_is_valid(uri);
   ensure_output_pointer_is_valid(type);
 
+  LOG_WARN(
+      "tiledb_group_get_member_by_name is deprecated. Please use "
+      "tiledb_group_get_member_by_name_v2 instead.");
+
   auto&& [uri_str, object_type, name_str, ignored_relative] =
       group->group().member_by_name(name);
 
@@ -366,6 +403,26 @@ capi_return_t tiledb_group_get_member_by_name(
   return TILEDB_OK;
 }
 
+capi_return_t tiledb_group_get_member_by_name_v2(
+    tiledb_group_handle_t* group,
+    const char* name,
+    tiledb_string_t** uri,
+    tiledb_object_t* type) {
+  ensure_group_is_valid(group);
+  ensure_output_pointer_is_valid(uri);
+  ensure_output_pointer_is_valid(type);
+
+  std::string uri_str;
+  sm::ObjectType object_type;
+  std::tie(uri_str, object_type, std::ignore, std::ignore) =
+      group->group().member_by_name(name);
+
+  *uri = tiledb_string_handle_t::make_handle(std::move(uri_str));
+  *type = static_cast<tiledb_object_t>(object_type);
+
+  return TILEDB_OK;
+}
+
 capi_return_t tiledb_group_get_is_relative_uri_by_name(
     tiledb_group_handle_t* group, const char* name, uint8_t* is_relative) {
   ensure_group_is_valid(group);
@@ -695,6 +752,17 @@ capi_return_t tiledb_group_get_member_by_index(
       ctx, group, index, uri, type, name);
 }
 
+capi_return_t tiledb_group_get_member_by_index_v2(
+    tiledb_ctx_t* ctx,
+    tiledb_group_t* group,
+    uint64_t index,
+    tiledb_string_t** uri,
+    tiledb_object_t* type,
+    tiledb_string_t** name) TILEDB_NOEXCEPT {
+  return api_entry_context<tiledb::api::tiledb_group_get_member_by_index_v2>(
+      ctx, group, index, uri, type, name);
+}
+
 capi_return_t tiledb_group_get_member_by_name(
     tiledb_ctx_t* ctx,
     tiledb_group_t* group,
@@ -705,6 +773,16 @@ capi_return_t tiledb_group_get_member_by_name(
       ctx, group, name, uri, type);
 }
 
+capi_return_t tiledb_group_get_member_by_name_v2(
+    tiledb_ctx_t* ctx,
+    tiledb_group_t* group,
+    const char* name,
+    tiledb_string_t** uri,
+    tiledb_object_t* type) TILEDB_NOEXCEPT {
+  return api_entry_context<tiledb::api::tiledb_group_get_member_by_name_v2>(
+      ctx, group, name, uri, type);
+}
+
 capi_return_t tiledb_group_get_is_relative_uri_by_name(
     tiledb_ctx_t* ctx,
     tiledb_group_t* group,

tiledb/api/c_api/group/group_api_external_experimental.h

@@ -399,7 +399,8 @@ TILEDB_EXPORT capi_return_t tiledb_group_get_member_count(
     tiledb_ctx_t* ctx, tiledb_group_t* group, uint64_t* count) TILEDB_NOEXCEPT;
 
 /**
- * Get a member of a group by index and details of group
+ * Get a member of a group by index and details of group.
+ * Deprecated, use \p tiledb_group_get_member_by_index_v2 instead.
  *
  * **Example:**
  *
@@ -423,14 +424,12 @@ TILEDB_EXPORT capi_return_t tiledb_group_get_member_count(
  * @param ctx The TileDB context.
  * @param group An group opened in READ mode.
  * @param index index of member to fetch
- * @param uri URI of member, The caller takes ownership
- *   of the c-string.
+ * @param uri URI of member.
  * @param type type of member
- * @param name name of member, The caller takes ownership
- *   of the c-string. NULL if name was not set
+ * @param name name of member. NULL if name was not set
  * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
  */
-TILEDB_EXPORT capi_return_t tiledb_group_get_member_by_index(
+TILEDB_DEPRECATED_EXPORT capi_return_t tiledb_group_get_member_by_index(
     tiledb_ctx_t* ctx,
     tiledb_group_t* group,
     uint64_t index,
@@ -447,6 +446,46 @@ TILEDB_EXPORT capi_return_t tiledb_group_get_member_by_index(
  * tiledb_group_t* group;
  * tiledb_group_alloc(ctx, "s3://tiledb_bucket/my_group", &group);
  * tiledb_group_open(ctx, group, TILEDB_WRITE);
+ * tiledb_group_add_member(ctx, group, "s3://tiledb_bucket/my_array");
+ * tiledb_group_add_member(ctx, group, "s3://tiledb_bucket/my_group_2");
+ *
+ * tiledb_group_close(ctx, group);
+ * tiledb_group_open(ctx, group, TILEDB_READ);
+ * tiledb_string_t *uri, *name;
+ * tiledb_object_t type;
+ * tiledb_group_get_member_by_index_v2(ctx, group, 0, &uri, &type, &name);
+ *
+ * tiledb_string_free(uri);
+ * tiledb_string_free(name);
+ *
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param group An group opened in READ mode.
+ * @param index index of member to fetch
+ * @param uri Handle to the URI of the member.
+ * @param type type of member
+ * @param name Handle to the name of the member. NULL if name was not set
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT capi_return_t tiledb_group_get_member_by_index_v2(
+    tiledb_ctx_t* ctx,
+    tiledb_group_t* group,
+    uint64_t index,
+    tiledb_string_t** uri,
+    tiledb_object_t* type,
+    tiledb_string_t** name) TILEDB_NOEXCEPT;
+
+/**
+ * Get a member of a group by name and details of group.
+ * Deprecated, use \p tiledb_group_get_member_by_name_v2.
+ *
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_group_t* group;
+ * tiledb_group_alloc(ctx, "s3://tiledb_bucket/my_group", &group);
+ * tiledb_group_open(ctx, group, TILEDB_WRITE);
  * tiledb_group_add_member(ctx, group, "s3://tiledb_bucket/my_array", "array1");
  * tiledb_group_add_member(ctx, group, "s3://tiledb_bucket/my_group_2",
  * "group2");
@@ -464,18 +503,54 @@ TILEDB_EXPORT capi_return_t tiledb_group_get_member_by_index(
  * @param ctx The TileDB context.
  * @param group An group opened in READ mode.
  * @param name name of member to fetch
- * @param uri URI of member, The caller takes ownership
- *   of the c-string.
+ * @param uri URI of member
  * @param type type of member
  * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
  */
-TILEDB_EXPORT capi_return_t tiledb_group_get_member_by_name(
+TILEDB_DEPRECATED_EXPORT capi_return_t tiledb_group_get_member_by_name(
     tiledb_ctx_t* ctx,
     tiledb_group_t* group,
     const char* name,
     char** uri,
     tiledb_object_t* type) TILEDB_NOEXCEPT;
 
+/**
+ * Get a member of a group by name and details of group.
+ *
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_group_t* group;
+ * tiledb_group_alloc(ctx, "s3://tiledb_bucket/my_group", &group);
+ * tiledb_group_open(ctx, group, TILEDB_WRITE);
+ * tiledb_group_add_member(ctx, group, "s3://tiledb_bucket/my_array", "array1");
+ * tiledb_group_add_member(ctx, group, "s3://tiledb_bucket/my_group_2",
+ * "group2");
+ *
+ * tiledb_group_close(ctx, group);
+ * tiledb_group_open(ctx, group, TILEDB_READ);
+ * tilledb_string_t *uri;
+ * tiledb_object_t type;
+ * tiledb_group_get_member_by_name(ctx, group, "array1", &uri, &type);
+ *
+ * tiledb_string_free(uri);
+ *
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param group An group opened in READ mode.
+ * @param name name of member to fetch
+ * @param uri Handle to the URI of the member.
+ * @param type type of member
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT capi_return_t tiledb_group_get_member_by_name_v2(
+    tiledb_ctx_t* ctx,
+    tiledb_group_t* group,
+    const char* name,
+    tiledb_string_t** uri,
+    tiledb_object_t* type) TILEDB_NOEXCEPT;
+
 /* (clang format was butchering the tiledb_group_add_member() calls) */
 /* clang-format off */
 /**