Improve: usearch_remove C99 interface

c/lib.cpp

@@ -18,6 +18,7 @@ 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 labeling_result_t = index_t::labeling_result_t;
 using serialization_result_t = index_t::serialization_result_t;
 using vector_view_t = span_gt<float>;
 
@@ -153,7 +154,7 @@ USEARCH_EXPORT void usearch_reserve(usearch_index_t index, size_t capacity, usea
     reinterpret_cast<index_t*>(index)->reserve(capacity);
 }
 
-USEARCH_EXPORT void usearch_add(                                                                          //
+USEARCH_EXPORT void usearch_add(                                                                  //
     usearch_index_t index, usearch_label_t label, 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));
@@ -165,7 +166,7 @@ USEARCH_EXPORT bool usearch_contains(usearch_index_t index, usearch_label_t labe
     return reinterpret_cast<index_t*>(index)->contains(label);
 }
 
-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);
@@ -177,14 +178,16 @@ USEARCH_EXPORT size_t usearch_search(
     return result.dump_to(found_labels, found_distances);
 }
 
-USEARCH_EXPORT bool usearch_get(                          //
+USEARCH_EXPORT bool usearch_get(                  //
     usearch_index_t index, usearch_label_t label, //
     void* vector, usearch_scalar_kind_t kind, usearch_error_t*) {
     return get_(reinterpret_cast<index_t*>(index), label, 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_label_t label, usearch_error_t* error) {
+    labeling_result_t result = reinterpret_cast<index_t*>(index)->remove(label);
+    if (!result)
+        *error = result.error.what();
+    return result.completed;
 }
 }

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
@@ -40,50 +40,131 @@ USEARCH_EXPORT typedef enum usearch_scalar_kind_t {
 } 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);
+
+/**
+ *  @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);
+
+/**
+ *  @brief Saves the index to a file.
+ *  @param 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);
+
+/**
+ *  @brief Loads the index from a file.
+ *  @param 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_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 Creates a view of the index from a file without loading it into memory.
+ *  @param 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 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*);
+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);
 
-USEARCH_EXPORT void usearch_reserve(usearch_index_t, size_t capacity, usearch_error_t*);
+/**
+ *  @brief Reserves memory for a specified number of incoming vectors.
+ *  @param 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 void usearch_reserve(usearch_index_t, size_t capacity, 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 Adds a vector with a label to the index.
+ *  @param label The label associated with the vector.
+ *  @param vector Pointer to the vector data.
+ *  @param 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_label_t label, //
+    void const* vector, usearch_scalar_kind_t vector_kind, usearch_error_t* error);
 
-USEARCH_EXPORT bool usearch_contains(usearch_index_t, usearch_label_t, usearch_error_t*);
+/**
+ *  @brief Checks if the index contains a vector with a specific label.
+ *  @param label The label 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 label, `false` otherwise.
+ */
+USEARCH_EXPORT bool usearch_contains(usearch_index_t, usearch_label_t, usearch_error_t* error);
 
 /**
- *  @brief      Performs k-Approximate Nearest Neighbors Search.
- *  @return     Number of found matches.
+ *  @brief Performs k-Approximate Nearest Neighbors Search.
+ *  @return Number of found matches.
  */
-USEARCH_EXPORT size_t usearch_search(                                                                          //
+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_label_t* found_labels, 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 label from the index.
+ *  @param label The label of the vector to retrieve.
+ *  @param[out] vector Pointer to the memory where the vector data will be copied.
+ *  @param 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_label_t label, //
+    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 label from the index.
+ *  @param label The label 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_label_t label, usearch_error_t* error);
 
 #ifdef __cplusplus
 }

cpp/README.md

@@ -1,4 +1,4 @@
-# USearch C++ Inteface
+# USearch for C++
 
 ## Installation
 

docs/c/reference.rst

@@ -1,7 +1,7 @@
 API Reference
 ===============
 
-===============
-usearch
-===============
+==================
+usearch/usearch.h
+==================
 .. doxygenfile:: usearch.h

docs/compilation.md

@@ -203,7 +203,7 @@ swift test -v
 Linux:
 
 ```sh
-g++ -shared -fPIC lib.cpp -I ../include/  -I ../fp16/include/ -o libusearch.so
+g++ -std=c++11 -shared -fPIC c/lib.cpp -I ./include/  -I ./fp16/include/ -I ./robin-map/include/ -o libusearch.so
 ```
 
 ## Docker

docs/cpp/index.rst

@@ -1,5 +1,5 @@
 =====================
-USearch for C++
+C++ SDK
 =====================