Bloom Filter Operations

/**
 * Creates a Bloom filter with expected number of items and default 3% false positive probability
 * @param expectedNumItems expected number of items to be inserted
 * @return new BloomFilter instance
 */
public static BloomFilter create(long expectedNumItems);

/**
 * Creates a Bloom filter with specified false positive probability
 * @param expectedNumItems expected number of items to be inserted
 * @param fpp false positive probability (must be between 0.0 and 1.0)
 * @return new BloomFilter instance
 */
public static BloomFilter create(long expectedNumItems, double fpp);

/**
 * Creates a Bloom filter with specific bit count and optimal hash functions
 * @param expectedNumItems expected number of items to be inserted
 * @param numBits total number of bits in the filter
 * @return new BloomFilter instance
 */
public static BloomFilter create(long expectedNumItems, long numBits);

// Create with default 3% false positive rate
BloomFilter filter1 = BloomFilter.create(10000);

// Create with custom false positive rate
BloomFilter filter2 = BloomFilter.create(10000, 0.01); // 1% false positive rate

// Create with specific bit count
BloomFilter filter3 = BloomFilter.create(10000, 100000); // ~1% false positive rate

/**
 * Adds an item to the Bloom filter, supporting String, byte[], and integral types
 * @param item item to add (String, byte[], Byte, Short, Integer, Long)
 * @return true if the filter's bits changed, false if item might already be present
 */
public abstract boolean put(Object item);

/**
 * Specialized method for adding String items
 * @param item string item to add
 * @return true if the filter's bits changed
 */
public abstract boolean putString(String item);

/**
 * Specialized method for adding long values
 * @param item long value to add
 * @return true if the filter's bits changed
 */
public abstract boolean putLong(long item);

/**
 * Specialized method for adding byte arrays
 * @param item byte array to add
 * @return true if the filter's bits changed
 */
public abstract boolean putBinary(byte[] item);

BloomFilter filter = BloomFilter.create(1000);

// Add different data types
boolean changed1 = filter.put("hello");           // true (first time)
boolean changed2 = filter.put("hello");           // false (might already exist)
boolean changed3 = filter.putLong(12345L);        // true
boolean changed4 = filter.putBinary("data".getBytes()); // true
boolean changed5 = filter.put(42);                // true (Integer)

/**
 * Tests if an item might be contained in the filter
 * @param item item to test (String, byte[], Byte, Short, Integer, Long)
 * @return true if item might be present, false if definitely not present
 */
public abstract boolean mightContain(Object item);

/**
 * Specialized method for testing String items
 * @param item string item to test
 * @return true if item might be present
 */
public abstract boolean mightContainString(String item);

/**
 * Specialized method for testing long values
 * @param item long value to test
 * @return true if item might be present
 */
public abstract boolean mightContainLong(long item);

/**
 * Specialized method for testing byte arrays
 * @param item byte array to test
 * @return true if item might be present
 */
public abstract boolean mightContainBinary(byte[] item);

BloomFilter filter = BloomFilter.create(1000);
filter.put("example");
filter.putLong(42L);

// Test membership
boolean test1 = filter.mightContain("example");    // true (was added)
boolean test2 = filter.mightContain("missing");    // false (definitely not added)
boolean test3 = filter.mightContainLong(42L);      // true (was added)
boolean test4 = filter.mightContainLong(999L);     // false or true (false positive possible)

/**
 * Returns the expected false positive probability based on current state
 * @return expected false positive probability
 */
public abstract double expectedFpp();

/**
 * Returns the total number of bits in the underlying bit array
 * @return bit size of the filter
 */
public abstract long bitSize();

/**
 * Returns the number of set bits in the filter
 * @return cardinality (number of 1-bits)
 */
public long cardinality();

BloomFilter filter = BloomFilter.create(1000, 0.01);

double fpp = filter.expectedFpp();        // approximately 0.01
long bits = filter.bitSize();             // total bits allocated
long setBits = filter.cardinality();      // number of bits set to 1

/**
 * Checks if another Bloom filter is compatible for merging
 * @param other the other Bloom filter
 * @return true if filters can be merged
 */
public abstract boolean isCompatible(BloomFilter other);

/**
 * Combines this filter with another using bitwise OR (union operation)
 * @param other the other Bloom filter (must be compatible)
 * @return this filter after merging
 * @throws IncompatibleMergeException if filters are incompatible
 */
public abstract BloomFilter mergeInPlace(BloomFilter other) throws IncompatibleMergeException;

/**
 * Combines this filter with another using bitwise AND (intersection operation)
 * @param other the other Bloom filter (must be compatible)
 * @return this filter after intersection
 * @throws IncompatibleMergeException if filters are incompatible
 */
public abstract BloomFilter intersectInPlace(BloomFilter other) throws IncompatibleMergeException;

BloomFilter filter1 = BloomFilter.create(1000, 0.01);
BloomFilter filter2 = BloomFilter.create(1000, 0.01);

filter1.put("item1");
filter2.put("item2");

// Check compatibility
if (filter1.isCompatible(filter2)) {
    // Merge filters (union - items in either filter)
    filter1.mergeInPlace(filter2);
    
    // Now filter1 contains both "item1" and "item2"
    boolean test1 = filter1.mightContain("item1"); // true
    boolean test2 = filter1.mightContain("item2"); // true
}

/**
 * Computes optimal number of bits for given parameters
 * @param n expected number of insertions
 * @param p desired false positive probability
 * @return optimal bit count
 */
public static long optimalNumOfBits(long n, double p);

/**
 * Computes optimal bits with constraints
 * @param expectedNumItems expected insertions
 * @param maxNumItems maximum possible insertions
 * @param maxNumOfBits maximum allowed bits
 * @return optimal bit count within constraints
 */
public static long optimalNumOfBits(long expectedNumItems, long maxNumItems, long maxNumOfBits);

// Calculate optimal bit count for 10,000 items with 1% false positive rate
long optimalBits = BloomFilter.optimalNumOfBits(10000, 0.01);

// Create filter with calculated parameters
BloomFilter optimized = BloomFilter.create(10000, optimalBits);

public enum BloomFilter.Version {
    /** Version 1 binary format for serialization */
    V1(1);
}