feat: [sc-58279] [core] add tiledb_array_schema_get_enumeration API

test/src/unit-cppapi-enumerations.cc

@@ -33,6 +33,7 @@
 #include <fstream>
 
 #include <test/support/tdb_catch.h>
+#include "test/support/src/array_schema_helpers.h"
 #include "test/support/src/vfs_helpers.h"
 #include "tiledb/api/c_api/array/array_api_internal.h"
 #include "tiledb/api/c_api/array_schema/array_schema_api_internal.h"
@@ -313,6 +314,67 @@ TEST_CASE_METHOD(
   REQUIRE(enmr_name2.has_value() == false);
 }
 
+TEST_CASE_METHOD(
+    CPPEnumerationFx,
+    "CPP: Enumerations From Disk - ArraySchema::get_enumeration",
+    "[enumeration][array-schema-get-enumeration][rest]") {
+  create_array();
+
+  SECTION("default schema load does not populate enumeration") {
+    auto schema = Array::load_schema(ctx_, uri_);
+    auto enmr = ArraySchemaExperimental::get_enumeration_if_loaded(
+        ctx_, schema, "an_enumeration");
+    CHECK(!enmr.has_value());
+  }
+
+  SECTION("array get_enumeration loads enumeration and schema shares") {
+    auto array = tiledb::Array(ctx_, uri_, TILEDB_READ);
+    auto from_array =
+        ArrayExperimental::get_enumeration(ctx_, array, "an_enumeration");
+
+    auto schema = array.schema();
+    auto from_schema = ArraySchemaExperimental::get_enumeration_if_loaded(
+        ctx_, schema, "an_enumeration");
+    CHECK(test::is_equivalent_enumeration(from_array, *from_schema));
+  }
+
+  SECTION("array get_enumeration loads into user schema handle") {
+    auto array = tiledb::Array(ctx_, uri_, TILEDB_READ);
+    auto schema = array.schema();
+
+    // the enumeration is not populated yet
+    REQUIRE(!ArraySchemaExperimental::get_enumeration_if_loaded(
+                 ctx_, schema, "an_enumeration")
+                 .has_value());
+
+    // array method actually loads it
+    auto from_array =
+        ArrayExperimental::get_enumeration(ctx_, array, "an_enumeration");
+
+    // and once it is loaded, it is set on the schema
+    auto from_schema = ArraySchemaExperimental::get_enumeration_if_loaded(
+        ctx_, schema, "an_enumeration");
+    REQUIRE(from_schema.has_value());
+
+    CHECK(test::is_equivalent_enumeration(from_array, *from_schema));
+  }
+
+  SECTION("schema load with rest config does populate enumeration") {
+    Config config;
+    config["rest.load_enumerations_on_array_open"] = "true";
+
+    auto schema = Array::load_schema_with_config(ctx_, config, uri_);
+    auto enmr = ArraySchemaExperimental::get_enumeration_if_loaded(
+        ctx_, schema, "an_enumeration");
+    REQUIRE(enmr.has_value());
+    REQUIRE(enmr->ptr() != nullptr);
+    REQUIRE(enmr->name() == "an_enumeration");
+    REQUIRE(enmr->type() == TILEDB_STRING_ASCII);
+    REQUIRE(enmr->cell_val_num() == TILEDB_VAR_NUM);
+    REQUIRE(enmr->ordered() == false);
+  }
+}
+
 TEST_CASE_METHOD(
     CPPEnumerationFx,
     "CPP: Array::load_all_enumerations",

test/support/CMakeLists.txt

@@ -36,6 +36,7 @@ list(APPEND TILEDB_CORE_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/tiledb/sm/c_api")
 
 # Gather the test source files
 set(TILEDB_TEST_SUPPORT_SOURCES
+  src/array_schema_helpers.cc
   src/ast_helpers.h
   src/ast_helpers.cc
   src/helpers.h

test/support/src/array_schema_helpers.cc

@@ -0,0 +1,54 @@
+/**
+ * @file   array_schema_helpers.cc
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2017-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
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * This file defines some array schema test suite helper functions.
+ */
+
+#include "test/support/src/array_schema_helpers.h"
+#include "tiledb/api/c_api/enumeration/enumeration_api_internal.h"
+#include "tiledb/sm/array_schema/enumeration.h"
+#include "tiledb/sm/cpp_api/tiledb"
+
+using namespace tiledb;
+
+namespace tiledb::test {
+
+bool is_equivalent_enumeration(
+    const Enumeration& left, const Enumeration& right) {
+  return left.name() == right.name() && left.type() == right.type() &&
+         left.cell_val_num() == right.cell_val_num() &&
+         left.ordered() == right.ordered() &&
+         std::equal(
+             left.ptr()->data().begin(),
+             left.ptr()->data().end(),
+             right.ptr()->data().begin(),
+             right.ptr()->data().end());
+}
+
+}  // namespace tiledb::test

test/support/src/array_schema_helpers.h

@@ -0,0 +1,50 @@
+/**
+ * @file   array_schema_helpers.h
+ *
+ * @section LICENSE
+ *
+ * The MIT License
+ *
+ * @copyright Copyright (c) 2017-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
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @section DESCRIPTION
+ *
+ * This file declares some array schema test suite helper functions.
+ */
+
+#ifndef TILEDB_TEST_ARRAY_SCHEMA_HELPERS_H
+#define TILEDB_TEST_ARRAY_SCHEMA_HELPERS_H
+
+#include "tiledb/sm/cpp_api/tiledb"
+#include "tiledb/sm/cpp_api/tiledb_experimental"
+
+namespace tiledb::test {
+
+/**
+ * @return if two enumerations `left` and `right` are equivalent,
+ *         i.e. have the same name, datatype, variants, etc
+ */
+bool is_equivalent_enumeration(
+    const tiledb::Enumeration& left, const tiledb::Enumeration& right);
+
+}  // namespace tiledb::test
+
+#endif

tiledb/api/c_api/array_schema/array_schema_api.cc

@@ -181,6 +181,26 @@ capi_return_t tiledb_array_schema_timestamp_range(
   return TILEDB_OK;
 }
 
+capi_return_t tiledb_array_schema_get_enumeration_if_loaded(
+    tiledb_array_schema_t* array_schema,
+    const char* enumeration_name,
+    tiledb_enumeration_t** enumeration) {
+  ensure_array_schema_is_valid(array_schema);
+  ensure_output_pointer_is_valid(enumeration);
+
+  if (enumeration_name == nullptr) {
+    throw CAPIException("'enumeration_name' must not be null");
+  }
+
+  auto ptr = array_schema->get_enumeration(enumeration_name);
+  if (ptr) {
+    *enumeration = tiledb_enumeration_handle_t::make_handle(ptr);
+  } else {
+    *enumeration = nullptr;
+  }
+  return TILEDB_OK;
+}
+
 capi_return_t tiledb_array_schema_add_enumeration(
     tiledb_array_schema_t* array_schema, tiledb_enumeration_t* enumeration) {
   ensure_array_schema_is_valid(array_schema);
@@ -540,6 +560,17 @@ CAPI_INTERFACE(
       ctx, array_schema, lo, hi);
 }
 
+CAPI_INTERFACE(
+    array_schema_get_enumeration_if_loaded,
+    tiledb_ctx_t* ctx,
+    tiledb_array_schema_t* array_schema,
+    const char* enumeration_name,
+    tiledb_enumeration_t** enumeration) {
+  return api_entry_context<
+      tiledb::api::tiledb_array_schema_get_enumeration_if_loaded>(
+      ctx, array_schema, enumeration_name, enumeration);
+}
+
 CAPI_INTERFACE(
     array_schema_add_enumeration,
     tiledb_ctx_t* ctx,

tiledb/api/c_api/array_schema/array_schema_api_experimental.h

@@ -67,6 +67,38 @@ TILEDB_EXPORT capi_return_t tiledb_array_schema_timestamp_range(
     uint64_t* lo,
     uint64_t* hi) TILEDB_NOEXCEPT;
 
+/**
+ * Retrieves an already-loaded enumeration given its name,
+ * if it has already been loaded into memory.
+ *
+ * If the enumeration has already been loaded,
+ * such as via `tiledb_array_get_enumeration`,
+ * then this returns a pointer to the enumeration.
+ * Otherwise this returns `TILEDB_OK` and sets `enumeration` to NULL.
+ *
+ * **Example:**
+ *
+ * The following retrieves the enumeration named "states" in the schema.
+ *
+ * @code{.c}
+ * tiledb_enumeration_t* enmr;
+ * tiledb_array_schema_get_enumeration_if_loaded(ctx,
+ *         array_schema, "states", &enmr);
+ * tiledb_attribute_free(&enmr);
+ * @endcode
+ *
+ * @param[in] ctx The TileDB context.
+ * @param[in] array_schema The array schema.
+ * @param[in] name The name of the enumeration to retrieve.
+ * @param[out] enmr The enumeration object to retrieve.
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT capi_return_t tiledb_array_schema_get_enumeration_if_loaded(
+    tiledb_ctx_t* ctx,
+    tiledb_array_schema_t* array_schema,
+    const char* name,
+    tiledb_enumeration_t** enumeration) TILEDB_NOEXCEPT;
+
 /**
  * Adds an enumeration to an array schema.
  *

tiledb/api/c_api/array_schema/array_schema_api_internal.h

@@ -90,6 +90,11 @@ struct tiledb_array_schema_handle_t
         dim_id, name, label_order, label_type, check_name);
   }
 
+  shared_ptr<const tiledb::sm::Enumeration> get_enumeration(
+      const char* name) const {
+    return array_schema_->get_enumeration(name);
+  }
+
   void add_enumeration(shared_ptr<const tiledb::sm::Enumeration> enmr) {
     return array_schema_->add_enumeration(enmr);
   }

tiledb/api/c_api/array_schema/test/unit_capi_array_schema.cc

@@ -361,6 +361,69 @@ TEST_CASE(
   CHECK(enumeration == nullptr);
 }
 
+TEST_CASE(
+    "C API: tiledb_array_schema_get_enumeration argument validation",
+    "[capi][array_schema]") {
+  capi_return_t rc;
+  ordinary_array_schema x{};
+  tiledb_enumeration_t* enumeration;
+  SECTION("null context") {
+    rc = tiledb_array_schema_get_enumeration_if_loaded(
+        nullptr, x.schema, "primes", &enumeration);
+    REQUIRE(tiledb_status(rc) == TILEDB_INVALID_CONTEXT);
+  }
+  SECTION("null schema") {
+    rc = tiledb_array_schema_get_enumeration_if_loaded(
+        x.ctx(), nullptr, "primes", &enumeration);
+    REQUIRE(tiledb_status(rc) == TILEDB_ERR);
+  }
+  SECTION("null name") {
+    rc = tiledb_array_schema_get_enumeration_if_loaded(
+        x.ctx(), x.schema, nullptr, &enumeration);
+    REQUIRE(tiledb_status(rc) == TILEDB_ERR);
+  }
+  SECTION("null enumeration") {
+    rc = tiledb_array_schema_get_enumeration_if_loaded(
+        x.ctx(), x.schema, "primes", nullptr);
+    REQUIRE(tiledb_status(rc) == TILEDB_ERR);
+  }
+  SECTION("success") {
+    int32_t values[5] = {2, 3, 5, 7, 11};
+    rc = tiledb_enumeration_alloc(
+        x.ctx(),
+        "primes",
+        TILEDB_UINT32,
+        1,
+        0,
+        values,
+        sizeof(uint32_t) * 5,
+        nullptr,
+        0,
+        &enumeration);
+    REQUIRE(tiledb_status(rc) == TILEDB_OK);
+    rc = tiledb_array_schema_add_enumeration(x.ctx(), x.schema, enumeration);
+    REQUIRE(tiledb_status(rc) == TILEDB_OK);
+    REQUIRE_NOTHROW(tiledb_enumeration_free(&enumeration));
+    CHECK(enumeration == nullptr);
+
+    rc = tiledb_array_schema_get_enumeration_if_loaded(
+        x.ctx(), x.schema, "primes", &enumeration);
+    REQUIRE(tiledb_status(rc) == TILEDB_OK);
+    REQUIRE(enumeration != nullptr);
+
+    tiledb_string_t* tiledb_name(nullptr);
+    rc = tiledb_enumeration_get_name(x.ctx(), enumeration, &tiledb_name);
+    REQUIRE(tiledb_status(rc) == TILEDB_OK);
+    REQUIRE(tiledb_name != nullptr);
+
+    const char* name;
+    size_t length;
+    rc = tiledb_string_view(tiledb_name, &name, &length);
+    REQUIRE(tiledb_status(rc) == TILEDB_OK);
+    CHECK(std::string(name, length) == "primes");
+  }
+}
+
 TEST_CASE(
     "C API: tiledb_array_schema_set_coords_filter_list argument validation",
     "[capi][array_schema]") {

tiledb/sm/cpp_api/array.h

@@ -717,6 +717,32 @@ class Array {
     return ArraySchema(ctx, schema);
   }
 
+  /**
+   * Loads the array schema from an array.
+   * Options to load additional features are read from the optionally-provided
+   * `config`. See `tiledb_array_schema_load_with_config`.
+   *
+   * **Example:**
+   * @code{.cpp}
+   * tiledb::Config config;
+   * config["rest.load_enumerations_on_array_open"] = "true";
+   * auto schema = tiledb::Array::load_schema_with_config(ctx, config,
+   * "s3://bucket-name/array-name");
+   * @endcode
+   *
+   * @param ctx The TileDB context.
+   * @param config The request for additional features.
+   * @param uri The array URI.
+   * @return The loaded ArraySchema object.
+   */
+  static ArraySchema load_schema_with_config(
+      const Context& ctx, const Config& config, const std::string& uri) {
+    tiledb_array_schema_t* schema;
+    ctx.handle_error(tiledb_array_schema_load_with_config(
+        ctx.ptr().get(), config.ptr().get(), uri.c_str(), &schema));
+    return ArraySchema(ctx, schema);
+  }
+
   /**
    * Gets the encryption type the given array was created with.
    *