usearch 2.8.15 → 2.9.0

package/stringzilla/swift/StringProtocol+StringZilla.swift

@@ -0,0 +1,280 @@
+//
+//  StringProtocol+StringZilla.swift
+//
+//  Created by Ash Vardanian on 18/1/24.
+//  Extension of StringProtocol to interface with StringZilla functionalities.
+//
+//  Docs:
+//  - Accessing immutable UTF8-range:
+//    https://developer.apple.com/documentation/swift/string/utf8view
+//
+//  More reading materials:
+//  - String’s ABI and UTF-8. Nov 2018
+//    https://forums.swift.org/t/string-s-abi-and-utf-8/17676
+//  - Stable pointer into a C string without copying it? Aug 2021
+//    https://forums.swift.org/t/stable-pointer-into-a-c-string-without-copying-it/51244/1
+
+import StringZillaC
+
+// We need to link the standard libraries.
+#if os(Linux)
+import Glibc
+#else
+import Darwin.C
+#endif
+
+/// Protocol defining a single-byte data type.
+fileprivate protocol SingleByte {}
+
+extension UInt8: SingleByte {}
+extension Int8: SingleByte {} // This would match `CChar` as well.
+
+@usableFromInline
+enum StringZillaError: Error {
+    case contiguousStorageUnavailable
+    case memoryAllocationFailed
+    
+    var localizedDescription: String {
+        switch self {
+        case .contiguousStorageUnavailable:
+            return "Contiguous storage for the sequence is unavailable."
+        case .memoryAllocationFailed:
+            return "Memory allocation failed."
+        }
+    }
+}
+
+/// Protocol defining the interface for StringZilla-compatible byte-spans.
+///
+/// # Discussion:
+/// The Swift documentation is extremely vague about the actual memory layout of a String
+/// and the cost of obtaining the underlying UTF8 representation or any other raw pointers.
+/// https://developer.apple.com/documentation/swift/stringprotocol/withcstring(_:)
+/// https://developer.apple.com/documentation/swift/stringprotocol/withcstring(encodedas:_:)
+/// https://developer.apple.com/documentation/swift/stringprotocol/data(using:allowlossyconversion:)
+public protocol StringZillaViewable: Collection {
+    /// A type that represents a position in the collection.
+    /// 
+    /// Executes a closure with a pointer to the string's UTF8 C representation and its length.
+    ///
+    /// - Parameters:
+    ///   - body: A closure that takes a pointer to a C string and its length.
+    /// - Throws: Can throw an error.
+    /// - Returns: Returns a value of type R, which is the result of the closure.
+    func withStringZillaScope<R>(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R
+    
+    /// Calculates the offset index for a given byte pointer relative to a start pointer.
+    ///
+    /// - Parameters:
+    ///   - bytePointer: A pointer to the byte for which the offset is calculated.
+    ///   - startPointer: The starting pointer for the calculation, previously obtained from `szScope`.
+    /// - Returns: The calculated index offset.
+    func stringZillaByteOffset(forByte bytePointer: sz_cptr_t, after startPointer: sz_cptr_t) -> Index
+}
+
+extension String: StringZillaViewable {
+    public typealias Index = String.Index
+    
+    @_transparent
+    public func withStringZillaScope<R>(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R {
+        let cLength = sz_size_t(utf8.count)
+        return try self.withCString { cString in
+            try body(cString, cLength)
+        }
+    }
+    
+    @_transparent
+    public func stringZillaByteOffset(forByte bytePointer: sz_cptr_t, after startPointer: sz_cptr_t) -> Index {
+        self.utf8.index(self.utf8.startIndex, offsetBy: bytePointer - startPointer)
+    }
+}
+
+extension Substring.UTF8View: StringZillaViewable {
+    public typealias Index = Substring.UTF8View.Index
+    
+    /// Executes a closure with a pointer to the UTF8View's contiguous storage of single-byte elements (UTF-8 code units).
+    /// - Parameters:
+    ///   - body: A closure that takes a pointer to the contiguous storage and its size.
+    /// - Throws: An error if the storage is not contiguous.
+    @_transparent
+    public func withStringZillaScope<R>(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R {
+        return try withContiguousStorageIfAvailable { bufferPointer -> R in
+            let cLength = sz_size_t(bufferPointer.count)
+            let cString = UnsafeRawPointer(bufferPointer.baseAddress!).assumingMemoryBound(to: CChar.self)
+            return try body(cString, cLength)
+        } ?? {
+            throw StringZillaError.contiguousStorageUnavailable
+        }()
+    }
+    
+    /// Calculates the offset index for a given byte pointer relative to a start pointer.
+    /// - Parameters:
+    ///   - bytePointer: A pointer to the byte for which the offset is calculated.
+    ///   - startPointer: The starting pointer for the calculation, previously obtained from `szScope`.
+    /// - Returns: The calculated index offset.
+    @_transparent
+    public func stringZillaByteOffset(forByte bytePointer: sz_cptr_t, after startPointer: sz_cptr_t) -> Index {
+        return self.index(self.startIndex, offsetBy: bytePointer - startPointer)
+    }
+}
+
+extension String.UTF8View: StringZillaViewable {
+    public typealias Index = String.UTF8View.Index
+    
+    /// Executes a closure with a pointer to the UTF8View's contiguous storage of single-byte elements (UTF-8 code units).
+    /// - Parameters:
+    ///   - body: A closure that takes a pointer to the contiguous storage and its size.
+    /// - Throws: An error if the storage is not contiguous.
+    public func withStringZillaScope<R>(_ body: (sz_cptr_t, sz_size_t) throws -> R) rethrows -> R {
+        return try withContiguousStorageIfAvailable { bufferPointer -> R in
+            let cLength = sz_size_t(bufferPointer.count)
+            let cString = UnsafeRawPointer(bufferPointer.baseAddress!).assumingMemoryBound(to: CChar.self)
+            return try body(cString, cLength)
+        } ?? {
+            throw StringZillaError.contiguousStorageUnavailable
+        }()
+    }
+    
+    /// Calculates the offset index for a given byte pointer relative to a start pointer.
+    /// - Parameters:
+    ///   - bytePointer: A pointer to the byte for which the offset is calculated.
+    ///   - startPointer: The starting pointer for the calculation, previously obtained from `szScope`.
+    /// - Returns: The calculated index offset.
+    public func stringZillaByteOffset(forByte bytePointer: sz_cptr_t, after startPointer: sz_cptr_t) -> Index {
+        return self.index(self.startIndex, offsetBy: bytePointer - startPointer)
+    }
+}
+
+public extension StringZillaViewable {
+    
+    /// Finds the first occurrence of the specified substring within the receiver.
+    /// - Parameter needle: The substring to search for.
+    /// - Returns: The index of the found occurrence, or `nil` if not found.
+    @_specialize(where Self == String, S == String)
+    @_specialize(where Self == String.UTF8View, S == String.UTF8View)
+    func findFirst<S: StringZillaViewable>(substring needle: S) -> Index? {
+        var result: Index?
+        withStringZillaScope { hPointer, hLength in
+            needle.withStringZillaScope { nPointer, nLength in
+                if let matchPointer = sz_find(hPointer, hLength, nPointer, nLength) {
+                    result = self.stringZillaByteOffset(forByte: matchPointer, after: hPointer)
+                }
+            }
+        }
+        return result
+    }
+    
+    /// Finds the last occurrence of the specified substring within the receiver.
+    /// - Parameter needle: The substring to search for.
+    /// - Returns: The index of the found occurrence, or `nil` if not found.
+    @_specialize(where Self == String, S == String)
+    @_specialize(where Self == String.UTF8View, S == String.UTF8View)
+    func findLast<S: StringZillaViewable>(substring needle: S) -> Index? {
+        var result: Index?
+        withStringZillaScope { hPointer, hLength in
+            needle.withStringZillaScope { nPointer, nLength in
+                if let matchPointer = sz_rfind(hPointer, hLength, nPointer, nLength) {
+                    result = self.stringZillaByteOffset(forByte: matchPointer, after: hPointer)
+                }
+            }
+        }
+        return result
+    }
+    
+    /// Finds the first occurrence of the specified character-set members within the receiver.
+    /// - Parameter characters: A string-like collection of characters to match.
+    /// - Returns: The index of the found occurrence, or `nil` if not found.
+    @_specialize(where Self == String, S == String)
+    @_specialize(where Self == String.UTF8View, S == String.UTF8View)
+    func findFirst<S: StringZillaViewable>(characterFrom characters: S) -> Index? {
+        var result: Index?
+        withStringZillaScope { hPointer, hLength in
+            characters.withStringZillaScope { nPointer, nLength in
+                if let matchPointer = sz_find_char_from(hPointer, hLength, nPointer, nLength) {
+                    result = self.stringZillaByteOffset(forByte: matchPointer, after: hPointer)
+                }
+            }
+        }
+        return result
+    }
+    
+    /// Finds the last occurrence of the specified character-set members within the receiver.
+    /// - Parameter characters: A string-like collection of characters to match.
+    /// - Returns: The index of the found occurrence, or `nil` if not found.
+    @_specialize(where Self == String, S == String)
+    @_specialize(where Self == String.UTF8View, S == String.UTF8View)
+    func findLast<S: StringZillaViewable>(characterFrom characters: S) -> Index? {
+        var result: Index?
+        withStringZillaScope { hPointer, hLength in
+            characters.withStringZillaScope { nPointer, nLength in
+                if let matchPointer = sz_rfind_char_from(hPointer, hLength, nPointer, nLength) {
+                    result = self.stringZillaByteOffset(forByte: matchPointer, after: hPointer)
+                }
+            }
+        }
+        return result
+    }
+    
+    /// Finds the first occurrence of a character outside of the the given character-set within the receiver.
+    /// - Parameter characters: A string-like collection of characters to exclude.
+    /// - Returns: The index of the found occurrence, or `nil` if not found.
+    @_specialize(where Self == String, S == String)
+    @_specialize(where Self == String.UTF8View, S == String.UTF8View)
+    func findFirst<S: StringZillaViewable>(characterNotFrom characters: S) -> Index? {
+        var result: Index?
+        withStringZillaScope { hPointer, hLength in
+            characters.withStringZillaScope { nPointer, nLength in
+                if let matchPointer = sz_find_char_not_from(hPointer, hLength, nPointer, nLength) {
+                    result = self.stringZillaByteOffset(forByte: matchPointer, after: hPointer)
+                }
+            }
+        }
+        return result
+    }
+    
+    /// Finds the last occurrence of a character outside of the the given character-set within the receiver.
+    /// - Parameter characters: A string-like collection of characters to exclude.
+    /// - Returns: The index of the found occurrence, or `nil` if not found.
+    @_specialize(where Self == String, S == String)
+    @_specialize(where Self == String.UTF8View, S == String.UTF8View)
+    func findLast<S: StringZillaViewable>(characterNotFrom characters: S) -> Index? {
+        var result: Index?
+        withStringZillaScope { hPointer, hLength in
+            characters.withStringZillaScope { nPointer, nLength in
+                if let matchPointer = sz_rfind_char_not_from(hPointer, hLength, nPointer, nLength) {
+                    result = self.stringZillaByteOffset(forByte: matchPointer, after: hPointer)
+                }
+            }
+        }
+        return result
+    }
+    
+    /// Computes the Levenshtein edit distance between this and another string.
+    /// - Parameter other: A string-like collection of characters to exclude.
+    /// - Returns: The edit distance, as an unsigned integer.
+    /// - Throws: If a memory allocation error has happened.
+    @_specialize(where Self == String, S == String)
+    @_specialize(where Self == String.UTF8View, S == String.UTF8View)
+    func editDistance<S: StringZillaViewable>(from other: S, bound: UInt64 = 0) throws -> UInt64? {
+        var result: UInt64?
+        
+        // Use a do-catch block to handle potential errors
+        do {
+            try withStringZillaScope { hPointer, hLength in
+                try other.withStringZillaScope { nPointer, nLength in
+                    result = UInt64(sz_edit_distance(hPointer, hLength, nPointer, nLength, sz_size_t(bound), nil))
+                    if result == SZ_SIZE_MAX {
+                        result = nil
+                        throw StringZillaError.memoryAllocationFailed
+                    }
+                }
+            }
+        } catch {
+            // Handle or rethrow the error
+            throw error
+        }
+        
+        return result
+    }
+    
+}

package/stringzilla/swift/Test.swift

@@ -0,0 +1,60 @@
+//
+//  Test.swift
+//
+//
+//  Created by Ash Vardanian on 18/1/24.
+//
+
+import XCTest
+@testable import StringZilla
+
+class StringZillaTests: XCTestCase {
+    
+    var testString: String!
+    
+    override func setUp() {
+        super.setUp()
+        testString = "Hello, world! Welcome to StringZilla. 👋"
+        XCTAssertEqual(testString.count, 39)
+        XCTAssertEqual(testString.utf8.count, 42)
+    }
+    
+    func testFindFirstSubstring() {
+        let index = testString.findFirst(substring: "world")!
+        XCTAssertEqual(testString[index...], "world! Welcome to StringZilla. 👋")
+    }
+    
+    func testFindLastSubstring() {
+        let index = testString.findLast(substring: "o")!
+        XCTAssertEqual(testString[index...], "o StringZilla. 👋")
+    }
+    
+    func testFindFirstCharacterFromSet() {
+        let index = testString.findFirst(characterFrom: "aeiou")!
+        XCTAssertEqual(testString[index...], "ello, world! Welcome to StringZilla. 👋")
+    }
+    
+    func testFindLastCharacterFromSet() {
+        let index = testString.findLast(characterFrom: "aeiou")!
+        XCTAssertEqual(testString[index...], "a. 👋")
+    }
+    
+    func testFindFirstCharacterNotFromSet() {
+        let index = testString.findFirst(characterNotFrom: "aeiou")!
+        XCTAssertEqual(testString[index...], "Hello, world! Welcome to StringZilla. 👋")
+    }
+
+    // TODO: This fails!
+    // func testFindLastCharacterNotFromSet() {
+    //     let index = testString.findLast(characterNotFrom: "aeiou")!
+    //     XCTAssertEqual(testString.distance(from: testString.startIndex, to: index), 38)
+    //     XCTAssertEqual(testString[index...], "👋")
+    // }
+    
+    func testEditDistance() {
+        let otherString = "Hello, world!"
+        let distance = try? testString.editDistance(from: otherString) // Using try?
+        XCTAssertNotNil(distance)
+        XCTAssertEqual(distance, 29)
+    }
+}

package/wasmer.toml

@@ -1,6 +1,6 @@
 [package]
 name="unum/usearch"
-version="2.8.15"
+version="2.9.0"
 description="Smaller & Faster Single-File Vector Search Engine from Unum"
 license="Apache-2.0"
 readme="README.md"

package/simsimd/javascript/simsimd.js

@@ -1,45 +0,0 @@
-const compiled = require('bindings')('simsimd');
-
-module.exports = {
-
-    /**
-     * @brief Computes the squared Euclidean distance between two vectors.
-     * @param {Float32Array|Int8Array} a - The first vector.
-     * @param {Float32Array|Int8Array} b - The second vector.
-     * @returns {number} The squared Euclidean distance between vectors a and b.
-     */
-    sqeuclidean: compiled.sqeuclidean,
-
-    /**
-     * @brief Computes the cosine similarity between two vectors.
-     * @param {Float32Array|Int8Array} a - The first vector.
-     * @param {Float32Array|Int8Array} b - The second vector.
-     * @returns {number} The cosine similarity between vectors a and b.
-     */
-    cosine: compiled.cosine,
-
-    /**
-     * @brief Computes the inner product of two vectors.
-     * @param {Float32Array} a - The first vector.
-     * @param {Float32Array} b - The second vector.
-     * @returns {number} The inner product of vectors a and b.
-     */
-    inner: compiled.inner,
-
-    /**
-     * @brief Computes the bitwise Hamming distance between two vectors.
-     * @param {Uint8Array} a - The first vector.
-     * @param {Uint8Array} b - The second vector.
-     * @returns {number} The Hamming distance between vectors a and b.
-     */
-    hamming: compiled.hamming,
-
-    /**
-     * @brief Computes the bitwise Jaccard similarity coefficient between two vectors.
-     * @param {Uint8Array} a - The first vector.
-     * @param {Uint8Array} b - The second vector.
-     * @returns {number} The Jaccard similarity coefficient between vectors a and b.
-     */
-    jaccard: compiled.jaccard,
-
-};

package/simsimd/javascript/test/simsimd.test.js

@@ -1,47 +0,0 @@
-import test from 'node:test';
-import bindings from 'bindings';
-import assert from 'node:assert';
-
-const simsimd = bindings('simsimd');
-
-function assertAlmostEqual(actual, expected, tolerance = 1e-6) {
-    const lowerBound = expected - tolerance;
-    const upperBound = expected + tolerance;
-    assert(actual >= lowerBound && actual <= upperBound, `Expected ${actual} to be almost equal to ${expected}`);
-}
-
-test('Distance from itself', () => {
-
-    const f32s = new Float32Array([1.0, 2.0, 3.0]);
-    assertAlmostEqual(simsimd.sqeuclidean(f32s, f32s), 0.0, 0.01);
-    assertAlmostEqual(simsimd.cosine(f32s, f32s), 0.0, 0.01);
-
-    const f32sNormalized = new Float32Array([1.0 / Math.sqrt(14), 2.0 / Math.sqrt(14), 3.0 / Math.sqrt(14)]);
-    assertAlmostEqual(simsimd.inner(f32sNormalized, f32sNormalized), 0.0, 0.01);
-
-    const f32sDistribution = new Float32Array([1.0 / 6, 2.0 / 6, 3.0 / 6]);
-    assertAlmostEqual(simsimd.kullbackleibler(f32sDistribution, f32sDistribution), 0.0, 0.01);
-    assertAlmostEqual(simsimd.jensenshannon(f32sDistribution, f32sDistribution), 0.0, 0.01);
-
-    const u8s = new Uint8Array([1, 2, 3]);
-    assertAlmostEqual(simsimd.hamming(u8s, u8s), 0.0, 0.01);
-    assertAlmostEqual(simsimd.jaccard(u8s, u8s), 0.0, 0.01);
-});
-
-const f32Array1 = new Float32Array([1.0, 2.0, 3.0]);
-const f32Array2 = new Float32Array([4.0, 5.0, 6.0]);
-
-test('Squared Euclidean Distance', () => {
-    const result = simsimd.sqeuclidean(f32Array1, f32Array2);
-    assertAlmostEqual(result, 27.0, 0.01);
-});
-
-test('Inner Product', () => {
-    const result = simsimd.inner(f32Array1, f32Array2);
-    assertAlmostEqual(result, -31.0, 0.01);
-});
-
-test('Cosine Similarity', () => {
-    const result = simsimd.cosine(f32Array1, f32Array2);
-    assertAlmostEqual(result, 0.029, 0.01);
-});