Add documentation

include/sparrow/c_interface.hpp

@@ -66,7 +66,14 @@ extern "C"
 
 namespace sparrow
 {
+ /**
+ * Holds the allocator for the buffers of an ArrowArray.
+ * 
+ * @tparam BufferType The type of the buffers.
+ * @tparam Allocator An allocator for BufferType.
+ */
  template <class BufferType, template <typename> class Allocator>
+ requires sparrow::allocator<Allocator<BufferType>>
  struct ArrowArrayPrivateData
  {
  ArrowArrayPrivateData()
@@ -82,7 +89,13 @@ namespace sparrow
  any_allocator<BufferType> buffer_allocator;
  };
 
+ /**
+ * Holds the allocator for the strings of an ArrowSchema. 
+ * 
+ * @tparam Allocator An allocator for char.
+ */
  template <template <typename> class Allocator>
+ requires sparrow::allocator<Allocator<char>>
  struct ArrowSchemaPrivateData
  {
  ArrowSchemaPrivateData()
@@ -101,7 +114,17 @@ namespace sparrow
  size_t metadata_size = 0;
  };
 
- template <class T>
+
+ template <typename T>
+ concept ArrowType = std::is_same_v<T, ArrowArray> || std::is_same_v<T, ArrowSchema>;
+
+ /**
+ * Releases the children and dictionary of an ArrowArray or ArrowSchema.
+ * 
+ * @tparam T The type of the object.
+ * @param obj The object to release the children and dictionary of.
+ */
+ template <ArrowType T>
  void release_children(T& obj)
  {
  for (int64_t i = 0; i < obj.n_children; ++i)
@@ -114,12 +137,18 @@ namespace sparrow
  }
  delete child;
  }
- delete obj.children;
+ delete[] obj.children;
  obj.children = nullptr;
  obj.n_children = 0;
  }
 
- template <class T>
+ /**
+ * Releases the dictionary of an ArrowArray or ArrowSchema.
+ * 
+ * @tparam T The type of the object.
+ * @param obj The object to release the dictionary of.
+ */
+ template <ArrowType T>
  void release_dictionary(T& obj)
  {
  if (obj.dictionary != nullptr && obj.dictionary->release != nullptr)
@@ -131,14 +160,28 @@ namespace sparrow
  obj.dictionary = nullptr;
  }
 
- template <class T>
+ /**
+ * Releases the children and dictionary of an ArrowArray or ArrowSchema.
+ * 
+ * @tparam T The type of the object.
+ * @param obj The object to release the children and dictionary of.
+ */
+ template <ArrowType T>
  void common_deleter(T& obj)
  {
  release_children(obj);
  release_dictionary(obj);
  }
 
+ /**
+ * Deletes an ArrowArray.
+ * 
+ * @tparam T The type of the buffers of the ArrowArray.
+ * @tparam Allocator The allocator for the buffers of the ArrowArray.
+ * @param array The ArrowArray to delete.
+ */
  template <typename T, template <typename> typename Allocator>
+ requires sparrow::allocator<Allocator<T>>
  void delete_array(ArrowArray* array)
  {
  assert(array != nullptr);
@@ -156,28 +199,36 @@ namespace sparrow
  delete array->buffers;
  array->buffers = nullptr;
  array->n_buffers = 0;
- delete static_cast<ArrowArrayPrivateData<T, Allocator>*>(array->private_data);
+
  array->length = 0;
  array->null_count = 0;
  array->offset = 0;
+
+ delete private_data;
  array->private_data = nullptr;
  array->release = nullptr;
  }
 
+ /**
+ * Deletes an ArrowSchema.
+ *
+ * @tparam Allocator The allocator for the strings of the ArrowSchema.
+ * @param schema The ArrowSchema to delete.
+ */
  template <template <typename> class Allocator>
+ requires sparrow::allocator<Allocator<char>>
  void delete_schema(ArrowSchema* schema)
  {
  assert(schema != nullptr);
  assert(schema->release != nullptr);
 
  common_deleter(*schema);
 
- using ArrowSchemaPrivateData_with_allocator = ArrowSchemaPrivateData<Allocator>;
- const auto private_data = static_cast<ArrowSchemaPrivateData_with_allocator*>(schema->private_data);
+ const auto private_data = static_cast<ArrowSchemaPrivateData<Allocator>*>(schema->private_data);
  auto& string_allocator = private_data->string_allocator;
  const auto dealocate_string = [&string_allocator](const char*& str, size_t& size) -> void
  {
- string_allocator.deallocate(const_cast<char *>(str), size * sizeof(char));
+ string_allocator.deallocate(const_cast<char*>(str), size * sizeof(char));
  str = nullptr;
  size = 0;
  };
@@ -186,16 +237,30 @@ namespace sparrow
  dealocate_string(schema->name, private_data->name_size);
  dealocate_string(schema->metadata, private_data->metadata_size);
 
- delete static_cast<ArrowSchemaPrivateData<Allocator>*>(schema->private_data);
+ delete private_data;
  schema->n_children = 0;
  schema->flags = 0;
- 
+
  schema->private_data = nullptr;
  schema->release = nullptr;
  }
 
+ /**
+ * Creates an ArrowSchema.
+ *
+ * @tparam Allocator The allocator for the strings of the ArrowSchema.
+ * @param format The format of the schema.
+ * @param name The name of the schema.
+ * @param metadata The metadata of the schema.
+ * @param flags The flags of the schema.
+ * @param n_children The number of children of the schema.
+ * @param children The children of the schema.
+ * @param dictionary The dictionary of the schema.
+ * @return The created ArrowSchema.
+ */
  template <template <typename> class Allocator>
- ArrowSchema make_schema_constructor(
+ requires sparrow::allocator<Allocator<char>>
+ ArrowSchema make_arrow_schema(
  const char* format,
  const char* name,
  const char* metadata,
@@ -211,11 +276,11 @@ namespace sparrow
 
  auto private_data = static_cast<ArrowSchemaPrivateData<Allocator>*>(schema.private_data);
 
- const auto build_string = [&private_data](size_t& size, const char* str) -> const char *
+ const auto build_string = [&private_data](size_t& size, const char* str) -> const char*
  {
  size = strlen(str) + 1;
- const char * dest = private_data->string_allocator.allocate(size);
- std::uninitialized_copy(str, str + size, const_cast<char *>(dest));
+ const char* dest = private_data->string_allocator.allocate(size);
+ std::uninitialized_copy(str, str + size, const_cast<char*>(dest));
  return dest;
  };
 
@@ -230,7 +295,22 @@ namespace sparrow
  return schema;
  };
 
+ /**
+ * Creates an ArrowArray.
+ *
+ * @tparam T The type of the buffers of the ArrowArray.
+ * @tparam Allocator The allocator for the buffers of the ArrowArray.
+ * @param length The length of the array.
+ * @param null_count The null count of the array.
+ * @param offset The offset of the array.
+ * @param n_buffers The number of buffers of the array.
+ * @param n_children The number of children of the array.
+ * @param children The children of the array.
+ * @param dictionary The dictionary of the array.
+ * @return The created ArrowArray.
+ */
  template <class T, template <typename> class Allocator>
+ requires sparrow::allocator<Allocator<T>>
  ArrowArray make_array_constructor(
  int64_t length,
  int64_t null_count,

test/test_c_data_interface.cpp

@@ -48,7 +48,7 @@ TEST_SUITE("ArrowArray")
  children[1] = new ArrowArray;
  auto dictionary = new ArrowArray;
  auto array = sparrow::make_array_constructor<int, std::allocator>(1, 0, 0, 1, 2, children, dictionary);
- 
+
  array.release(&array);
 
  CHECK_EQ(array.length, 0);
@@ -65,14 +65,14 @@ TEST_SUITE("ArrowArray")
 
 TEST_SUITE("ArrowSchema")
 {
- TEST_CASE("make_schema_constructor")
+ TEST_CASE("make_arrow_schema")
  {
  auto children = new ArrowSchema*[2];
  children[0] = new ArrowSchema;
  children[1] = new ArrowSchema;
  auto dictionary = new ArrowSchema;
 
- const auto schema = sparrow::make_schema_constructor<std::allocator>(
+ const auto schema = sparrow::make_arrow_schema<std::allocator>(
  "format",
  "name",
  "metadata",
@@ -100,7 +100,7 @@ TEST_SUITE("ArrowSchema")
  children[1] = new ArrowSchema;
  auto dictionary = new ArrowSchema;
 
- auto schema = sparrow::make_schema_constructor<std::allocator>(
+ auto schema = sparrow::make_arrow_schema<std::allocator>(
  "format",
  "name",
  "metadata",