Replace dump functions with operator<< overloads (#5026)

[sc-32959]

In TileDB-Py `schema.dump()` is called without any argument, leading
writes to C `stdout` which Jupyter does not capture:
https://github.com/TileDB-Inc/TileDB/blob/76dbda43d98bff7b71527fbffd0dfd657437b00f/tiledb/sm/array_schema/array_schema.cc#L693-L694

Implementing a function that captures the output of the `dump()` to a
string and then prints it to `sys.stdout` will fix the problem. Of
course, `ArraySchema::dump(std::string*)` calls the `dump()` functions
of other classes, so those need to be implemented as well.

**But** we don't even want to write functions called dump internally;
that's a C idiom; we will reserve that term for the C API only. Since
we're dealing with text output, everything here can be done better by
overloading `operator<<` for `std::ostream`.

---
TYPE: IMPROVEMENT
DESC: Output of `schema.dump()` in TileDB-Py is not captured by Jupyter.
Replacing `dump` functions with `operator<<` overloads will give the
ability to print the resulted string from Python.

---------

Co-authored-by: Eric Hughes <[email protected]>

Author: kounelisagis

test/regression/targets/sc-38300.cc

@@ -53,7 +53,7 @@ void create_array(const std::string& array_uri) {
 void dump_schema(const std::string& array_uri) {
   Context ctx;
   Array array(ctx, array_uri, TILEDB_READ);
-  array.schema().dump();
+  std::cout << array.schema();
   ArrayExperimental::load_all_enumerations(ctx, array);
-  array.schema().dump();
+  std::cout << array.schema();
 }

test/src/unit-cppapi-enumerations.cc

@@ -674,27 +674,10 @@ CPPEnumerationFx::~CPPEnumerationFx() {
 
 template <typename T>
 void CPPEnumerationFx::check_dump(const T& val) {
-  FILE* handle = fopen(dump_name.c_str(), "w");
-  REQUIRE(handle != nullptr);
-  val.dump(handle);
-  fclose(handle);
-
   std::stringstream ss;
+  ss << val;
 
-  // Scoped in an anonymous block to ensure that rstream closes before
-  // we attempt to delete the file for cleanup.
-  {
-    std::ifstream rstream(dump_name);
-    if (rstream.is_open()) {
-      ss << rstream.rdbuf();
-    }
-  }
-
-  auto data = ss.str();
-  auto iter = data.find("Enumeration");
-  REQUIRE(iter != std::string::npos);
-
-  vfs_.remove_file(dump_name);
+  REQUIRE(ss.str().find("Enumeration") != std::string::npos);
 }
 
 void CPPEnumerationFx::create_array(bool with_empty_enumeration) {

test/src/unit-cppapi-fill_values.cc

@@ -40,23 +40,13 @@
 using namespace tiledb;
 
 void check_dump(const Attribute& attr, 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");
-  attr.dump(fout);
-  fclose(fout);
-#ifdef _WIN32
-  CHECK(!system("FC gold_fout.txt fout.txt > nul"));
-#else
-  CHECK(!system("diff gold_fout.txt fout.txt"));
-#endif
+  std::stringstream ss;
+  ss << attr;
+  CHECK(gold_out == ss.str());
 
   // Clean up
   Context ctx;
   VFS vfs(ctx);
-  CHECK_NOTHROW(vfs.remove_file("gold_fout.txt"));
-  CHECK_NOTHROW(vfs.remove_file("fout.txt"));
 }
 
 void create_array_1d(

tiledb/api/c_api/attribute/attribute_api.cc

@@ -5,7 +5,7 @@
  *
  * The MIT License
  *
- * @copyright Copyright (c) 2023 TileDB, Inc.
+ * @copyright Copyright (c) 2023-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
@@ -135,7 +135,28 @@ int32_t tiledb_attribute_get_cell_size(
 int32_t tiledb_attribute_dump(
     const tiledb_attribute_handle_t* attr, FILE* out) {
   ensure_attribute_is_valid(attr);
-  attr->dump(out);
+  ensure_cstream_handle_is_valid(out);
+
+  std::stringstream ss;
+  ss << *attr;
+  size_t r = fwrite(ss.str().c_str(), sizeof(char), ss.str().size(), out);
+  if (r != ss.str().size()) {
+    throw CAPIException(
+        "Error writing attribute " + attr->name() + " to output stream");
+  }
+
+  return TILEDB_OK;
+}
+
+int32_t tiledb_attribute_dump_str(
+    const tiledb_attribute_handle_t* attr, tiledb_string_handle_t** out) {
+  ensure_attribute_is_valid(attr);
+  ensure_output_pointer_is_valid(out);
+
+  std::stringstream ss;
+  ss << *attr;
+  *out = tiledb_string_handle_t::make_handle(ss.str());
+
   return TILEDB_OK;
 }
 
@@ -186,7 +207,7 @@ capi_return_t tiledb_attribute_set_enumeration_name(
 }
 
 capi_return_t tiledb_attribute_get_enumeration_name(
-    tiledb_attribute_t* attr, tiledb_string_t** name) {
+    tiledb_attribute_t* attr, tiledb_string_handle_t** name) {
   ensure_attribute_is_valid(attr);
   ensure_output_pointer_is_valid(name);
 
@@ -203,6 +224,12 @@ capi_return_t tiledb_attribute_get_enumeration_name(
 
 }  // namespace tiledb::api
 
+std::ostream& operator<<(
+    std::ostream& os, const tiledb_attribute_handle_t& attr) {
+  os << *attr.attr_;
+  return os;
+}
+
 using tiledb::api::api_entry_context;
 
 CAPI_INTERFACE(
@@ -308,6 +335,15 @@ CAPI_INTERFACE(
   return api_entry_context<tiledb::api::tiledb_attribute_dump>(ctx, attr, out);
 }
 
+CAPI_INTERFACE(
+    attribute_dump_str,
+    tiledb_ctx_t* ctx,
+    const tiledb_attribute_handle_t* attr,
+    tiledb_string_handle_t** out) {
+  return api_entry_context<tiledb::api::tiledb_attribute_dump_str>(
+      ctx, attr, out);
+}
+
 CAPI_INTERFACE(
     attribute_set_fill_value,
     tiledb_ctx_t* ctx,
@@ -365,7 +401,7 @@ CAPI_INTERFACE(
     attribute_get_enumeration_name,
     tiledb_ctx_t* ctx,
     tiledb_attribute_t* attr,
-    tiledb_string_t** name) {
+    tiledb_string_handle_t** name) {
   return api_entry_context<tiledb::api::tiledb_attribute_get_enumeration_name>(
       ctx, attr, name);
 }

tiledb/api/c_api/attribute/attribute_api_external.h

@@ -310,6 +310,31 @@ TILEDB_EXPORT int32_t tiledb_attribute_dump(
     const tiledb_attribute_t* attr,
     FILE* out) TILEDB_NOEXCEPT;
 
+/**
+ * Dumps the contents of an Attribute in ASCII form to the selected string
+ * output.
+ *
+ * The output string handle must be freed by the user after use.
+ *
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_string_t* tdb_string;
+ * tiledb_attribute_dump_str(ctx, attr, &tdb_string);
+ * // Use the string
+ * tiledb_string_free(&tdb_string);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param attr The attribute.
+ * @param out The output string.
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT int32_t tiledb_attribute_dump_str(
+    tiledb_ctx_t* ctx,
+    const tiledb_attribute_t* attr,
+    tiledb_string_t** out) TILEDB_NOEXCEPT;
+
 /**
  * Sets the default fill value for the input attribute. This value will
  * be used for the input attribute whenever querying (1) an empty cell in

tiledb/api/c_api/attribute/attribute_api_internal.h

@@ -5,7 +5,7 @@
  *
  * The MIT License
  *
- * @copyright Copyright (c) 2023 TileDB, Inc.
+ * @copyright Copyright (c) 2023-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
@@ -33,7 +33,6 @@
 #ifndef TILEDB_CAPI_ATTRIBUTE_INTERNAL_H
 #define TILEDB_CAPI_ATTRIBUTE_INTERNAL_H
 
-#include "attribute_api_external.h"
 #include "tiledb/api/c_api_support/handle/handle.h"
 #include "tiledb/common/common.h"
 #include "tiledb/sm/array_schema/attribute.h"
@@ -90,7 +89,7 @@ struct tiledb_attribute_handle_t
   /**
    * Copy the underlying attribute object.
    */
-  [[nodiscard]] attribute_type copy_attribute() {
+  [[nodiscard]] attribute_type copy_attribute() const {
     return attr_;
   }
 
@@ -190,13 +189,11 @@ struct tiledb_attribute_handle_t
   [[nodiscard]] std::optional<std::string> get_enumeration_name() const {
     return attr_->get_enumeration_name();
   };
-
   /**
    * Facade for `Attribute` function
    */
-  void dump(FILE* out) const {
-    attr_->dump(out);
-  }
+  friend std::ostream& operator<<(
+      std::ostream& os, const tiledb_attribute_handle_t& attr);
 };
 
 namespace tiledb::api {

tiledb/api/c_api/attribute/test/unit_capi_attribute.cc

@@ -33,7 +33,7 @@
 #include "../../../c_api_test_support/testsupport_capi_context.h"
 #include "../../../c_api_test_support/testsupport_capi_datatype.h"
 #include "../../filter_list/filter_list_api_internal.h"
-#include "../attribute_api_internal.h"
+#include "../attribute_api_external.h"
 using namespace tiledb::api::test_support;
 
 TEST_CASE(

tiledb/api/c_api/context/context_api.cc

@@ -31,7 +31,6 @@
  */
 
 #include "../config/config_api_internal.h"
-#include "../filesystem/filesystem_api_external.h"
 #include "context_api_external.h"
 #include "context_api_internal.h"
 #include "tiledb/api/c_api_support/c_api_support.h"

tiledb/api/c_api/dimension/dimension_api.cc

@@ -5,7 +5,7 @@
  *
  * The MIT License
  *
- * @copyright Copyright (c) 2023 TileDB, Inc.
+ * @copyright Copyright (c) 2023-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
@@ -32,6 +32,7 @@
 
 #include "../../c_api_support/c_api_support.h"
 #include "../filter_list/filter_list_api_internal.h"
+#include "../string/string_api_internal.h"
 #include "dimension_api_external.h"
 #include "dimension_api_internal.h"
 #include "tiledb/api/c_api_support/exception_wrapper/exception_wrapper.h"
@@ -40,7 +41,7 @@
 namespace tiledb::api {
 
 int32_t tiledb_dimension_alloc(
-    tiledb_ctx_t* ctx,
+    tiledb_ctx_handle_t* ctx,
     const char* name,
     tiledb_datatype_t type,
     const void* dim_domain,
@@ -138,12 +139,38 @@ int32_t tiledb_dimension_get_tile_extent(
 
 int32_t tiledb_dimension_dump(const tiledb_dimension_t* dim, FILE* out) {
   ensure_dimension_is_valid(dim);
-  dim->dump(out);
+  ensure_cstream_handle_is_valid(out);
+
+  std::stringstream ss;
+  ss << *dim;
+  size_t r = fwrite(ss.str().c_str(), sizeof(char), ss.str().size(), out);
+  if (r != ss.str().size()) {
+    throw CAPIException(
+        "Error writing dimension " + dim->name() + " to output stream");
+  }
+
+  return TILEDB_OK;
+}
+
+int32_t tiledb_dimension_dump_str(
+    const tiledb_dimension_t* dim, tiledb_string_handle_t** out) {
+  ensure_dimension_is_valid(dim);
+  ensure_output_pointer_is_valid(out);
+
+  std::stringstream ss;
+  ss << *dim;
+  *out = tiledb_string_handle_t::make_handle(ss.str());
   return TILEDB_OK;
 }
 
 }  // namespace tiledb::api
 
+std::ostream& operator<<(
+    std::ostream& os, const tiledb_dimension_handle_t& dim) {
+  os << *dim.dimension_;
+  return os;
+}
+
 using tiledb::api::api_entry_context;
 
 CAPI_INTERFACE(
@@ -242,3 +269,12 @@ CAPI_INTERFACE(
     FILE* out) {
   return api_entry_context<tiledb::api::tiledb_dimension_dump>(ctx, dim, out);
 }
+
+CAPI_INTERFACE(
+    dimension_dump_str,
+    tiledb_ctx_t* ctx,
+    const tiledb_dimension_t* dimension,
+    tiledb_string_handle_t** out) {
+  return api_entry_context<tiledb::api::tiledb_dimension_dump_str>(
+      ctx, dimension, out);
+}

tiledb/api/c_api/dimension/dimension_api_external.h

@@ -36,6 +36,7 @@
 #include "../api_external_common.h"
 #include "../datatype/datatype_api_external.h"
 #include "../filter_list/filter_list_api_external.h"
+#include "../string/string_api_external.h"
 
 // For the `FILE *` argument in `tiledb_dimension_dump`
 #include <stdio.h>
@@ -292,6 +293,31 @@ TILEDB_EXPORT int32_t tiledb_dimension_dump(
     const tiledb_dimension_t* dim,
     FILE* out) TILEDB_NOEXCEPT;
 
+/**
+ * Dumps the contents of a dimension in ASCII form to the selected string
+ * output.
+ *
+ * The output string handle must be freed by the user after use.
+ *
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_string_t* tdb_string;
+ * tiledb_dimension_dump_str(ctx, dimension, &tdb_string);
+ * // Use the string
+ * tiledb_string_free(&tdb_string);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param dimension The dimension.
+ * @param out The output string.
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT int32_t tiledb_dimension_dump_str(
+    tiledb_ctx_t* ctx,
+    const tiledb_dimension_t* dimension,
+    tiledb_string_t** out) TILEDB_NOEXCEPT;
+
 #ifdef __cplusplus
 }
 #endif