usearch 0.22.2 → 1.0.0

package/c/lib.cpp

@@ -1,6 +1,6 @@
 #include <cassert>
 
-#include <usearch/index_punned_dense.hpp>
+#include <usearch/index_dense.hpp>
 
 #ifndef USEARCH_EXPORT
 #define USEARCH_EXPORT
@@ -13,13 +13,12 @@ extern "C" {
 using namespace unum::usearch;
 using namespace unum;
 
-using label_t = usearch_label_t;
-using distance_t = usearch_distance_t;
-using index_t = index_punned_dense_gt<label_t>;
-using add_result_t = index_t::add_result_t;
-using search_result_t = index_t::search_result_t;
-using serialization_result_t = index_t::serialization_result_t;
-using vector_view_t = span_gt<float>;
+using add_result_t = typename index_dense_t::add_result_t;
+using search_result_t = typename index_dense_t::search_result_t;
+using labeling_result_t = typename index_dense_t::labeling_result_t;
+
+static_assert(std::is_same<usearch_key_t, index_dense_t::key_t>::value, "Type mismatch between C and C++");
+static_assert(std::is_same<usearch_distance_t, index_dense_t::distance_t>::value, "Type mismatch between C and C++");
 
 // helper functions that are not part of the C ABI
 metric_kind_t to_native_metric(usearch_metric_kind_t kind) {
@@ -42,133 +41,139 @@ scalar_kind_t to_native_scalar(usearch_scalar_kind_t kind) {
     case usearch_scalar_f32_k: return scalar_kind_t::f32_k;
     case usearch_scalar_f64_k: return scalar_kind_t::f64_k;
     case usearch_scalar_f16_k: return scalar_kind_t::f16_k;
-    case usearch_scalar_f8_k: return scalar_kind_t::f8_k;
+    case usearch_scalar_i8_k: return scalar_kind_t::i8_k;
     case usearch_scalar_b1_k: return scalar_kind_t::b1x8_k;
     default: return scalar_kind_t::unknown_k;
     }
 }
 
-add_result_t add_(index_t* index, usearch_label_t label, void const* vector, scalar_kind_t kind) {
+add_result_t add_(index_dense_t* index, usearch_key_t key, void const* vector, scalar_kind_t kind) {
     switch (kind) {
-    case scalar_kind_t::f32_k: return index->add(label, (f32_t const*)vector);
-    case scalar_kind_t::f64_k: return index->add(label, (f64_t const*)vector);
-    case scalar_kind_t::f16_k: return index->add(label, (f16_t const*)vector);
-    case scalar_kind_t::f8_k: return index->add(label, (f8_bits_t const*)vector);
-    case scalar_kind_t::b1x8_k: return index->add(label, (b1x8_t const*)vector);
+    case scalar_kind_t::f32_k: return index->add(key, (f32_t const*)vector);
+    case scalar_kind_t::f64_k: return index->add(key, (f64_t const*)vector);
+    case scalar_kind_t::f16_k: return index->add(key, (f16_t const*)vector);
+    case scalar_kind_t::i8_k: return index->add(key, (i8_bits_t const*)vector);
+    case scalar_kind_t::b1x8_k: return index->add(key, (b1x8_t const*)vector);
     default: return add_result_t{}.failed("Unknown scalar kind!");
     }
 }
 
-bool get_(index_t* index, label_t label, void* vector, scalar_kind_t kind) {
+bool get_(index_dense_t* index, usearch_key_t key, void* vector, scalar_kind_t kind) {
     switch (kind) {
-    case scalar_kind_t::f32_k: return index->get(label, (f32_t*)vector);
-    case scalar_kind_t::f64_k: return index->get(label, (f64_t*)vector);
-    case scalar_kind_t::f16_k: return index->get(label, (f16_t*)vector);
-    case scalar_kind_t::f8_k: return index->get(label, (f8_bits_t*)vector);
-    case scalar_kind_t::b1x8_k: return index->get(label, (b1x8_t*)vector);
-    default: return index->empty_search_result().failed("Unknown scalar kind!");
+    case scalar_kind_t::f32_k: return index->get(key, (f32_t*)vector);
+    case scalar_kind_t::f64_k: return index->get(key, (f64_t*)vector);
+    case scalar_kind_t::f16_k: return index->get(key, (f16_t*)vector);
+    case scalar_kind_t::i8_k: return index->get(key, (i8_bits_t*)vector);
+    case scalar_kind_t::b1x8_k: return index->get(key, (b1x8_t*)vector);
+    default: return search_result_t().failed("Unknown scalar kind!");
     }
 }
 
-search_result_t search_(index_t* index, void const* vector, scalar_kind_t kind, size_t n) {
+search_result_t search_(index_dense_t* index, void const* vector, scalar_kind_t kind, size_t n) {
     switch (kind) {
     case scalar_kind_t::f32_k: return index->search((f32_t const*)vector, n);
     case scalar_kind_t::f64_k: return index->search((f64_t const*)vector, n);
     case scalar_kind_t::f16_k: return index->search((f16_t const*)vector, n);
-    case scalar_kind_t::f8_k: return index->search((f8_bits_t const*)vector, n);
+    case scalar_kind_t::i8_k: return index->search((i8_bits_t const*)vector, n);
     case scalar_kind_t::b1x8_k: return index->search((b1x8_t const*)vector, n);
-    default: return index->empty_search_result().failed("Unknown scalar kind!");
+    default: return search_result_t().failed("Unknown scalar kind!");
     }
 }
 
-index_punned_dense_metric_t udf(metric_kind_t kind, usearch_metric_t raw_ptr) {
-    index_punned_dense_metric_t result;
-    result.kind_ = kind;
-    result.func_ = [raw_ptr](punned_vector_view_t a, punned_vector_view_t b) -> distance_t {
-        return raw_ptr((void const*)a.data(), (void const*)b.data());
-    };
-    return result;
-}
-
 extern "C" {
 
 USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, usearch_error_t* error) {
 
     assert(options && error);
 
-    index_config_t config;
-    config.connectivity = options->connectivity;
-    index_t index =        //
-        options->metric ?  //
-            index_t::make( //
-                options->dimensions, udf(to_native_metric(options->metric_kind), options->metric), config,
-                to_native_scalar(options->quantization), options->expansion_add, options->expansion_search)
-                        :  //
-            index_t::make( //
-                options->dimensions, to_native_metric(options->metric_kind), config,
-                to_native_scalar(options->quantization), options->expansion_add, options->expansion_search);
-
-    index_t* result_ptr = new index_t(std::move(index));
+    index_dense_config_t config(options->connectivity, options->expansion_add, options->expansion_search);
+    metric_kind_t metric_kind = to_native_metric(options->metric_kind);
+    scalar_kind_t scalar_kind = to_native_scalar(options->quantization);
+
+    auto metric_lambda = [options](byte_t const* a, byte_t const* b) -> usearch_distance_t {
+        return options->metric((void const*)a, (void const*)b);
+    };
+    metric_punned_t metric = //
+        options->metric ? metric_punned_t(metric_lambda, options->dimensions, metric_kind, scalar_kind)
+                        : metric_punned_t(options->dimensions, metric_kind, scalar_kind);
+
+    index_dense_t index = index_dense_t::make(metric, config);
+    index_dense_t* result_ptr = new index_dense_t(std::move(index));
     return result_ptr;
 }
 
-USEARCH_EXPORT void usearch_free(usearch_index_t index, usearch_error_t*) { delete reinterpret_cast<index_t*>(index); }
+USEARCH_EXPORT void usearch_free(usearch_index_t index, usearch_error_t*) {
+    delete reinterpret_cast<index_dense_t*>(index);
+}
 
 USEARCH_EXPORT void usearch_save(usearch_index_t index, char const* path, usearch_error_t* error) {
-    serialization_result_t result = reinterpret_cast<index_t*>(index)->save(path);
+
+    assert(index && path && error);
+    serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->save(path);
     if (!result)
         *error = result.error.what();
 }
 
 USEARCH_EXPORT void usearch_load(usearch_index_t index, char const* path, usearch_error_t* error) {
-    serialization_result_t result = reinterpret_cast<index_t*>(index)->load(path);
+
+    assert(index && path && error);
+    serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->load(path);
     if (!result)
         *error = result.error.what();
 }
 
 USEARCH_EXPORT void usearch_view(usearch_index_t index, char const* path, usearch_error_t* error) {
-    serialization_result_t result = reinterpret_cast<index_t*>(index)->view(path);
+
+    assert(index && path && error);
+    serialization_result_t result = reinterpret_cast<index_dense_t*>(index)->view(path);
     if (!result)
         *error = result.error.what();
 }
 
 USEARCH_EXPORT size_t usearch_size(usearch_index_t index, usearch_error_t*) { //
-    return reinterpret_cast<index_t*>(index)->size();
+    return reinterpret_cast<index_dense_t*>(index)->size();
 }
 
 USEARCH_EXPORT size_t usearch_capacity(usearch_index_t index, usearch_error_t*) {
-    return reinterpret_cast<index_t*>(index)->capacity();
+    return reinterpret_cast<index_dense_t*>(index)->capacity();
 }
 
 USEARCH_EXPORT size_t usearch_dimensions(usearch_index_t index, usearch_error_t*) {
-    return reinterpret_cast<index_t*>(index)->dimensions();
+    return reinterpret_cast<index_dense_t*>(index)->dimensions();
 }
 
 USEARCH_EXPORT size_t usearch_connectivity(usearch_index_t index, usearch_error_t*) {
-    return reinterpret_cast<index_t*>(index)->connectivity();
+    return reinterpret_cast<index_dense_t*>(index)->connectivity();
 }
 
-USEARCH_EXPORT void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t*) {
-    // TODO: Consider returning the new capacity.
-    reinterpret_cast<index_t*>(index)->reserve(capacity);
+USEARCH_EXPORT void usearch_reserve(usearch_index_t index, size_t capacity, usearch_error_t* error) {
+    assert(index && error);
+    if (!reinterpret_cast<index_dense_t*>(index)->reserve(capacity))
+        *error = "Out of memory!";
 }
 
-USEARCH_EXPORT void usearch_add(                                                                          //
-    usearch_index_t index, usearch_label_t label, void const* vector, usearch_scalar_kind_t kind, //
+USEARCH_EXPORT void usearch_add(                                                              //
+    usearch_index_t index, usearch_key_t key, void const* vector, usearch_scalar_kind_t kind, //
     usearch_error_t* error) {
-    add_result_t result = add_(reinterpret_cast<index_t*>(index), label, vector, to_native_scalar(kind));
+
+    assert(index && vector && error);
+    add_result_t result = add_(reinterpret_cast<index_dense_t*>(index), key, vector, to_native_scalar(kind));
     if (!result)
         *error = result.error.what();
 }
 
-USEARCH_EXPORT bool usearch_contains(usearch_index_t index, usearch_label_t label, usearch_error_t*) {
-    return reinterpret_cast<index_t*>(index)->contains(label);
+USEARCH_EXPORT bool usearch_contains(usearch_index_t index, usearch_key_t key, usearch_error_t*) {
+    assert(index);
+    return reinterpret_cast<index_dense_t*>(index)->contains(key);
 }
 
-USEARCH_EXPORT size_t usearch_search(                                                                    //
+USEARCH_EXPORT size_t usearch_search(                                                            //
     usearch_index_t index, void const* vector, usearch_scalar_kind_t kind, size_t results_limit, //
-    usearch_label_t* found_labels, usearch_distance_t* found_distances, usearch_error_t* error) {
-    search_result_t result = search_(reinterpret_cast<index_t*>(index), vector, to_native_scalar(kind), results_limit);
+    usearch_key_t* found_labels, usearch_distance_t* found_distances, usearch_error_t* error) {
+
+    assert(index && vector && error);
+    search_result_t result =
+        search_(reinterpret_cast<index_dense_t*>(index), vector, to_native_scalar(kind), results_limit);
     if (!result) {
         *error = result.error.what();
         return 0;
@@ -177,14 +182,20 @@ USEARCH_EXPORT size_t usearch_search(
     return result.dump_to(found_labels, found_distances);
 }
 
-USEARCH_EXPORT bool usearch_get(                          //
-    usearch_index_t index, usearch_label_t label, //
+USEARCH_EXPORT bool usearch_get(              //
+    usearch_index_t index, usearch_key_t key, //
     void* vector, usearch_scalar_kind_t kind, usearch_error_t*) {
-    return get_(reinterpret_cast<index_t*>(index), label, vector, to_native_scalar(kind));
+
+    assert(index && vector);
+    return get_(reinterpret_cast<index_dense_t*>(index), key, vector, to_native_scalar(kind));
 }
 
-USEARCH_EXPORT void usearch_remove(usearch_index_t, usearch_label_t, usearch_error_t* error) {
-    if (error != nullptr)
-        *error = "USearch does not support removal of elements yet.";
+USEARCH_EXPORT bool usearch_remove(usearch_index_t index, usearch_key_t key, usearch_error_t* error) {
+
+    assert(index && error);
+    labeling_result_t result = reinterpret_cast<index_dense_t*>(index)->remove(key);
+    if (!result)
+        *error = result.error.what();
+    return result.completed;
 }
 }

package/c/test.c

@@ -107,8 +107,8 @@ void test_add_vector(size_t vectors_count, size_t vector_dimension, float const*
 
     // Add vectors
     for (size_t i = 0; i < vectors_count; ++i) {
-        usearch_label_t label = i;
-        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        usearch_key_t key = i;
+        usearch_add(idx, key, data + i * vector_dimension, usearch_scalar_f32_k, &error);
         ASSERT(!error, error);
     }
 
@@ -117,10 +117,10 @@ void test_add_vector(size_t vectors_count, size_t vector_dimension, float const*
 
     // Check vectors in the index
     for (size_t i = 0; i < vectors_count; ++i) {
-        usearch_label_t label = i;
-        ASSERT(usearch_contains(idx, label, &error), error);
+        usearch_key_t key = i;
+        ASSERT(usearch_contains(idx, key, &error), error);
     }
-    ASSERT(!usearch_contains(idx, -1, &error), error); // Non existing label
+    ASSERT(!usearch_contains(idx, -1, &error), error); // Non existing key
 
     usearch_free(idx, &error);
     printf("Test: Add Vector - PASSED\n");
@@ -137,21 +137,21 @@ void test_find_vector(size_t vectors_count, size_t vector_dimension, float const
 
     // Create result buffers
     int results_count = 10;
-    usearch_label_t* labels = (usearch_label_t*)malloc(results_count * sizeof(usearch_label_t));
+    usearch_key_t* keys = (usearch_key_t*)malloc(results_count * sizeof(usearch_key_t));
     float* distances = (float*)malloc(results_count * sizeof(float));
-    ASSERT(labels && distances, "Failed to allocate memory");
+    ASSERT(keys && distances, "Failed to allocate memory");
 
     // Add vectors
     for (size_t i = 0; i < vectors_count; ++i) {
-        usearch_label_t label = i;
-        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        usearch_key_t key = i;
+        usearch_add(idx, key, data + i * vector_dimension, usearch_scalar_f32_k, &error);
         ASSERT(!error, error);
     }
 
     // Find the vectors
     for (size_t i = 0; i < vectors_count; i++) {
         const void *query_vector = data + i * vector_dimension;
-        size_t found_count = usearch_search(idx, query_vector, usearch_scalar_f32_k, results_count, labels, distances, &error);
+        size_t found_count = usearch_search(idx, query_vector, usearch_scalar_f32_k, results_count, keys, distances, &error);
         ASSERT(!error, error);
         ASSERT(found_count = results_count, "Vector is missing");
     }
@@ -171,15 +171,15 @@ void test_remove_vector(size_t vectors_count, size_t vector_dimension, float con
 
     // Add vectors
     for (size_t i = 0; i < vectors_count; ++i) {
-        usearch_label_t label = i;
-        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        usearch_key_t key = i;
+        usearch_add(idx, key, data + i * vector_dimension, usearch_scalar_f32_k, &error);
         ASSERT(!error, error);
     }
 
     // Remove the vectors
     for (size_t i = 0; i < vectors_count; i++) {
-        usearch_label_t label = i;
-        usearch_remove(idx, label, &error);
+        usearch_key_t key = i;
+        usearch_remove(idx, key, &error);
         ASSERT(error, "Currently, Remove is not supported");
     }
 
@@ -198,8 +198,8 @@ void test_save_load(size_t vectors_count, size_t vector_dimension, float const*
 
     // Add vectors
     for (size_t i = 0; i < vectors_count; ++i) {
-        usearch_label_t label = i;
-        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        usearch_key_t key = i;
+        usearch_add(idx, key, data + i * vector_dimension, usearch_scalar_f32_k, &error);
         ASSERT(!error, error);
     }
 
@@ -224,8 +224,8 @@ void test_save_load(size_t vectors_count, size_t vector_dimension, float const*
 
     // Check vectors in the index
     for (size_t i = 0; i < vectors_count; ++i) {
-        usearch_label_t label = i;
-        ASSERT(usearch_contains(idx, label, &error), error);
+        usearch_key_t key = i;
+        ASSERT(usearch_contains(idx, key, &error), error);
     }
 
     usearch_free(idx, &error);
@@ -243,8 +243,8 @@ void test_view(size_t vectors_count, size_t vector_dimension, float const* data)
 
     // Add vectors
     for (size_t i = 0; i < vectors_count; ++i) {
-        usearch_label_t label = i;
-        usearch_add(idx, label, data + i * vector_dimension, usearch_scalar_f32_k, &error);
+        usearch_key_t key = i;
+        usearch_add(idx, key, data + i * vector_dimension, usearch_scalar_f32_k, &error);
         ASSERT(!error, error);
     }
 

package/c/usearch.h

@@ -1,6 +1,6 @@
 #ifndef UNUM_USEARCH_H
 #define UNUM_USEARCH_H
-// in case the header is included from cpp code
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -11,79 +11,179 @@ extern "C" {
 #include <stdint.h>  // `size_t`
 
 USEARCH_EXPORT typedef void* usearch_index_t;
-USEARCH_EXPORT typedef uint32_t usearch_label_t;
+USEARCH_EXPORT typedef uint64_t usearch_key_t;
 USEARCH_EXPORT typedef float usearch_distance_t;
+
+/**
+ *  @brief  Pointer to a null-terminated error message.
+ *          Returned error messages @b don't need to be deallocated.
+ */
 USEARCH_EXPORT typedef char const* usearch_error_t;
 
+/**
+ *  @brief  Type-punned callback for "metrics" or "distance functions",
+ *          that accepts pointers to two vectors and measures their @b dis-similarity.
+ */
 USEARCH_EXPORT typedef usearch_distance_t (*usearch_metric_t)(void const*, void const*);
 
+/**
+ *  @brief  Enumerator for the most common kinds of `usearch_metric_t`.
+ *          Those are supported out of the box, with SIMD-optimizations for most common hardware.
+ */
 USEARCH_EXPORT typedef enum usearch_metric_kind_t {
-    usearch_metric_ip_k = 0,
-    usearch_metric_l2sq_k,
+    usearch_metric_unknown_k = 0,
     usearch_metric_cos_k,
+    usearch_metric_ip_k,
+    usearch_metric_l2sq_k,
     usearch_metric_haversine_k,
     usearch_metric_pearson_k,
     usearch_metric_jaccard_k,
     usearch_metric_hamming_k,
     usearch_metric_tanimoto_k,
     usearch_metric_sorensen_k,
-    usearch_metric_unknown_k,
 } usearch_metric_kind_t;
 
 USEARCH_EXPORT typedef enum usearch_scalar_kind_t {
-    usearch_scalar_f32_k = 0,
+    usearch_scalar_unknown_k = 0,
+    usearch_scalar_f32_k,
     usearch_scalar_f64_k,
     usearch_scalar_f16_k,
-    usearch_scalar_f8_k,
+    usearch_scalar_i8_k,
     usearch_scalar_b1_k,
-    usearch_scalar_unknown_k,
 } usearch_scalar_kind_t;
 
 USEARCH_EXPORT typedef struct usearch_init_options_t {
-
+    /**
+     *  @brief The metric kind used for distance calculation between vectors.
+     */
     usearch_metric_kind_t metric_kind;
+    /**
+     *  @brief The @b optional custom distance metric function used for distance calculation between vectors.
+     *  If the `metric_kind` is set to `usearch_metric_unknown_k`, this function pointer mustn't be `NULL`.
+     */
     usearch_metric_t metric;
-
+    /**
+     *  @brief The scalar kind used for quantization of vector data during indexing.
+     */
     usearch_scalar_kind_t quantization;
+    /**
+     *  @brief The number of dimensions in the vectors to be indexed.
+     *  Must be defined for most metrics, but can be avoided for `usearch_metric_haversine_k`.
+     */
     size_t dimensions;
+    /**
+     *  @brief The @b optional connectivity parameter that limits connections-per-node in graph.
+     */
     size_t connectivity;
+    /**
+     *  @brief The @b optional expansion factor used for index construction when adding vectors.
+     */
     size_t expansion_add;
+    /**
+     *  @brief The @b optional expansion factor used for index construction during search operations.
+     */
     size_t expansion_search;
 } usearch_init_options_t;
 
-USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t*, usearch_error_t*);
-USEARCH_EXPORT void usearch_free(usearch_index_t, usearch_error_t*);
+/**
+ *  @brief Initializes a new instance of the index.
+ *  @param options Pointer to the `usearch_init_options_t` structure containing initialization options.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return A handle to the initialized USearch index, or `NULL` on failure.
+ */
+USEARCH_EXPORT usearch_index_t usearch_init(usearch_init_options_t* options, usearch_error_t* error);
 
-USEARCH_EXPORT void usearch_save(usearch_index_t, char const* path, usearch_error_t*);
-USEARCH_EXPORT void usearch_load(usearch_index_t, char const* path, usearch_error_t*);
-USEARCH_EXPORT void usearch_view(usearch_index_t, char const* path, usearch_error_t*);
+/**
+ *  @brief Frees the resources associated with the index.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_free(usearch_index_t, usearch_error_t* error);
 
-USEARCH_EXPORT size_t usearch_size(usearch_index_t, usearch_error_t*);
-USEARCH_EXPORT size_t usearch_capacity(usearch_index_t, usearch_error_t*);
-USEARCH_EXPORT size_t usearch_dimensions(usearch_index_t, usearch_error_t*);
-USEARCH_EXPORT size_t usearch_connectivity(usearch_index_t, usearch_error_t*);
+/**
+ *  @brief Saves the index to a file.
+ *  @param[in] path The file path where the index will be saved.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_save(usearch_index_t, char const* path, usearch_error_t* error);
 
-USEARCH_EXPORT void usearch_reserve(usearch_index_t, size_t capacity, usearch_error_t*);
+/**
+ *  @brief Loads the index from a file.
+ *  @param[in] path The file path from where the index will be loaded.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_load(usearch_index_t, char const* path, usearch_error_t* error);
 
-USEARCH_EXPORT void usearch_add(                                                                     //
-    usearch_index_t, usearch_label_t, void const* vector, usearch_scalar_kind_t vector_kind, //
-    usearch_error_t*);
+/**
+ *  @brief Creates a view of the index from a file without loading it into memory.
+ *  @param[in] path The file path from where the view will be created.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_view(usearch_index_t, char const* path, usearch_error_t* error);
 
-USEARCH_EXPORT bool usearch_contains(usearch_index_t, usearch_label_t, usearch_error_t*);
+USEARCH_EXPORT size_t usearch_size(usearch_index_t, usearch_error_t* error);
+USEARCH_EXPORT size_t usearch_capacity(usearch_index_t, usearch_error_t* error);
+USEARCH_EXPORT size_t usearch_dimensions(usearch_index_t, usearch_error_t* error);
+USEARCH_EXPORT size_t usearch_connectivity(usearch_index_t, usearch_error_t* error);
 
 /**
- *  @brief      Performs k-Approximate Nearest Neighbors Search.
- *  @return     Number of found matches.
+ *  @brief Reserves memory for a specified number of incoming vectors.
+ *  @param[in] capacity The desired total capacity including current size.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
  */
-USEARCH_EXPORT size_t usearch_search(                                                                          //
+USEARCH_EXPORT void usearch_reserve(usearch_index_t, size_t capacity, usearch_error_t* error);
+
+/**
+ *  @brief Adds a vector with a key to the index.
+ *  @param[in] key The key associated with the vector.
+ *  @param[in] vector Pointer to the vector data.
+ *  @param[in] vector_kind The scalar type used in the vector data.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ */
+USEARCH_EXPORT void usearch_add(        //
+    usearch_index_t, usearch_key_t key, //
+    void const* vector, usearch_scalar_kind_t vector_kind, usearch_error_t* error);
+
+/**
+ *  @brief Checks if the index contains a vector with a specific key.
+ *  @param[in] key The key to be checked.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return `true` if the index contains the vector with the given key, `false` otherwise.
+ */
+USEARCH_EXPORT bool usearch_contains(usearch_index_t, usearch_key_t, usearch_error_t* error);
+
+/**
+ *  @brief Performs k-Approximate Nearest Neighbors (kANN) Search for closest vectors to query.
+ *  @param[in] query_vector Pointer to the query vector data.
+ *  @param[in] query_kind The scalar type used in the query vector data.
+ *  @param[in] results_limit Upper bound on the number of neighbors to search, the "k" in "kANN".
+ *  @param[out] found_keys Output buffer for up to `results_limit` nearest neighbors keys.
+ *  @param[out] found_distances Output buffer for up to `results_limit` distances to nearest neighbors.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return Number of found matches.
+ */
+USEARCH_EXPORT size_t usearch_search(                                                                  //
     usearch_index_t, void const* query_vector, usearch_scalar_kind_t query_kind, size_t results_limit, //
-    usearch_label_t* found_labels, usearch_distance_t* found_distances, usearch_error_t*);
+    usearch_key_t* found_keys, usearch_distance_t* found_distances, usearch_error_t* error);
 
-USEARCH_EXPORT bool usearch_get(              //
-    usearch_index_t, usearch_label_t, //
-    void* vector, usearch_scalar_kind_t vector_kind, usearch_error_t*);
+/**
+ *  @brief Retrieves the vector associated with the given key from the index.
+ *  @param[in] key The key of the vector to retrieve.
+ *  @param[out] vector Pointer to the memory where the vector data will be copied.
+ *  @param[in] vector_kind The scalar type used in the vector data.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return `true` if the vector is successfully retrieved, `false` if the vector is not found.
+ */
+USEARCH_EXPORT bool usearch_get(        //
+    usearch_index_t, usearch_key_t key, //
+    void* vector, usearch_scalar_kind_t vector_kind, usearch_error_t* error);
 
-USEARCH_EXPORT void usearch_remove(usearch_index_t, usearch_label_t, usearch_error_t*);
+/**
+ *  @brief Removes the vector associated with the given key from the index.
+ *  @param[in] key The key of the vector to be removed.
+ *  @param[out] error Pointer to a string where the error message will be stored, if an error occurs.
+ *  @return `true` if the vector is successfully removed, `false` if the vector is not found.
+ */
+USEARCH_EXPORT bool usearch_remove(usearch_index_t, usearch_key_t key, usearch_error_t* error);
 
 #ifdef __cplusplus
 }

package/conanfile.py

@@ -4,7 +4,7 @@ from conans import ConanFile
 class USearchConan(ConanFile):
 
     name = 'USearch'
-    version = '0.22.2'
+    version = '1.0.0'
     license = 'Apache 2.0'
     url = 'https://github.com/unum-cloud/usearch'
     description = 'Smaller & Faster Single-File Vector Search Engine from Unum'

package/cpp/CMakeLists.txt

@@ -83,6 +83,7 @@ if(${USEARCH_BUILD_TEST})
     target_link_libraries(test PRIVATE Threads::Threads)
     target_include_directories(test PRIVATE ${USEARCH_PUNNED_INCLUDE_DIRS})
     set_target_properties(test PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+    set_target_properties(test PROPERTIES CXX_STANDARD 17)
 
     if(${CMAKE_VERSION} VERSION_EQUAL 3.13 OR ${CMAKE_VERSION} VERSION_GREATER 3.13)
         include(CTest)
@@ -96,6 +97,7 @@ if(${USEARCH_BUILD_BENCHMARK})
     target_link_libraries(bench PRIVATE Threads::Threads)
     target_include_directories(bench PRIVATE ${USEARCH_PUNNED_INCLUDE_DIRS})
     set_target_properties(bench PROPERTIES RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
+    set_target_properties(bench PROPERTIES CXX_STANDARD 17)
 
     if(${USEARCH_USE_SIMSIMD})
         target_compile_definitions(bench PRIVATE USEARCH_USE_SIMSIMD=1)
@@ -107,6 +109,6 @@ if(${USEARCH_BUILD_BENCHMARK})
     endif()
 
     if(${USEARCH_USE_JEMALLOC})
-        target_link_libraries(bench PRIVATE ${JEMALLOC_LIBRARIES})
+        target_link_libraries(bench PRIVATE ${JEMALLOC_LIBRARIES})        
     endif()
 endif()