Reimplement C++ dump APIs as deprecated. (#5179)

kounelisagis · KiterLuc · teo-tsirpanis · web-flow · commit 6bad3ac5a58e · 2024-07-18T17:53:07.000+02:00
[sc-32959] Following #5026, `dump` C++ APIs were mistakenly deleted. This PR reimplements them as deprecated. `operator<<` remains the canonical interface. --- TYPE: NO_HISTORY DESC: Reimplement `dump` C++ APIs as deprecated. --------- Co-authored-by: Luc Rancourt <lucrancourt@gmail.com> Co-authored-by: KiterLuc <67824247+KiterLuc@users.noreply.github.com> Co-authored-by: Theodore Tsirpanis <theodore.tsirpanis@tiledb.com>
diff --git a/test/src/unit-capi-fill_values.cc b/test/src/unit-capi-fill_values.cc
@@ -38,24 +38,17 @@
 
 void check_dump(
     tiledb_ctx_t* ctx, tiledb_attribute_t* a, const std::string& gold_out) {
-  FILE* gold_fout = fopen("gold_fout.txt", "w");
-  fwrite(gold_out.c_str(), sizeof(char), gold_out.size(), gold_fout);
-  fclose(gold_fout);
-  FILE* fout = fopen("fout.txt", "w");
-  tiledb_attribute_dump(ctx, a, fout);
-  fclose(fout);
-#ifdef _WIN32
-  CHECK(!system("FC gold_fout.txt fout.txt > nul"));
-#else
-  CHECK(!system("diff gold_fout.txt fout.txt"));
-#endif
+  tiledb_string_t* tdb_string;
+  auto rc = tiledb_attribute_dump_str(ctx, a, &tdb_string);
+  REQUIRE(rc == TILEDB_OK);
 
-  // Clean up
-  tiledb_vfs_t* vfs;
-  tiledb_vfs_alloc(ctx, nullptr, &vfs);
-  CHECK(tiledb_vfs_remove_file(ctx, vfs, "gold_fout.txt") == TILEDB_OK);
-  CHECK(tiledb_vfs_remove_file(ctx, vfs, "fout.txt") == TILEDB_OK);
-  tiledb_vfs_free(&vfs);
+  const char* out_ptr;
+  size_t out_length;
+  rc = tiledb_string_view(tdb_string, &out_ptr, &out_length);
+  REQUIRE(rc == TILEDB_OK);
+  std::string out_str(out_ptr, out_length);
+
+  CHECK(out_str == gold_out);
 }
 
 TEST_CASE(
diff --git a/tiledb/api/c_api/attribute/CMakeLists.txt b/tiledb/api/c_api/attribute/CMakeLists.txt
@@ -35,7 +35,7 @@ gather_sources(${SOURCES})
 commence(object_library capi_attribute_stub)
   this_target_sources(${SOURCES})
   this_target_link_libraries(export)
-  this_target_object_libraries(capi_datatype capi_filter_list_stub)
+  this_target_object_libraries(capi_datatype capi_filter_list_stub capi_string)
   this_target_object_libraries(attribute)
 conclude(object_library)
 
diff --git a/tiledb/api/c_api/attribute/attribute_api_external.h b/tiledb/api/c_api/attribute/attribute_api_external.h
@@ -288,6 +288,7 @@ TILEDB_EXPORT int32_t tiledb_attribute_get_cell_size(
     const tiledb_attribute_t* attr,
     uint64_t* cell_size) TILEDB_NOEXCEPT;
 
+#ifndef TILEDB_REMOVE_DEPRECATIONS
 /**
  * Dumps the contents of an attribute in ASCII form to some output (e.g.,
  * file or stdout).
@@ -305,10 +306,11 @@ TILEDB_EXPORT int32_t tiledb_attribute_get_cell_size(
  * @param out The output.
  * @return `TILEDB_OK` for success and `TILEDB_ERR` for error./
  */
-TILEDB_EXPORT int32_t tiledb_attribute_dump(
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_attribute_dump(
     tiledb_ctx_t* ctx,
     const tiledb_attribute_t* attr,
     FILE* out) TILEDB_NOEXCEPT;
+#endif
 
 /**
  * Dumps the contents of an Attribute in ASCII form to the selected string
diff --git a/tiledb/api/c_api/attribute/test/unit_capi_attribute.cc b/tiledb/api/c_api/attribute/test/unit_capi_attribute.cc
@@ -34,6 +34,7 @@
 #include "../../../c_api_test_support/testsupport_capi_datatype.h"
 #include "../../filter_list/filter_list_api_internal.h"
 #include "../attribute_api_external.h"
+
 using namespace tiledb::api::test_support;
 
 TEST_CASE(
@@ -363,11 +364,15 @@ TEST_CASE(
   ordinary_attribute_1 attr{};
   // SECTION("success") omitted to avoid log noise
   SECTION("null context") {
-    capi_return_t rc = tiledb_attribute_dump(nullptr, attr.attribute, stderr);
+    tiledb_string_t* tdb_string;
+    capi_return_t rc =
+        tiledb_attribute_dump_str(nullptr, attr.attribute, &tdb_string);
     REQUIRE(tiledb_status(rc) == TILEDB_INVALID_CONTEXT);
   }
   SECTION("null dimension") {
-    capi_return_t rc = tiledb_attribute_dump(attr.context(), nullptr, stderr);
+    tiledb_string_t* tdb_string;
+    capi_return_t rc =
+        tiledb_attribute_dump_str(attr.context(), nullptr, &tdb_string);
     REQUIRE(tiledb_status(rc) == TILEDB_ERR);
   }
   // SECTION("null file pointer") `nullptr` is allowed; it's mapped to `stdout`
diff --git a/tiledb/api/c_api/dimension/CMakeLists.txt b/tiledb/api/c_api/dimension/CMakeLists.txt
@@ -35,7 +35,7 @@ gather_sources(${SOURCES})
 commence(object_library capi_dimension_stub)
   this_target_sources(dimension_api.cc)
   this_target_link_libraries(export)
-  this_target_object_libraries(capi_datatype capi_filter_list_stub)
+  this_target_object_libraries(capi_datatype capi_filter_list_stub capi_string)
   this_target_object_libraries(dimension)
 conclude(object_library)
 
diff --git a/tiledb/api/c_api/dimension/dimension_api_external.h b/tiledb/api/c_api/dimension/dimension_api_external.h
@@ -271,6 +271,7 @@ TILEDB_EXPORT int32_t tiledb_dimension_get_tile_extent(
     const tiledb_dimension_t* dim,
     const void** tile_extent) TILEDB_NOEXCEPT;
 
+#ifndef TILEDB_REMOVE_DEPRECATIONS
 /**
  * Dumps the contents of a dimension in ASCII form to some output (e.g.,
  * file or stdout).
@@ -288,10 +289,11 @@ TILEDB_EXPORT int32_t tiledb_dimension_get_tile_extent(
  * @param out The output.
  * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
  */
-TILEDB_EXPORT int32_t tiledb_dimension_dump(
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_dimension_dump(
     tiledb_ctx_t* ctx,
     const tiledb_dimension_t* dim,
     FILE* out) TILEDB_NOEXCEPT;
+#endif
 
 /**
  * Dumps the contents of a dimension in ASCII form to the selected string
diff --git a/tiledb/api/c_api/dimension/test/unit_capi_dimension.cc b/tiledb/api/c_api/dimension/test/unit_capi_dimension.cc
@@ -34,6 +34,7 @@
 #include "../../../c_api_test_support/testsupport_capi_datatype.h"
 #include "../../filter_list/filter_list_api_internal.h"
 #include "../dimension_api_internal.h"
+
 using namespace tiledb::api::test_support;
 
 TEST_CASE(
@@ -341,11 +342,15 @@ TEST_CASE(
   ordinary_dimension_1 dim;
   // SECTION("success") omitted to avoid log noise
   SECTION("null context") {
-    capi_return_t rc = tiledb_dimension_dump(nullptr, dim.dimension, stderr);
+    tiledb_string_t* tdb_string;
+    capi_return_t rc =
+        tiledb_dimension_dump_str(nullptr, dim.dimension, &tdb_string);
     REQUIRE(tiledb_status(rc) == TILEDB_INVALID_CONTEXT);
   }
   SECTION("null dimension") {
-    capi_return_t rc = tiledb_dimension_dump(dim.ctx.context, nullptr, stderr);
+    tiledb_string_t* tdb_string;
+    capi_return_t rc =
+        tiledb_dimension_dump_str(dim.ctx.context, nullptr, &tdb_string);
     REQUIRE(tiledb_status(rc) == TILEDB_ERR);
   }
   // SECTION("null file pointer") `nullptr` is allowed; it's mapped to `stdout`
diff --git a/tiledb/api/c_api/domain/CMakeLists.txt b/tiledb/api/c_api/domain/CMakeLists.txt
@@ -35,7 +35,7 @@ gather_sources(${SOURCES})
 commence(object_library capi_domain_stub)
   this_target_sources(domain_api.cc)
   this_target_link_libraries(export)
-  this_target_object_libraries(capi_dimension_stub)
+  this_target_object_libraries(capi_dimension_stub capi_string)
   this_target_object_libraries(domain)
 conclude(object_library)
 
diff --git a/tiledb/api/c_api/domain/domain_api_external.h b/tiledb/api/c_api/domain/domain_api_external.h
@@ -206,6 +206,7 @@ TILEDB_EXPORT int32_t tiledb_domain_has_dimension(
     const char* name,
     int32_t* has_dim) TILEDB_NOEXCEPT;
 
+#ifndef TILEDB_REMOVE_DEPRECATIONS
 /**
  * Dumps the info of a domain in ASCII form to some output (e.g.,
  * file or `stdout`).
@@ -223,10 +224,11 @@ TILEDB_EXPORT int32_t tiledb_domain_has_dimension(
  * @param out The output.
  * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
  */
-TILEDB_EXPORT int32_t tiledb_domain_dump(
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_domain_dump(
     tiledb_ctx_t* ctx,
     const tiledb_domain_t* domain,
     FILE* out) TILEDB_NOEXCEPT;
+#endif
 
 /**
  * Dumps the contents of a domain in ASCII form to the selected string output.
diff --git a/tiledb/api/c_api/domain/test/unit_capi_domain.cc b/tiledb/api/c_api/domain/test/unit_capi_domain.cc
@@ -29,7 +29,6 @@
  */
 #define CATCH_CONFIG_MAIN
 #include <test/support/tdb_catch.h>
-
 #include "../../../c_api_test_support/testsupport_capi_context.h"
 #include "../domain_api_external.h"
 #include "../domain_api_internal.h"
@@ -247,11 +246,13 @@ TEST_CASE("C API: tiledb_domain_dump argument validation", "[capi][domain]") {
    * platform test, as it requires a FILE *.
    */
   SECTION("null context") {
-    auto rc{tiledb_domain_dump(nullptr, dom.domain, nullptr)};
+    tiledb_string_t* tdb_string;
+    auto rc{tiledb_domain_dump_str(nullptr, dom.domain, &tdb_string)};
     CHECK(rc == TILEDB_INVALID_CONTEXT);
   }
   SECTION("null domain") {
-    auto rc{tiledb_domain_dump(ctx, nullptr, nullptr)};
+    tiledb_string_t* tdb_string;
+    auto rc{tiledb_domain_dump_str(ctx, nullptr, &tdb_string)};
     CHECK(rc == TILEDB_ERR);
   }
   // SECTION("null FILE") is omitted. Null FILE* defaults to stderr
diff --git a/tiledb/api/c_api/enumeration/CMakeLists.txt b/tiledb/api/c_api/enumeration/CMakeLists.txt
@@ -33,7 +33,7 @@ gather_sources(${SOURCES})
 commence(object_library capi_enumeration_stub)
   this_target_sources(enumeration_api.cc)
   this_target_link_libraries(export)
-  this_target_object_libraries(capi_buffer_stub constants)
+  this_target_object_libraries(capi_buffer_stub capi_string constants)
   this_target_object_libraries(enumeration)
 conclude(object_library)
 
diff --git a/tiledb/api/c_api/enumeration/enumeration_api_experimental.h b/tiledb/api/c_api/enumeration/enumeration_api_experimental.h
@@ -293,6 +293,7 @@ TILEDB_EXPORT capi_return_t tiledb_enumeration_get_offsets(
     const void** offsets,
     uint64_t* offsets_size) TILEDB_NOEXCEPT;
 
+#ifndef TILEDB_REMOVE_DEPRECATIONS
 /**
  * Dumps the contents of an Enumeration in ASCII form to some output (e.g.,
  * file or stdout).
@@ -310,10 +311,11 @@ TILEDB_EXPORT capi_return_t tiledb_enumeration_get_offsets(
  * @param out The output.
  * @return `TILEDB_OK` for success and `TILEDB_ERR` for error./
  */
-TILEDB_EXPORT capi_return_t tiledb_enumeration_dump(
+TILEDB_DEPRECATED_EXPORT capi_return_t tiledb_enumeration_dump(
     tiledb_ctx_t* ctx,
     tiledb_enumeration_t* enumeration,
     FILE* out) TILEDB_NOEXCEPT;
+#endif
 
 /**
  * Dumps the contents of an Enumeration in ASCII form to the selected string
diff --git a/tiledb/doxygen/source/c-api.rst b/tiledb/doxygen/source/c-api.rst
@@ -334,8 +334,6 @@ Array Schema
     :project: TileDB-C
 .. doxygenfunction:: tiledb_array_schema_has_attribute
     :project: TileDB-C
-.. doxygenfunction:: tiledb_array_schema_dump
-    :project: TileDB-C
 .. doxygenfunction:: tiledb_array_schema_dump_str
     :project: TileDB-C
 
@@ -363,8 +361,6 @@ Attribute
     :project: TileDB-C
 .. doxygenfunction:: tiledb_attribute_get_cell_size
     :project: TileDB-C
-.. doxygenfunction:: tiledb_attribute_dump
-    :project: TileDB-C
 .. doxygenfunction:: tiledb_attribute_dump_str
     :project: TileDB-C
 .. doxygenfunction:: tiledb_attribute_set_fill_value
@@ -394,8 +390,6 @@ Domain
     :project: TileDB-C
 .. doxygenfunction:: tiledb_domain_has_dimension
     :project: TileDB-C
-.. doxygenfunction:: tiledb_domain_dump
-    :project: TileDB-C
 .. doxygenfunction:: tiledb_domain_dump_str
     :project: TileDB-C
 
@@ -421,8 +415,6 @@ Dimension
     :project: TileDB-C
 .. doxygenfunction:: tiledb_dimension_get_tile_extent
     :project: TileDB-C
-.. doxygenfunction:: tiledb_dimension_dump
-    :project: TileDB-C
 .. doxygenfunction:: tiledb_dimension_dump_str
     :project: TileDB-C
 
diff --git a/tiledb/sm/array_schema/domain.cc b/tiledb/sm/array_schema/domain.cc
@@ -1170,8 +1170,6 @@ template uint64_t Domain::stride<double>(Layout subarray_layout) const;
 }  // namespace tiledb::sm
 
 std::ostream& operator<<(std::ostream& os, const tiledb::sm::Domain& domain) {
-  std::string tmp;
-
   for (unsigned i = 0; i < domain.dim_num(); i++) {
     os << std::endl;
     os << *domain.dimension_ptr(i);
diff --git a/tiledb/sm/c_api/tiledb.h b/tiledb/sm/c_api/tiledb.h
@@ -888,27 +888,6 @@ TILEDB_EXPORT int32_t tiledb_array_schema_has_attribute(
     const char* name,
     int32_t* has_attr) TILEDB_NOEXCEPT;
 
-/**
- * Dumps the array schema in ASCII format in the selected file output.
- *
- * **Example:**
- *
- * The following prints the array schema dump in standard output.
- *
- * @code{.c}
- * tiledb_array_schema_dump(ctx, array_schema, stdout);
- * @endcode
- *
- * @param ctx The TileDB context.
- * @param array_schema The array schema.
- * @param out The output handle.
- * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
- */
-TILEDB_EXPORT int32_t tiledb_array_schema_dump(
-    tiledb_ctx_t* ctx,
-    const tiledb_array_schema_t* array_schema,
-    FILE* out) TILEDB_NOEXCEPT;
-
 /**
  * Dumps the array schema in ASCII format in the selected string output.
  *
diff --git a/tiledb/sm/c_api/tiledb_deprecated.h b/tiledb/sm/c_api/tiledb_deprecated.h
@@ -42,6 +42,27 @@ extern "C" {
 
 // No deprecated APIs are declared at the moment.
 
+/**
+ * Dumps the array schema in ASCII format in the selected file output.
+ *
+ * **Example:**
+ *
+ * The following prints the array schema dump in standard output.
+ *
+ * @code{.c}
+ * tiledb_array_schema_dump(ctx, array_schema, stdout);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param array_schema The array schema.
+ * @param out The output handle.
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_DEPRECATED_EXPORT int32_t tiledb_array_schema_dump(
+    tiledb_ctx_t* ctx,
+    const tiledb_array_schema_t* array_schema,
+    FILE* out) TILEDB_NOEXCEPT;
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/tiledb/sm/cpp_api/array_schema.h b/tiledb/sm/cpp_api/array_schema.h
@@ -157,6 +157,20 @@ class ArraySchema : public Schema {
   /*                API                */
   /* ********************************* */
 
+#ifndef TILEDB_REMOVE_DEPRECATIONS
+  /**
+   * Dumps the array schema in an ASCII representation to an output.
+   *
+   * @param out (Optional) File to dump output to. Defaults to `stdout`.
+   */
+  TILEDB_DEPRECATED
+  void dump(FILE* out = stdout) const override {
+    auto& ctx = ctx_.get();
+    ctx.handle_error(
+        tiledb_array_schema_dump(ctx.ptr().get(), schema_.get(), out));
+  }
+#endif
+
   /** Returns the array type. */
   tiledb_array_type_t array_type() const {
     auto& ctx = ctx_.get();
diff --git a/tiledb/sm/cpp_api/attribute.h b/tiledb/sm/cpp_api/attribute.h
@@ -475,6 +475,20 @@ class Attribute {
     return attr_;
   }
 
+#ifndef TILEDB_REMOVE_DEPRECATIONS
+  /**
+   * Dumps information about the attribute in an ASCII representation to an
+   * output.
+   *
+   * @param out (Optional) File to dump output to. Defaults to `stdout`.
+   */
+  TILEDB_DEPRECATED
+  void dump(FILE* out = stdout) const {
+    ctx_.get().handle_error(
+        tiledb_attribute_dump(ctx_.get().ptr().get(), attr_.get(), out));
+  }
+#endif
+
   /* ********************************* */
   /*          STATIC FUNCTIONS         */
   /* ********************************* */
diff --git a/tiledb/sm/cpp_api/dimension.h b/tiledb/sm/cpp_api/dimension.h
@@ -396,6 +396,20 @@ class Dimension {
     return dim_;
   }
 
+#ifndef TILEDB_REMOVE_DEPRECATIONS
+  /**
+   * Dumps information about the dimension in an ASCII representation to an
+   * output.
+   *
+   * @param out (Optional) File to dump output to. Defaults to `stdout`.
+   */
+  TILEDB_DEPRECATED
+  void dump(FILE* out = stdout) const {
+    ctx_.get().handle_error(
+        tiledb_dimension_dump(ctx_.get().ptr().get(), dim_.get(), out));
+  }
+#endif
+
   /* ********************************* */
   /*          STATIC FUNCTIONS         */
   /* ********************************* */
diff --git a/tiledb/sm/cpp_api/domain.h b/tiledb/sm/cpp_api/domain.h
diff --git a/tiledb/sm/cpp_api/enumeration_experimental.h b/tiledb/sm/cpp_api/enumeration_experimental.h
diff --git a/tiledb/sm/cpp_api/schema_base.h b/tiledb/sm/cpp_api/schema_base.h
