example.zig

const std = @import("std");
const hasher = std.hash.Fnv1a_64;
const cuckoo = @import("./cuckoofilter.zig");

fn fingerprint8(x: []const u8) u8 {
    return x[0];
}

fn fingerprint16(x: []const u8) u16 {
    return @ptrCast(*u16, x[0..1].ptr).*;
}

fn print(x: var) void {
   std.debug.warn("{}\n", x); 
}

pub fn main() void {
    const element = "banana";
    const hash = hasher.hash(element);
    const fp8 = fingerprint8(element);

    // Assume we want to keep track of max 1 Million items.
    const universe_size = 1000000;

    // Let's use Filter8, a filter with 1 byte long  
    // fingerprints and a 3% max error rate.
    const memsize = comptime cuckoo.Filter8.size_for(universe_size);

    // Note: memory must be zeroed before giving it to the filter.
    var memory = []u8{0} ** memsize;

    // The value of memsize has to be a power of two and it 
    // is *strongly* recommended to keep the fill rate of a 
    // filter under 80%. size_for() will pad the number for 
    // you automatically. size_for_exactly() rounds up to the
    // closest padding of two without applying any padding 
    // beforehand.

    // Use capacity() to know how many items a slice of memory  
    // can store for the given filter Type
    print(cuckoo.Filter8.capacity(memsize)); // => 2097152 

    // Instantiating a filter
    var cf8 = cuckoo.Filter8.init(memory[0..]);

    // Error % information:
    print(cuckoo.Filter8.max_error());    // => 3.125e-02 (~0.003, i.e. 3%)

    // Filter usage
    print(cf8.maybe_contains(hash, fp8)); // => false
    cf8.add(hash, fp8) catch unreachable;
    print(cf8.maybe_contains(hash, fp8)); // => true
    print(cf8.maybe_contains(
        hasher.hash("apple"), 
        fingerprint8("apple"),
    )); // => false
    cf8.remove(hash, fp8) catch unreachable;
    print(cf8.maybe_contains(hash, fp8)); // => false

    // The library offers:
    //    Filter8  (3%)
    //    Filter16 (0.1%)
    //    Filter32 (0.001%)
    // Choose one depending on your error % needs.
}