saving.

Author: lemire

README.md

@@ -27,6 +27,62 @@ The following additional types are implemented, but less tested:
 
 ## Usage
 
+
+To use the XOR and Binary Fuse filters, first prepare an array of keys, then construct the filter:
+
+```java
+import org.fastfilter.xor.Xor8;
+import org.fastfilter.xor.Xor16;
+import org.fastfilter.xor.XorBinaryFuse8;
+import org.fastfilter.xor.XorBinaryFuse16;
+
+// Example keys
+long[] keys = {1, 2, 3, 4, 5};
+
+// Construct XOR filters
+Xor8 xor8 = Xor8.construct(keys);
+Xor16 xor16 = Xor16.construct(keys);
+XorBinaryFuse8 xorBinaryFuse8 = XorBinaryFuse8.construct(keys);
+XorBinaryFuse16 xorBinaryFuse16 = XorBinaryFuse16.construct(keys);
+
+// Check membership
+boolean mightContain = xor8.mayContain(1L); // true
+boolean mightContain2 = xor8.mayContain(6L); // false (with high probability)
+```
+
+All filters implement the `Filter` interface and support the `mayContain(long key)` method to check if a key might be in the set. Note that false positives are possible, but false negatives are not.
+
+
+### Serialization and Deserialization
+
+Filters can be serialized to and deserialized from a `ByteBuffer` for persistence or transmission:
+
+```java
+import java.nio.ByteBuffer;
+
+// Assuming you have a constructed filter, e.g., Xor8 xor8 = Xor8.construct(keys);
+
+// Get the serialized size
+int size = xor8.getSerializedSize();
+
+// Allocate a ByteBuffer
+ByteBuffer buffer = ByteBuffer.allocate(size);
+
+// Serialize the filter
+xor8.serialize(buffer);
+
+// Prepare buffer for reading (flip)
+buffer.flip();
+
+// Deserialize the filter
+Xor8 deserializedXor8 = Xor8.deserialize(buffer);
+
+// The deserialized filter behaves identically to the original
+boolean result = deserializedXor8.mayContain(1L); // true
+```
+
+This allows saving filters to files, databases, or sending them over networks.
+
 ### Maven
 
 When using Maven: The latest version, 1.0.4, is not yet available on Maven central, see [issue #48](https://github.com/FastFilter/fastfilter_java/issues/48). However, it is available at https://jitpack.io/:

fastfilter/src/test/java/org/fastfilter/xor/StringFilters.java

@@ -0,0 +1,131 @@
+package org.fastfilter.xor;
+
+import static org.junit.Assert.assertTrue;
+
+import java.util.HashSet;
+import java.util.Random;
+import java.util.Set;
+
+import org.fastfilter.Filter;
+import org.junit.Test;
+
+public class StringFilters {
+
+    private static final int NUM_STRINGS = 100_000;
+    private static final int NUM_TEST_STRINGS = 1_000;
+    private static final Random random = new Random(42);
+
+    private static final long[] keys = generateKeys();
+    private static final long[] testKeys = generateTestKeys();
+
+    private static long[] generateKeys() {
+        String[] strings = new String[NUM_STRINGS];
+        for (int i = 0; i < NUM_STRINGS; i++) {
+            strings[i] = generateRandomString();
+        }
+        long[] k = new long[NUM_STRINGS];
+        for (int i = 0; i < NUM_STRINGS; i++) {
+            k[i] = hashString(strings[i]);
+        }
+        checkUniqueness(k, "keys");
+        return k;
+    }
+
+    private static long[] generateTestKeys() {
+        String[] strings = new String[NUM_TEST_STRINGS];
+        for (int i = 0; i < NUM_TEST_STRINGS; i++) {
+            strings[i] = generateRandomString();
+        }
+        long[] k = new long[NUM_TEST_STRINGS];
+        for (int i = 0; i < NUM_TEST_STRINGS; i++) {
+            k[i] = hashString(strings[i]);
+        }
+        checkUniqueness(k, "test keys");
+        return k;
+    }
+
+    private static void checkUniqueness(long[] array, String name) {
+        Set<Long> set = new HashSet<>();
+        int collisions = 0;
+        for (long l : array) {
+            if (!set.add(l)) {
+                collisions++;
+            }
+        }
+        if (collisions > 0) {
+            System.out.println("Warning: " + collisions + " hash collisions in " + name);
+        } else {
+            System.out.println("No hash collisions in " + name);
+        }
+    }
+
+    private static String generateRandomString() {
+        int length = 5 + random.nextInt(16); // 5 to 20 chars
+        StringBuilder sb = new StringBuilder(length);
+        for (int i = 0; i < length; i++) {
+            sb.append((char) ('a' + random.nextInt(26)));
+        }
+        return sb.toString();
+    }
+
+    private static long hashString(String s) {
+        long h = 0;
+        for (char c : s.toCharArray()) {
+            h = h * 31 + c;
+        }
+        return h;
+    }
+
+    @Test
+    public void testXor8() {
+        testFilter(Xor8.class);
+    }
+
+    @Test
+    public void testXor16() {
+        testFilter(Xor16.class);
+    }
+
+    @Test
+    public void testXorBinaryFuse8() {
+        testFilter(XorBinaryFuse8.class);
+    }
+
+    @Test
+    public void testXorBinaryFuse16() {
+        testFilter(XorBinaryFuse16.class);
+    }
+
+    @Test
+    public void testXorBinaryFuse32() {
+        testFilter(XorBinaryFuse32.class);
+    }
+
+    private void testFilter(Class<?> filterClass) {
+        // Construct filter
+        Filter filter;
+        try {
+            filter = (Filter) filterClass.getMethod("construct", long[].class).invoke(null, (Object) keys);
+        } catch (Exception e) {
+            throw new RuntimeException(e);
+        }
+
+        // Check all keys are in the filter
+        for (int i = 0; i < NUM_STRINGS; i++) {
+            assertTrue("Key " + i + " should be in filter", filter.mayContain(keys[i]));
+        }
+
+        // Check false positives on test keys
+        int falsePositives = 0;
+        for (int i = 0; i < NUM_TEST_STRINGS; i++) {
+            if (filter.mayContain(testKeys[i])) {
+                falsePositives++;
+            }
+        }
+
+        // Expect low false positive rate (less than 1% for most filters)
+        double fpp = (double) falsePositives / NUM_TEST_STRINGS;
+        System.out.println(filterClass.getSimpleName() + " false positive rate: " + fpp);
+        assertTrue("False positive rate should be low: " + fpp, fpp < 0.01); // Allow up to 1%
+    }
+}