{"id":30210300,"url":"https://github.com/caiocdcs/probz","last_synced_at":"2025-08-13T20:02:55.457Z","repository":{"id":307871389,"uuid":"1028551381","full_name":"caiocdcs/probz","owner":"caiocdcs","description":"A Zig library for probabilistic data structures, like Bloom Filter, HyperLogLog, etc.","archived":false,"fork":false,"pushed_at":"2025-08-12T08:50:05.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-12T09:29:56.414Z","etag":null,"topics":["bloom-filter","probabilistic-data-structures","zig","zig-package","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caiocdcs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-29T17:40:54.000Z","updated_at":"2025-08-12T08:50:08.000Z","dependencies_parsed_at":"2025-08-02T19:36:11.816Z","dependency_job_id":"71111cb2-7e57-48af-9ffa-d42fb7b51caa","html_url":"https://github.com/caiocdcs/probz","commit_stats":null,"previous_names":["caiocdcs/probz"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/caiocdcs/probz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fprobz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fprobz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fprobz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fprobz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caiocdcs","download_url":"https://codeload.github.com/caiocdcs/probz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caiocdcs%2Fprobz/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270304939,"owners_count":24562085,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-13T02:00:09.904Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bloom-filter","probabilistic-data-structures","zig","zig-package","ziglang"],"created_at":"2025-08-13T20:01:27.165Z","updated_at":"2025-08-13T20:02:55.435Z","avatar_url":"https://github.com/caiocdcs.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Probz\n\nZig library for probabilistic data structures.\n\nData Structures\n\n- [x] Bloom Filter\n- [x] Scalable Bloom Filter\n- [x] Counting Bloom Filter\n- [x] Quotient filter\n- [x] Cuckoo Filter\n- [ ] HyperLogLog\n- [ ] q-digest\n- [ ] t-digest\n- [ ] Top-K\n- [ ] Count-min sketch\n- [ ] Locality–Sensitive Hashing\n\n## Adding to a project\nRun the following command to add the package to your project.\n\n```sh\nzig fetch --save git+https://github.com/caiocdcs/probz#main\n```\n\nThen add it as an import in your `build.zig` file.\n\n```zig\nconst probz = b.dependency(\"probz\", .{\n    .target = target,\n    .optimize = optimize,\n});\n\nexe.root_module.addImport(\"probz\", probz.module(\"probz\"));\n```\n\n## How to use it\n\n### Bloom filter\n\n```zig\nconst std = @import(\"std\");\nconst BloomFilter = @import(\"probz\").BloomFilter;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Create a bloom filter expecting 1000 items with 1% false positive rate\n    var bloom = try BloomFilter.init(allocator, 1000, 0.01);\n    defer bloom.deinit();\n\n    // Add some items to the filter\n    try bloom.set(\"apple\");\n    try bloom.set(\"banana\");\n\n    _ = try bloom.has(\"apple\"); // true\n    _ = try bloom.has(\"banana\"); // true\n    _ = try bloom.has(\"grape\"); // false\n\n    const estimated_size = bloom.estimatedSize();\n    std.debug.print(\"Estimated items in filter: {}\\n\", .{estimated_size});\n}\n```\n\n### Counting Bloom Filter\n\n```zig\nconst std = @import(\"std\");\nconst CountingBloomFilter = @import(\"probz\").CountingBloomFilter;\n\n// Default counting bloom filter with u4 counters, up to 16 items\nconst DefaultCountingBloomFilter = @import(\"probz\").DefaultCountingBloomFilter;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Create with custom counter size (u8 allows up to 255 occurrences)\n    var cbf = try CountingBloomFilter(u8).init(allocator, 100, 0.01);\n    defer cbf.deinit();\n\n    try cbf.add(\"apple\");\n    try cbf.add(\"apple\");\n    try cbf.add(\"banana\");\n\n    _ = cbf.has(\"apple\"); // true\n    _ = cbf.has(\"banana\"); // true\n    _ = cbf.has(\"grape\"); // false\n\n    // Fast removal - caller ensures item exists\n    cbf.remove(\"apple\");\n    const still_has_apple = cbf.has(\"apple\"); // true\n\n    cbf.remove(\"apple\");\n    const no_apple = cbf.has(\"apple\"); // false\n\n    try cbf.removeSafe(\"banana\");\n    try cbf.removeSafe(\"banana\");\n}\n```\n\n**Important**: `remove()` is fast but requires the caller to ensure the item exists via `has()`. For automatic safety checking, use `removeSafe()` instead.\n\n### Scalable Bloom Filter\n\n```zig\nconst std = @import(\"std\");\nconst ScalableBloomFilter = @import(\"probz\").ScalableBloomFilter;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Create with initial capacity 100, target 1% false positive rate\n    var sbf = try ScalableBloomFilter.initDefault(allocator, 100, 0.01);\n    defer sbf.deinit();\n\n    // Add many items - filter automatically scales\n    for (0..1000) |i| {\n        var buf: [32]u8 = undefined;\n        const item = try std.fmt.bufPrint(\u0026buf, \"item{}\", .{i});\n        try sbf.add(item);\n    }\n\n    _ = try sbf.has(\"item500\"); // true\n    _ = try sbf.has(\"item9999\"); // false\n\n    std.debug.print(\"Filters used: {}\\n\", .{sbf.filterCount()});\n    std.debug.print(\"Items added: {}\\n\", .{sbf.estimatedSize()});\n}\n```\n\n### Quotient Filter\n\n```zig\nconst std = @import(\"std\");\nconst QuotientFilter = @import(\"probz\").QuotientFilter;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Create a quotient filter with 8 quotient bits (256 slots) and 8 remainder bits\n    var qf = try QuotientFilter.init(allocator, 8, 8);\n    defer qf.deinit();\n\n    // Add some items to the filter\n    try qf.set(\"apple\");\n    try qf.set(\"banana\");\n    try qf.set(\"cherry\");\n\n    _ = try qf.has(\"apple\");  // true\n    _ = try qf.has(\"banana\"); // true\n    _ = try qf.has(\"grape\");  // false (or possibly true - false positive)\n\n    _ = try qf.delete(\"banana\"); // true\n\n    std.debug.print(\"Filter has {} slots\\n\", .{qf.length});\n}\n```\n\n### Cuckoo Filter\n\n```zig\nconst std = @import(\"std\");\nconst CuckooFilter = @import(\"probz\").CuckooFilter;\n\n// Default cuckoo filter with 16-bit fingerprints and 4 slots per bucket\nconst DefaultCuckooFilter = @import(\"probz\").DefaultCuckooFilter;\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Create a cuckoo filter with capacity for ~1000 items\n    var cf = try DefaultCuckooFilter.init(allocator, 1000);\n    defer cf.deinit();\n\n    // Add some items to the filter\n    try cf.set(\"apple\");\n    try cf.set(\"banana\");\n    try cf.set(\"cherry\");\n\n    _ = cf.has(\"apple\");  // true\n    _ = cf.has(\"banana\"); // true\n    _ = cf.has(\"grape\");  // false (or possibly true - false positive)\n\n    // Cuckoo filters support deletion without false negatives\n    _ = cf.remove(\"banana\"); // true - item was removed\n    _ = cf.has(\"banana\");    // false\n\n    const item_count = cf.estimatedSize();\n    std.debug.print(\"Items in filter: {}\\n\", .{item_count});\n}\n```\n\n\n## Contributing\n\nFeel free to open an issue or make a PR.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiocdcs%2Fprobz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaiocdcs%2Fprobz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaiocdcs%2Fprobz/lists"}