{"id":25089587,"url":"https://github.com/karsjenkoop/bloomfilterc","last_synced_at":"2025-04-01T17:23:05.212Z","repository":{"id":274815314,"uuid":"924162934","full_name":"KarsjenKoop/BloomFilterC","owner":"KarsjenKoop","description":"Simple bloom filter implementation in c with header only macros","archived":false,"fork":false,"pushed_at":"2025-01-29T23:04:52.000Z","size":14,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-07T11:17:49.207Z","etag":null,"topics":["bloom-filter","c","header-only"],"latest_commit_sha":null,"homepage":"","language":"C","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/KarsjenKoop.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}},"created_at":"2025-01-29T14:27:21.000Z","updated_at":"2025-01-29T23:04:55.000Z","dependencies_parsed_at":"2025-01-29T15:40:57.456Z","dependency_job_id":null,"html_url":"https://github.com/KarsjenKoop/BloomFilterC","commit_stats":null,"previous_names":["karsjenkoop/bloomfilterc"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarsjenKoop%2FBloomFilterC","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarsjenKoop%2FBloomFilterC/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarsjenKoop%2FBloomFilterC/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KarsjenKoop%2FBloomFilterC/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KarsjenKoop","download_url":"https://codeload.github.com/KarsjenKoop/BloomFilterC/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246679068,"owners_count":20816402,"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","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","c","header-only"],"created_at":"2025-02-07T11:17:57.065Z","updated_at":"2025-04-01T17:23:05.184Z","avatar_url":"https://github.com/KarsjenKoop.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"This repository provides a single-header C implementation of a Bloom Filter. Bloom Filters are a space-efficient probabilistic data structure used for testing set membership, with the possibility of false positives but no false negatives.\n\n### Features\n\t•\tSingle Header-Only: Just include bloom_filter.h in your project; no external library dependencies.\n\t•\tMultiple Hash Functions: Uses two base hash functions (FNV-1a and DJB2) and mixes them to generate multiple hashes.\n\t•\tMacro-Based API: Macros for:\n\t•\tCreating and destroying Bloom Filter instances\n\t•\tAdding items and checking membership\n\t•\tClearing, loading, and exporting filter state\n\n### Quick Start:\n\t  1.\tClone or download this repository.\n\t  2.\tCopy the bloom_filter.h file into your project’s include path.\n\t  3.\tInclude it in your C/C++ code:\n\t  4.\tUse the provided macros to create a bloom filter, add items, and check membership.\n\n```c\n#include \"bloom_filter.h\"\n```\n\n### Example Usage\n\nBelow is a minimal C example demonstrating how to use the macros:\n```c\n#include \u003cstdio.h\u003e\n#include \u003cstring.h\u003e\n#include \"bloom_filter.h\"\n\nint main(void) {\n    // 1. Create a Bloom Filter pointer with 1024 bits and 5 hash functions.\n    bloom_filter_t *bf;\n    BLOOM_FILTER_CREATE_PTR(bf, 1024, 5);\n    if (bf == NULL) {\n        fprintf(stderr, \"Failed to create bloom filter.\\n\");\n        return 1;\n    }\n\n    // 2. Add some data to the bloom filter.\n    const char *someData = \"Hello World\";\n    BLOOM_FILTER_ADD(*bf, someData, strlen(someData));\n\n    // 3. Check if the data might be in the bloom filter.\n    bool found = false;\n    BLOOM_FILTER_CHECK(*bf, someData, strlen(someData), found);\n    if (found) {\n        printf(\"Data is possibly in the bloom filter.\\n\");\n    } else {\n        printf(\"Data is definitely NOT in the bloom filter.\\n\");\n    }\n\n    // 4. Destroy the bloom filter and free memory.\n    BLOOM_FILTER_DESTROY_PTR(bf);\n    return 0;\n}\n```\n### Macros and Their Usage\n\n#### Creation \u0026 Destruction\n\tBLOOM_FILTER_CREATE_PTR(var_name, bits, hcount)\nCreates a new bloom_filter_t* called var_name with:\n\t•\tbits: total number of bits (must be a multiple of 8).\n\t•\thcount: number of hash functions to apply.\n\n```c\nbloom_filter_t *my_bf;\nBLOOM_FILTER_CREATE_PTR(my_bf, 1024, 5);\nif (my_bf == NULL) {\n    // handle error\n}\n\n```\n\n\n•\tBLOOM_FILTER_DESTROY_PTR(var_name)\nFrees the memory allocated by BLOOM_FILTER_CREATE_PTR.\n```c\nBLOOM_FILTER_DESTROY_PTR(my_bf);\n```\n\n\n### Add \u0026 Check\n•\tBLOOM_FILTER_ADD(bf, data_ptr, data_len)\nAdds an item (arbitrary bytes) to the filter.\n\t•\tbf is a bloom_filter_t struct (not a pointer).\n\t•\tdata_ptr points to the data to add.\n\t•\tdata_len is the size of the data in bytes.\n\n```c\nconst char *my_key = \"ABC\";\nBLOOM_FILTER_ADD(*my_bf, my_key, strlen(my_key));\n```\n\n•\tBLOOM_FILTER_CHECK(bf, data_ptr, data_len, out_bool)\nChecks if an item might be in the set.\n\t•\tbf is a bloom_filter_t struct (not a pointer).\n\t•\tout_bool is a boolean variable that will be set:\n\t•\ttrue =\u003e possibly in the set\n\t•\tfalse =\u003e definitely not in the set\n\n```c\nbool result;\nBLOOM_FILTER_CHECK(*my_bf, my_key, strlen(my_key), result);\nif (result) {\n    // possibly in set\n} else {\n    // definitely not in set\n}\n```\n\n\n### Clearing\n•\tBLOOM_FILTER_CLEAR(bf)\nSets all bits in the Bloom Filter to 0.\n```c\nBLOOM_FILTER_CLEAR(*my_bf);\n```\n\n\n### Load \u0026 Export\n\t•\tBLOOM_FILTER_LOAD(bf, src_bits, len)\nCopies the raw bit array from src_bits (byte buffer) into the filter.\nAllows you to load a previously saved Bloom Filter state.\n```c\n// Suppose you have some external storage or network buffer 'existing_bits'\nBLOOM_FILTER_LOAD(*my_bf, existing_bits, my_bf-\u003ebyte_size);\n```\n\n•\tBLOOM_FILTER_EXPORT(bf, dest_bits, len)\nCopies the Bloom Filter’s bit array into dest_bits.\nUseful for saving the current filter state or transmitting it over a network.\n```c\n// Suppose 'buffer' is a byte array with at least bf-\u003ebyte_size capacity\nBLOOM_FILTER_EXPORT(*my_bf, buffer, bf-\u003ebyte_size);\n```\n\n\n### How It Works\n\t1.\tHashing: Two base hash functions (FNV-1a and DJB2) are computed on the input data.\n\t2.\tHash Mixing: These are then “mixed” to generate a pseudo-unique series of hashes (up to hash_count times).\n\t3.\tBit Setting/Checking: Each hash mod the filter size corresponds to a specific bit index. For an “add,” that bit is set; for a “check,” that bit is tested.\n\nBloom Filters typically have a tunable false-positive rate determined by the filter size and the number of hash functions.\n\n### Notes and Considerations\n* False Positives: Bloom filters may yield false positives (reporting membership when the item is not actually present). However, there are no false negatives.\n* Memory Alignment: Ensure your bits parameter is a multiple of 8. Otherwise, the macro returns NULL.\n* Thread-Safety: This implementation is not inherently thread-safe. Synchronize access if multiple threads share a filter.\n* Non-Cryptographic Hashes: FNV-1a and DJB2 are fast, but not cryptographically secure.\n\n## Contributing\n\nContributions, bug reports, and feature requests are welcome. Please:\n1. Fork the repo\n2.\tCreate a branch for your changes\n3.\tSubmit a Pull Request describing your changes\n\nLicense\n\nThis header-only Bloom Filter is provided under the MIT License. You’re free to use it in both open-source and commercial projects, subject to the terms of that license.\n\nHappy filtering! If you have any questions or suggestions, feel free to open an issue.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarsjenkoop%2Fbloomfilterc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarsjenkoop%2Fbloomfilterc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarsjenkoop%2Fbloomfilterc/lists"}