Add: Java get API (#407)

Author: mccullocht

build.gradle

@@ -86,6 +86,7 @@ model {
     }
 
     toolChains {
+        clang(Clang)
         gcc(Gcc) {
             target("linux_aarch64") {
                 cppCompiler.withArguments { args ->

java/cloud/unum/usearch/Index.java

@@ -122,6 +122,17 @@ public int[] search(float vector[], long count) {
     return c_search(c_ptr, vector, count);
   }
 
+  /**
+   * Return the contents of the vector at key.
+   * 
+   * @param key key to lookup.
+   * @return the contents of the vector.
+   * @throws {@link IllegalArgumentException} is key is not available.
+   */
+  public float[] get(int key) {
+    return c_get(c_ptr, key);
+  }
+
   /**
    * Saves the index to a file.
    *
@@ -296,7 +307,11 @@ public Config expansion_search(long _expansion_search) {
       System.loadLibrary("usearch"); // used for tests. This library in classpath only
     } catch (UnsatisfiedLinkError e) {
       try {
-        NativeUtils.loadLibraryFromJar("/usearch/libusearch.so");
+        if (System.getProperty("os.name").equals("Mac OS X")) {
+          NativeUtils.loadLibraryFromJar("/usearch/libusearch.dylib");
+        } else {
+          NativeUtils.loadLibraryFromJar("/usearch/libusearch.so");
+        }
       } catch (IOException e1) {
         throw new RuntimeException(e1);
       }
@@ -339,6 +354,8 @@ private static native long c_create(
 
   private static native int[] c_search(long ptr, float vector[], long count);
 
+  private static native float[] c_get(long ptr, int key);
+
   private static native void c_save(long ptr, String path);
 
   private static native void c_load(long ptr, String path);

java/cloud/unum/usearch/cloud_unum_usearch_Index.cpp

@@ -141,6 +141,26 @@ JNIEXPORT void JNICALL Java_cloud_unum_usearch_Index_c_1add( //
     (*env).ReleaseFloatArrayElements(vector, vector_data, 0);
 }
 
+JNIEXPORT jfloatArray JNICALL Java_cloud_unum_usearch_Index_c_1get(
+    JNIEnv *env, jclass, jlong c_ptr, jint key) {
+    
+    auto index = reinterpret_cast<index_dense_t*>(c_ptr);
+    size_t dim = index->dimensions();
+    std::unique_ptr<jfloat[]> vector(new jfloat[dim]);
+    if (index->get(key, vector.get()) == 0) {
+        jclass jc = env->FindClass("java/lang/IllegalArgumentException");
+        if (jc) {
+            env->ThrowNew(jc, "key not found");
+        }
+    }
+    jfloatArray jvector = env->NewFloatArray(dim);
+    if (jvector == nullptr) {  // out of memory
+        return nullptr;
+    }
+    env->SetFloatArrayRegion(jvector, 0, dim, vector.get());
+    return jvector;
+}
+
 JNIEXPORT jintArray JNICALL Java_cloud_unum_usearch_Index_c_1search( //
     JNIEnv* env, jclass, jlong c_ptr, jfloatArray vector, jlong wanted) {
 

java/cloud/unum/usearch/cloud_unum_usearch_Index.h

@@ -1,5 +1,7 @@
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertThrows;
+
 import java.io.File;
-import java.util.Arrays;
 
 import org.junit.Test;
 
@@ -28,4 +30,22 @@ public void test() {
 
         System.out.println("Java Tests Passed!");
     }
+
+    public void testGetSuccess() {
+        Index index = new Index.Config().metric("cos").dimensions(2).build();
+        float vec[] = { 10, 20 };
+        index.reserve(10);
+        index.add(42, vec);
+
+        assertArrayEquals(vec, index.get(42), 0.01f);
+    }
+
+    public void testGetFailed() {
+        Index index = new Index.Config().metric("cos").dimensions(2).build();
+        float vec[] = { 10, 20 };
+        index.reserve(10);
+        index.add(42, vec);
+
+        assertThrows(IllegalArgumentException.class, () -> index.get(41));
+    }
 }