Update BloomFilter (#261)

Author: Kyle-Ye

Sources/OpenSwiftUICore/Data/Other/BloomFilter.swift

@@ -1,61 +1,100 @@
 //
 //  BloomFilter.swift
-//  OpenSwiftUI
+//  OpenSwiftUICore
 //
 //  Audited for iOS 18.0
-//  Status: WIP
+//  Status: Complete
 
+/// A probabilistic data structure used to test whether an element is a member of a set.
+///
+/// A Bloom filter is a space-efficient probabilistic data structure that is used to test
+/// whether an element is a member of a set. False positives are possible, but false negatives
+/// are not. Elements can be added to the set, but not removed.
+///
+/// This implementation uses a simple bit array represented as a UInt and a hash function
+/// to set 3 different bits for each added element.
 package struct BloomFilter: Equatable {
+    /// The internal bit representation of the Bloom filter.
     package var value: UInt
 
+    /// Creates an empty Bloom filter.
     @inlinable
     package init() {
         value = 0
     }
 
+    /// Creates a Bloom filter containing a single hashable value.
+    ///
+    /// - Parameter value: The hashable value to add to the filter.
     @inlinable
     package init<T>(value: T) where T : Hashable {
         self.init(hashValue: value.hashValue)
     }
 
+    /// Creates a Bloom filter containing a specific type.
+    ///
+    /// - Parameter type: The type to add to the filter.
     @inlinable
     package init(type: any Any.Type) {
         let pointer = unsafeBitCast(type, to: OpaquePointer.self)
         self.init(hashValue: Int(bitPattern: pointer))
     }
 
+    /// Adds the elements of another Bloom filter to this filter.
+    ///
+    /// - Parameter other: Another Bloom filter to combine with this one.
     @inlinable
     package mutating func formUnion(_ other: BloomFilter) {
         value |= other.value
     }
 
+    /// Returns a new Bloom filter containing the elements of both this filter and another.
+    ///
+    /// - Parameter other: Another Bloom filter to combine with this one.
+    /// - Returns: A new Bloom filter containing the elements of both filters.
     @inlinable
     package func union(_ other: BloomFilter) -> BloomFilter {
-        var filter = BloomFilter()
-        filter.value = value | other.value
-        return filter
+        var value = self
+        value.formUnion(other)
+        return value
     }
 
+    /// Tests whether another Bloom filter might be contained in this one.
+    ///
+    /// Due to the probabilistic nature of Bloom filters, this method may return true
+    /// even when the other filter is not actually a subset (false positive). However,
+    /// if it returns false, then the other filter definitely contains elements not in this one.
+    ///
+    /// - Parameter other: Another Bloom filter to test against this one.
+    /// - Returns: `true` if the other filter might be contained in this one, `false` if it definitely is not.
     @inlinable
     package func mayContain(_ other: BloomFilter) -> Bool {
         (other.value & ~value) == 0
     }
 
+    /// Indicates whether the Bloom filter is empty (contains no elements).
+    ///
+    /// - Returns: `true` if the filter is empty, `false` otherwise.
     @inlinable
     package var isEmpty: Bool {
         value == 0
     }
 
+    /// Creates a Bloom filter using a hash value.
+    ///
+    /// This initializer sets 3 different bits in the filter based on different parts of the hash value.
+    ///
+    /// - Parameter hashValue: The hash value to use for bit selection.
     @inlinable
     init(hashValue: Int) {
         // Make sure we do LSR instead of ASR
         let value = UInt(bitPattern: hashValue)
-        let a0 = 1 &<< (value &>> 0x10)
-        let a1 = 1 &<< (value &>> 0xa)
-        let a2 = 1 &<< (value &>> 0x4)
-        self.value = a0 | a1 | a2
+        let bit0 = 1 &<< (value &>> 0x10)
+        let bit1 = 1 &<< (value &>> 0xa)
+        let bit2 = 1 &<< (value &>> 0x4)
+        self.value = bit0 | bit1 | bit2
     }
-    
+
     // FIXME:
     @inline(__always)
     package func match(_ filter: BloomFilter) -> Bool {

Tests/OpenSwiftUICoreTests/Data/Other/BloomFilterTests.swift

@@ -9,7 +9,7 @@ import Testing
 struct BloomFilterTests {
     #if os(macOS)
     @Test("Bloom Filter's init", .enabled(if: ProcessInfo.processInfo.operatingSystemVersionString == "14.0"))
-    func testInitType() throws {
+    func initType() throws {
         // hashValue: 0x1dd382138
         // 1 &<< (value &>> 0x10): 1 &<< 0x38 -> 0x0100_0000_0000_0000
         // 1 &<< (value &>> 0x0a): 1 &<< 0x08 -> 0x0000_0000_0000_0100
@@ -29,20 +29,66 @@ struct BloomFilterTests {
         #expect(BloomFilter(type: type).value == expectedValue)
     }
 
+    #if arch(x86_64) || arch(arm64)
     @Test
-    func testInitHashValue() throws {
+    func initHashValue() throws {
         // hashValue: 0
         // 1 &<< (value &>> 0x10): 1 &<< 0 -> 0x0000_0000_0000_0001
         // 1 &<< (value &>> 0x0a): 1 &<< 0 -> 0x0000_0000_0000_0001
         // 1 &<< (value &>> 0x04): 1 &<< 0 -> 0x0000_0000_0000_0001
         #expect(BloomFilter(hashValue: 0).value == 0x0000_0000_0000_0001)
 
-        #if arch(x86_64) || arch(arm64)
         // hashValue: 0x00000001dfa19ae0
         // 1 &<< (value &>> 0x10): 1 &<< 0x21 -> 0x0000_0002_0000_0000
         // 1 &<< (value &>> 0x0a): 1 &<< 0x26 -> 0x0000_0040_0000_0000
         // 1 &<< (value &>> 0x04): 1 &<< 0x2e -> 0x0000_4000_0000_0000
         #expect(BloomFilter(hashValue: 0x0000_0001_DFA1_9AE0).value == 0x0000_4042_0000_0000)
-        #endif
     }
+    
+    @Test
+    func union() throws {
+        // Test union of two filters
+        let filter1 = BloomFilter(hashValue: 0)  // 0x0000_0000_0000_0001
+        let filter2 = BloomFilter(hashValue: 0x0000_0001_DFA1_9AE0)  // 0x0000_4042_0000_0000
+        
+        // Test union operation
+        let unionResult = filter1.union(filter2)
+        #expect(unionResult.value == 0x0000_4042_0000_0001)
+        
+        // Test formUnion operation
+        var mutableFilter = filter1
+        mutableFilter.formUnion(filter2)
+        #expect(mutableFilter.value == 0x0000_4042_0000_0001)
+        
+        // Test union with empty filter
+        let emptyFilter = BloomFilter()
+        #expect(filter1.union(emptyFilter).value == filter1.value)
+        #expect(emptyFilter.union(filter1).value == filter1.value)
+    }
+    
+    @Test
+    func mayContain() throws {
+        // Create filters with known bits
+        let filter1 = BloomFilter(hashValue: 0)  // 0x0000_0000_0000_0001
+        let filter2 = BloomFilter(hashValue: 0x0000_0001_DFA1_9AE0)  // 0x0000_4042_0000_0000
+        let unionFilter = filter1.union(filter2)  // 0x0000_4042_0000_0001
+        let emptyFilter = BloomFilter()  // 0x0000_0000_0000_0000
+        
+        // Test mayContain functionality
+        #expect(unionFilter.mayContain(filter1), "Union may contain filter1")
+        #expect(unionFilter.mayContain(filter2), "Union may contain filter2")
+        #expect(!filter1.mayContain(filter2), "filter1 does not contain filter2")
+        #expect(!filter2.mayContain(filter1), "filter2 does not contain filter1")
+        
+        // Empty filter cases
+        #expect(filter1.mayContain(emptyFilter), "Any non-empty filter should contain empty filter")
+        #expect(filter2.mayContain(emptyFilter), "Any non-empty filter should contain empty filter")
+        #expect(!emptyFilter.mayContain(filter1), "Empty filter does not contain any non-empty filter")
+        
+        // Self-containment
+        #expect(filter1.mayContain(filter1), "Filter should contain itself")
+        #expect(filter2.mayContain(filter2), "Filter should contain itself")
+        #expect(emptyFilter.mayContain(emptyFilter), "Empty filter should contain itself")
+    }
+    #endif
 }