[
{
"path": ".gitignore",
"content": "# Build results\n\n[Dd]ebug/\n[Rr]elease/\nx64/\napp.publish/\n[Bb]in/\n[Oo]bj/\n\n# MSTest test Results\n[Tt]est[Rr]esult*/\n[Bb]uild[Ll]og.*\n\n# Visual Studio\n*.suo\n*.user\n*.sln.docstates\n*.sln.ide/\nproject.lock.json\n\n# ReSharper is a .NET coding add-in\n_ReSharper*/\n*.[Rr]e[Ss]harper\n\n_UpgradeReport_Files/\nBackup*/\nUpgradeLog*.XML\nUpgradeLog*.htm\n\n\n#GhostDoc\n*.GhostDoc.xml\n\n# NuGet Packages Directory\npackages/\n\n# Windows image file caches\nThumbs.db\nehthumbs.db\n\n# Folder config file\nDesktop.ini\n\n# Recycle Bin used on file shares\n$RECYCLE.BIN/\n\n# Mac crap\n.DS_Store\n\n\n####################\n#\n# Current Project\n#\n####################\n\n.vs/\nartifacts/\n*.log\n/test/BenchmarkTest/BenchmarkDotNet.Artifacts\n"
},
{
"path": "BloomFilter.NetCore.sln",
"content": "\nMicrosoft Visual Studio Solution File, Format Version 12.00\n# Visual Studio Version 17\nVisualStudioVersion = 17.0.31903.59\nMinimumVisualStudioVersion = 10.0.40219.1\nProject(\"{2150E333-8FDC-42A3-9474-1A3956D46DE8}\") = \"src\", \"src\", \"{8D22B289-3A76-4399-BDA3-FD1B699B2F13}\"\nEndProject\nProject(\"{2150E333-8FDC-42A3-9474-1A3956D46DE8}\") = \"test\", \"test\", \"{BFDF8E72-A7F7-4894-8782-74BB34438F99}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Demo\", \"test\\Demo\\Demo.csproj\", \"{42A8F6A2-7CE7-493F-B3A7-07A1753F5285}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"BloomFilter\", \"src\\BloomFilter\\BloomFilter.csproj\", \"{E9FB2A60-8EFE-49E9-98FE-D75A076CAD0F}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"BloomFilterTest\", \"test\\BloomFilterTest\\BloomFilterTest.csproj\", \"{24193FBE-88A5-4C26-9996-341DEBE0CA80}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"PerformanceTest\", \"test\\PerformanceTest\\PerformanceTest.csproj\", \"{D46EEAAF-36FD-4297-9381-1845C93D13C4}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"BloomFilter.Redis\", \"src\\BloomFilter.Redis\\BloomFilter.Redis.csproj\", \"{4A858860-7405-43F4-9132-0DF40BADBDAD}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"BloomFilter.Redis.Test\", \"test\\BloomFilter.Redis.Test\\BloomFilter.Redis.Test.csproj\", \"{C02DC47A-7258-4B59-AAB4-DFA208DE9B36}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"BenchmarkTest\", \"test\\BenchmarkTest\\BenchmarkTest.csproj\", \"{CFB47A7F-580A-4F4B-940D-03D99EE70C41}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"BloomFilter.CSRedis\", \"src\\BloomFilter.CSRedis\\BloomFilter.CSRedis.csproj\", \"{903B0A3A-1753-47CA-ADBC-B4379FF8F372}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"BloomFilter.EasyCaching\", \"src\\BloomFilter.EasyCaching\\BloomFilter.EasyCaching.csproj\", \"{C4AFDCB8-077D-463A-9EF9-D2F8723F01F4}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"BloomFilter.FreeRedis\", \"src\\BloomFilter.FreeRedis\\BloomFilter.FreeRedis.csproj\", \"{311303FD-7ABA-4C7D-AA5C-90E265FA04A7}\"\nEndProject\nGlobal\n\tGlobalSection(SolutionConfigurationPlatforms) = preSolution\n\t\tDebug|Any CPU = Debug|Any CPU\n\t\tRelease|Any CPU = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(ProjectConfigurationPlatforms) = postSolution\n\t\t{42A8F6A2-7CE7-493F-B3A7-07A1753F5285}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{42A8F6A2-7CE7-493F-B3A7-07A1753F5285}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{42A8F6A2-7CE7-493F-B3A7-07A1753F5285}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{42A8F6A2-7CE7-493F-B3A7-07A1753F5285}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{E9FB2A60-8EFE-49E9-98FE-D75A076CAD0F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{E9FB2A60-8EFE-49E9-98FE-D75A076CAD0F}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{E9FB2A60-8EFE-49E9-98FE-D75A076CAD0F}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{E9FB2A60-8EFE-49E9-98FE-D75A076CAD0F}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{24193FBE-88A5-4C26-9996-341DEBE0CA80}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{24193FBE-88A5-4C26-9996-341DEBE0CA80}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{24193FBE-88A5-4C26-9996-341DEBE0CA80}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{24193FBE-88A5-4C26-9996-341DEBE0CA80}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{D46EEAAF-36FD-4297-9381-1845C93D13C4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{D46EEAAF-36FD-4297-9381-1845C93D13C4}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{D46EEAAF-36FD-4297-9381-1845C93D13C4}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{D46EEAAF-36FD-4297-9381-1845C93D13C4}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{4A858860-7405-43F4-9132-0DF40BADBDAD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{4A858860-7405-43F4-9132-0DF40BADBDAD}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{4A858860-7405-43F4-9132-0DF40BADBDAD}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{4A858860-7405-43F4-9132-0DF40BADBDAD}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{C02DC47A-7258-4B59-AAB4-DFA208DE9B36}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{C02DC47A-7258-4B59-AAB4-DFA208DE9B36}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{C02DC47A-7258-4B59-AAB4-DFA208DE9B36}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{C02DC47A-7258-4B59-AAB4-DFA208DE9B36}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{CFB47A7F-580A-4F4B-940D-03D99EE70C41}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{CFB47A7F-580A-4F4B-940D-03D99EE70C41}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{CFB47A7F-580A-4F4B-940D-03D99EE70C41}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{CFB47A7F-580A-4F4B-940D-03D99EE70C41}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{903B0A3A-1753-47CA-ADBC-B4379FF8F372}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{903B0A3A-1753-47CA-ADBC-B4379FF8F372}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{903B0A3A-1753-47CA-ADBC-B4379FF8F372}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{903B0A3A-1753-47CA-ADBC-B4379FF8F372}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{C4AFDCB8-077D-463A-9EF9-D2F8723F01F4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{C4AFDCB8-077D-463A-9EF9-D2F8723F01F4}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{C4AFDCB8-077D-463A-9EF9-D2F8723F01F4}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{C4AFDCB8-077D-463A-9EF9-D2F8723F01F4}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{311303FD-7ABA-4C7D-AA5C-90E265FA04A7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{311303FD-7ABA-4C7D-AA5C-90E265FA04A7}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{311303FD-7ABA-4C7D-AA5C-90E265FA04A7}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{311303FD-7ABA-4C7D-AA5C-90E265FA04A7}.Release|Any CPU.Build.0 = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(SolutionProperties) = preSolution\n\t\tHideSolutionNode = FALSE\n\tEndGlobalSection\n\tGlobalSection(NestedProjects) = preSolution\n\t\t{42A8F6A2-7CE7-493F-B3A7-07A1753F5285} = {BFDF8E72-A7F7-4894-8782-74BB34438F99}\n\t\t{E9FB2A60-8EFE-49E9-98FE-D75A076CAD0F} = {8D22B289-3A76-4399-BDA3-FD1B699B2F13}\n\t\t{24193FBE-88A5-4C26-9996-341DEBE0CA80} = {BFDF8E72-A7F7-4894-8782-74BB34438F99}\n\t\t{D46EEAAF-36FD-4297-9381-1845C93D13C4} = {BFDF8E72-A7F7-4894-8782-74BB34438F99}\n\t\t{4A858860-7405-43F4-9132-0DF40BADBDAD} = {8D22B289-3A76-4399-BDA3-FD1B699B2F13}\n\t\t{C02DC47A-7258-4B59-AAB4-DFA208DE9B36} = {BFDF8E72-A7F7-4894-8782-74BB34438F99}\n\t\t{CFB47A7F-580A-4F4B-940D-03D99EE70C41} = {BFDF8E72-A7F7-4894-8782-74BB34438F99}\n\t\t{903B0A3A-1753-47CA-ADBC-B4379FF8F372} = {8D22B289-3A76-4399-BDA3-FD1B699B2F13}\n\t\t{C4AFDCB8-077D-463A-9EF9-D2F8723F01F4} = {8D22B289-3A76-4399-BDA3-FD1B699B2F13}\n\t\t{311303FD-7ABA-4C7D-AA5C-90E265FA04A7} = {8D22B289-3A76-4399-BDA3-FD1B699B2F13}\n\tEndGlobalSection\n\tGlobalSection(ExtensibilityGlobals) = postSolution\n\t\tSolutionGuid = {12D6ACDC-31C9-4A69-BE24-76E0F73E48A6}\n\tEndGlobalSection\nEndGlobal\n"
},
{
"path": "Directory.Build.props",
"content": "\n\n \n $(Ver)\n $(Ver)\n 2019-2023 v.la\n v.la@live.cn\n A bloom filter implementation\n bloom filter\n\n $(MSBuildThisFileDirectory)/artifacts\n Bloom;Filter;bloom-filter\n latest\n false\n icon.png\n https://github.com/vla/BloomFilter.NetCore\n MIT\n MIT\n\n git://github.com/vla/BloomFilter.NetCore\n git\n master\n true\n\n \n\n \n true\n \n\n \n\n True\n False\n $(MSBuildThisFileDirectory)/sign.snk\n \n\n\n \n \n \n\n"
},
{
"path": "Directory.Packages.props",
"content": "\n \n true\n false\n \n\n \n \n \n \n \n\n \n \n \n \n\n \n \n \n \n\n \n \n \n \n \n\n \n \n \n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n"
},
{
"path": "LICENSE",
"content": "MIT License\n\nCopyright (c) 2018 v.la@live.cn\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
},
{
"path": "README.md",
"content": "# BloomFilter.NetCore\n\n[](https://opensource.org/licenses/MIT)\n[](https://dotnet.microsoft.com/)\n\nA high-performance, feature-complete Bloom filter library for .NET, supporting both in-memory and distributed Redis backends.\n\n[中文文档](README.zh-CN.md)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Key Features](#key-features)\n- [Packages & Status](#packages--status)\n- [Architecture](#architecture)\n- [Core Functionality](#core-functionality)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Usage Examples](#usage-examples)\n - [In-Memory Mode](#in-memory-mode)\n - [Dependency Injection](#dependency-injection)\n - [Redis Distributed Mode](#redis-distributed-mode)\n- [Hash Algorithms](#hash-algorithms)\n- [Performance Benchmarks](#performance-benchmarks)\n- [Advanced Usage](#advanced-usage)\n- [API Reference](#api-reference)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\nBloomFilter.NetCore is an enterprise-grade Bloom filter library designed for the .NET ecosystem. A Bloom filter is a space-efficient probabilistic data structure used to test whether an element is a member of a set. Its core characteristics are:\n\n- **Space Efficient**: Extremely small memory footprint compared to traditional HashSets\n- **O(1) Time Complexity**: Both add and query operations execute in constant time\n- **Probabilistic**: May return false positives but never false negatives\n\nThis project provides two major implementation types:\n\n1. **In-Memory Bloom Filter (FilterMemory)**: BitArray-based in-memory implementation, suitable for single-process scenarios\n2. **Distributed Bloom Filter (FilterRedis series)**: Redis-backed distributed implementation, supports concurrent access from multiple applications\n\n### Primary Use Cases\n\n- **Cache Penetration Protection**: Prevent malicious queries for non-existent data from bypassing cache\n- **Deduplication**: URL deduplication, email deduplication, user ID deduplication, etc.\n- **Recommendation Systems**: Check if a user has seen specific content\n- **Web Crawlers**: Check if URLs have been crawled\n- **Distributed Systems**: Share state checks across multiple service instances\n- **Big Data**: Existence checks for massive datasets\n\n## Key Features\n\n### 🎯 Flexible Configuration\n\n- **Fully Configurable Parameters**: Bit array size (m), number of hash functions (k)\n- **Automatic Parameter Calculation**: Automatically calculate optimal parameters based on tolerable false positive rate (p) and expected element count (n)\n- **20+ Hash Algorithms**: Support for CRC, MD5, SHA, Murmur, LCGs, xxHash, or custom algorithms\n\n### ⚡ High Performance\n\n- **Fast Generation**: Bloom filter generation and operations are extremely fast\n- **Optimized Implementation**: Uses Span, ReadOnlyMemory for zero-copy operations\n- **Unsafe Code Optimization**: Uses unsafe code blocks in performance-critical paths\n- **Rejection Sampling**: Implements rejection sampling and hash chaining, considering avalanche effect for improved hash quality\n\n### 🔒 Concurrency Safe\n\n- **Thread-Safe**: Uses AsyncLock mechanism for safe multi-threaded concurrent access\n- **Async Support**: Comprehensive async/await support with async versions of all operations\n- **Distributed Locking**: Redis implementations support concurrent access across applications\n\n### 🌐 Multiple Backend Support\n\n- **StackExchange.Redis**: Officially recommended Redis client\n- **CSRedisCore**: High-performance Redis client\n- **FreeRedis**: Lightweight Redis client\n- **EasyCaching**: Supports EasyCaching abstraction layer, switchable cache providers\n\n### 📦 Modern .NET Support\n\n- **Multi-Framework Support**: net462, netstandard2.0, net6.0, net7.0, net8.0, net9.0, net10.0\n- **Dependency Injection**: Native support for Microsoft.Extensions.DependencyInjection\n- **Nullable Reference Types**: Enabled for improved code safety\n\n## Packages & Status\n\n| Package | NuGet | Description |\n|---------|-------|-------------|\n|**BloomFilter.NetCore**|[](https://www.nuget.org/packages/BloomFilter.NetCore)| Core package with in-memory Bloom filter |\n|**BloomFilter.Redis.NetCore**|[](https://www.nuget.org/packages/BloomFilter.Redis.NetCore)| StackExchange.Redis implementation |\n|**BloomFilter.CSRedis.NetCore**|[](https://www.nuget.org/packages/BloomFilter.CSRedis.NetCore)| CSRedisCore implementation |\n|**BloomFilter.FreeRedis.NetCore**|[](https://www.nuget.org/packages/BloomFilter.FreeRedis.NetCore)| FreeRedis implementation |\n|**BloomFilter.EasyCaching.NetCore**|[](https://www.nuget.org/packages/BloomFilter.EasyCaching.NetCore)| EasyCaching integration |\n\n## Architecture\n\n### Core Interface Layer\n\n```\nIBloomFilter (Interface)\n ├── Add / AddAsync - Add elements\n ├── Contains / ContainsAsync - Check elements\n ├── All / AllAsync - Batch check\n ├── Clear / ClearAsync - Clear filter\n └── ComputeHash - Compute hash values\n```\n\n### Implementation Hierarchy\n\n```\nFilter (Abstract Base Class)\n ├── FilterMemory (In-Memory)\n │ └── Uses BitArray storage\n │\n └── Redis Series (Distributed)\n ├── FilterRedis (StackExchange.Redis)\n ├── FilterCSRedis (CSRedisCore)\n ├── FilterFreeRedis (FreeRedis)\n └── FilterEasyCachingRedis (EasyCaching)\n```\n\n### Configuration System\n\n```\nBloomFilterOptions\n ├── FilterMemoryOptions - In-memory mode configuration\n ├── FilterRedisOptions - StackExchange.Redis configuration\n ├── FilterCSRedisOptions - CSRedisCore configuration\n ├── FilterFreeRedisOptions - FreeRedis configuration\n └── FilterEasyCachingOptions - EasyCaching configuration\n```\n\n## Core Functionality\n\n### Mathematical Model\n\nBloomFilter.NetCore implements the complete Bloom filter mathematical model:\n\n#### 1. Optimal Bit Array Size (m)\n\nGiven expected element count `n` and false positive rate `p`, calculate optimal bit array size:\n\n```\nm = -(n * ln(p)) / (ln(2)^2)\n```\n\n#### 2. Optimal Number of Hash Functions (k)\n\nGiven element count `n` and bit array size `m`, calculate optimal number of hash functions:\n\n```\nk = (m / n) * ln(2)\n```\n\n#### 3. Actual False Positive Rate (p)\n\nGiven inserted element count, number of hash functions, and bit array size, calculate actual false positive rate:\n\n```\np = (1 - e^(-k*n/m))^k\n```\n\nThese calculations are provided by static methods in the `Filter` base class:\n\n```csharp\n// Calculate optimal bit array size\nlong m = Filter.BestM(expectedElements, errorRate);\n\n// Calculate optimal number of hash functions\nint k = Filter.BestK(expectedElements, capacity);\n\n// Calculate optimal element count\nlong n = Filter.BestN(hashes, capacity);\n\n// Calculate actual false positive rate\ndouble p = Filter.BestP(hashes, capacity, insertedElements);\n```\n\n### Storage Mechanisms\n\n#### In-Memory Storage\n\n- **BitArray**: Uses .NET's BitArray as underlying storage\n- **Bucketing Strategy**: Automatically splits into multiple BitArrays when capacity exceeds 2GB (MaxInt = 2,147,483,640)\n- **Serialization Support**: Supports serialization/deserialization for persistence or transfer\n\n#### Redis Storage\n\n- **SETBIT/GETBIT**: Uses Redis bit operation commands\n- **Distributed Access**: Multiple application instances can concurrently access the same filter\n- **Persistence**: Leverages Redis persistence mechanisms for data safety\n\n### Concurrency Control\n\n```csharp\n// AsyncLock ensures thread safety\npublic class AsyncLock\n{\n private readonly SemaphoreSlim _semaphore = new(1, 1);\n\n public async ValueTask LockAsync()\n {\n await _semaphore.WaitAsync();\n return new Release(_semaphore);\n }\n}\n```\n\n## Installation\n\n### Install via NuGet\n\n**In-Memory Mode (Core Package):**\n\n```bash\ndotnet add package BloomFilter.NetCore\n```\n\n**Redis Distributed Mode (Choose One):**\n\n```bash\n# StackExchange.Redis\ndotnet add package BloomFilter.Redis.NetCore\n\n# CSRedisCore\ndotnet add package BloomFilter.CSRedis.NetCore\n\n# FreeRedis\ndotnet add package BloomFilter.FreeRedis.NetCore\n\n# EasyCaching\ndotnet add package BloomFilter.EasyCaching.NetCore\n```\n\n## Quick Start\n\n### Simplest Example\n\n```csharp\nusing BloomFilter;\n\n// Create a Bloom filter: expect 10 million elements, 1% false positive rate\nvar bf = FilterBuilder.Build(10_000_000, 0.01);\n\n// Add elements\nbf.Add(\"user:123\");\nbf.Add(\"user:456\");\n\n// Check element existence\nConsole.WriteLine(bf.Contains(\"user:123\")); // True\nConsole.WriteLine(bf.Contains(\"user:789\")); // False (very small probability of True)\n\n// Clear filter\nbf.Clear();\n```\n\n### Async Operations\n\n```csharp\n// Async add\nawait bf.AddAsync(Encoding.UTF8.GetBytes(\"user:123\"));\n\n// Async check\nbool exists = await bf.ContainsAsync(Encoding.UTF8.GetBytes(\"user:123\"));\n\n// Batch async operations\nvar users = new[] {\n Encoding.UTF8.GetBytes(\"user:1\"),\n Encoding.UTF8.GetBytes(\"user:2\"),\n Encoding.UTF8.GetBytes(\"user:3\")\n};\n\nawait bf.AddAsync(users);\nvar results = await bf.ContainsAsync(users);\n```\n\n### Fluent API (New in v3.0)\n\nv3.0 introduces a modern fluent API for building Bloom filters with improved discoverability and expressiveness:\n\n```csharp\n// In-Memory Fluent API\nvar filter = FilterBuilder.Create()\n .WithName(\"UserFilter\")\n .ExpectingElements(10_000_000)\n .WithErrorRate(0.001)\n .UsingHashMethod(HashMethod.XXHash3)\n .BuildInMemory();\n\n// Redis Fluent API (StackExchange.Redis)\nvar redisFilter = FilterRedisBuilder.Create()\n .WithRedisConnection(\"localhost:6379\")\n .WithRedisKey(\"bloom:users\")\n .WithName(\"UserFilter\")\n .ExpectingElements(10_000_000)\n .WithErrorRate(0.001)\n .BuildRedis();\n\n// CSRedis Fluent API\nvar csredisFilter = FilterCSRedisBuilder.Create()\n .WithRedisClient(csredisClient)\n .WithRedisKey(\"bloom:users\")\n .ExpectingElements(10_000_000)\n .BuildCSRedis();\n\n// FreeRedis Fluent API\nvar freeRedisFilter = FilterFreeRedisBuilder.Create()\n .WithRedisClient(redisClient)\n .WithRedisKey(\"bloom:users\")\n .ExpectingElements(10_000_000)\n .BuildFreeRedis();\n\n// EasyCaching Fluent API\nvar easyCachingFilter = FilterEasyCachingBuilder.Create()\n .WithRedisCachingProvider(provider)\n .WithRedisKey(\"bloom:users\")\n .ExpectingElements(10_000_000)\n .BuildEasyCaching();\n\n// All common configuration methods:\n// - WithName(string) - Set filter name\n// - ExpectingElements(long) - Set expected element count\n// - WithErrorRate(double) - Set false positive rate (0-1)\n// - UsingHashMethod(HashMethod) - Use predefined hash algorithm\n// - UsingCustomHash(HashFunction) - Use custom hash function\n// - WithSerializer(IFilterMemorySerializer) - Set custom serializer (memory only)\n```\n\n**Why use Fluent API?**\n- 🔍 Better discoverability with IntelliSense\n- 📖 More readable and self-documenting code\n- ⛓️ Chainable method calls\n- 🎯 Type-safe configuration\n- ✅ Backward compatible - old static methods still work!\n\n## Usage Examples\n\n### In-Memory Mode\n\n#### Basic Usage\n\n```csharp\nusing BloomFilter;\n\npublic class UserService\n{\n // Static shared Bloom filter\n private static readonly IBloomFilter _bloomFilter =\n FilterBuilder.Build(10_000_000, 0.01);\n\n public void AddUser(string userId)\n {\n // Add user ID\n _bloomFilter.Add(userId);\n }\n\n public bool MayExistUser(string userId)\n {\n // Check if user may exist\n return _bloomFilter.Contains(userId);\n }\n}\n```\n\n#### Custom Configuration\n\n```csharp\nusing BloomFilter;\n\n// Method 1: Specify hash algorithm\nvar bf1 = FilterBuilder.Build(\n expectedElements: 1_000_000,\n errorRate: 0.001,\n hashMethod: HashMethod.Murmur3\n);\n\n// Method 2: Use custom hash function\nvar hashFunction = new Murmur128BitsX64();\nvar bf2 = FilterBuilder.Build(\n expectedElements: 1_000_000,\n errorRate: 0.001,\n hashFunction: hashFunction\n);\n\n// Method 3: Manually specify parameters (advanced usage)\nvar bf3 = FilterBuilder.Build(\n capacity: 9585059, // Bit array size\n hashes: 10, // Number of hash functions\n hashMethod: HashMethod.XXHash3\n);\n\n// Method 4: Use configuration object\nvar options = new FilterMemoryOptions\n{\n Name = \"MyFilter\",\n ExpectedElements = 5_000_000,\n ErrorRate = 0.01,\n Method = HashMethod.Murmur3\n};\nvar bf4 = FilterBuilder.Build(options);\n```\n\n### Dependency Injection\n\n#### ASP.NET Core Integration\n\n```csharp\nusing BloomFilter;\nusing Microsoft.Extensions.DependencyInjection;\n\npublic class Startup\n{\n public void ConfigureServices(IServiceCollection services)\n {\n // Register Bloom filter service\n services.AddBloomFilter(setupAction =>\n {\n setupAction.UseInMemory(options =>\n {\n options.Name = \"MainFilter\";\n options.ExpectedElements = 10_000_000;\n options.ErrorRate = 0.01;\n options.Method = HashMethod.Murmur3;\n });\n });\n\n services.AddControllers();\n }\n}\n\n// Use in controller or service\npublic class UserController : ControllerBase\n{\n private readonly IBloomFilter _bloomFilter;\n\n public UserController(IBloomFilter bloomFilter)\n {\n _bloomFilter = bloomFilter;\n }\n\n [HttpPost(\"users/{userId}\")]\n public IActionResult CheckUser(string userId)\n {\n if (_bloomFilter.Contains(userId))\n {\n // User may exist, continue to query database\n return Ok(\"User may exist\");\n }\n else\n {\n // User definitely doesn't exist, no need to query database\n return NotFound(\"User doesn't exist\");\n }\n }\n}\n```\n\n#### Multiple Filter Instances\n\n```csharp\nservices.AddBloomFilter(setupAction =>\n{\n // User filter\n setupAction.UseInMemory(options =>\n {\n options.Name = \"UserFilter\";\n options.ExpectedElements = 10_000_000;\n options.ErrorRate = 0.01;\n });\n\n // Email filter\n setupAction.UseInMemory(options =>\n {\n options.Name = \"EmailFilter\";\n options.ExpectedElements = 5_000_000;\n options.ErrorRate = 0.001;\n });\n});\n\n// Use factory to get specific filter\npublic class MyService\n{\n private readonly IBloomFilter _userFilter;\n private readonly IBloomFilter _emailFilter;\n\n public MyService(IBloomFilterFactory factory)\n {\n _userFilter = factory.Get(\"UserFilter\");\n _emailFilter = factory.Get(\"EmailFilter\");\n }\n}\n```\n\n### Redis Distributed Mode\n\n#### StackExchange.Redis\n\n```csharp\nusing BloomFilter;\n\n// Method 1: Direct build\nvar bf = FilterRedisBuilder.Build(\n redisHost: \"localhost:6379\",\n name: \"DistributedFilter\",\n expectedElements: 5_000_000,\n errorRate: 0.001\n);\n\nbf.Add(\"item:123\");\nConsole.WriteLine(bf.Contains(\"item:123\")); // True\n\n// Method 2: Dependency injection\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseRedis(new FilterRedisOptions\n {\n Name = \"UserFilter\",\n RedisKey = \"BloomFilter:Users\",\n Endpoints = new List { \"localhost:6379\" },\n Database = 0,\n ExpectedElements = 10_000_000,\n ErrorRate = 0.01,\n Method = HashMethod.Murmur3\n });\n});\n\n// Method 3: Advanced configuration (master-slave, sentinel, cluster)\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseRedis(new FilterRedisOptions\n {\n Name = \"ProductFilter\",\n RedisKey = \"BloomFilter:Products\",\n Endpoints = new List\n {\n \"redis-master:6379\",\n \"redis-slave1:6379\",\n \"redis-slave2:6379\"\n },\n Password = \"your-redis-password\",\n Ssl = true,\n ConnectTimeout = 5000,\n SyncTimeout = 3000,\n ExpectedElements = 20_000_000,\n ErrorRate = 0.001\n });\n});\n```\n\n#### CSRedisCore\n\n```csharp\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseCSRedis(new FilterCSRedisOptions\n {\n Name = \"OrderFilter\",\n RedisKey = \"BloomFilter:Orders\",\n ConnectionStrings = new List\n {\n \"localhost:6379,password=123456,defaultDatabase=0,poolsize=50,prefix=myapp:\"\n },\n ExpectedElements = 5_000_000,\n ErrorRate = 0.01\n });\n});\n```\n\n#### FreeRedis\n\n```csharp\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseFreeRedis(new FilterFreeRedisOptions\n {\n Name = \"CartFilter\",\n RedisKey = \"BloomFilter:Carts\",\n ConnectionStrings = new List { \"localhost:6379,password=123456\" },\n ExpectedElements = 1_000_000,\n ErrorRate = 0.01\n });\n});\n```\n\n#### EasyCaching Integration\n\nEasyCaching provides a unified caching abstraction layer, allowing you to easily switch underlying cache implementations:\n\n```csharp\nusing EasyCaching.Core.Configurations;\nusing Microsoft.Extensions.DependencyInjection;\n\nvar services = new ServiceCollection();\n\n// 1. Configure EasyCaching\nservices.AddEasyCaching(options =>\n{\n // Configure Redis provider\n options.UseRedis(config =>\n {\n config.DBConfig.Endpoints.Add(new ServerEndPoint(\"127.0.0.1\", 6379));\n config.DBConfig.Database = 0;\n }, \"redis-provider-1\");\n\n // Can configure multiple providers\n options.UseRedis(config =>\n {\n config.DBConfig.Endpoints.Add(new ServerEndPoint(\"127.0.0.1\", 6379));\n config.DBConfig.Database = 1;\n }, \"redis-provider-2\");\n});\n\n// 2. Configure BloomFilter\nservices.AddBloomFilter(setupAction =>\n{\n // Use first Redis provider\n setupAction.UseEasyCachingRedis(new FilterEasyCachingRedisOptions\n {\n Name = \"BF1\",\n RedisKey = \"BloomFilter1\",\n ProviderName = \"redis-provider-1\",\n ExpectedElements = 10_000_000,\n ErrorRate = 0.01\n });\n\n // Use second Redis provider\n setupAction.UseEasyCachingRedis(new FilterEasyCachingRedisOptions\n {\n Name = \"BF2\",\n RedisKey = \"BloomFilter2\",\n ProviderName = \"redis-provider-2\",\n ExpectedElements = 5_000_000,\n ErrorRate = 0.001\n });\n});\n\nvar provider = services.BuildServiceProvider();\n\n// Use default filter\nvar bf = provider.GetService();\nbf.Add(\"value1\");\n\n// Use named filter\nvar factory = provider.GetService();\nvar bf1 = factory.Get(\"BF1\");\nvar bf2 = factory.Get(\"BF2\");\n\nbf1.Add(\"item1\");\nbf2.Add(\"item2\");\n```\n\n### Real-World Application Scenarios\n\n#### 1. Cache Penetration Protection\n\n```csharp\npublic class ProductService\n{\n private readonly IBloomFilter _bloomFilter;\n private readonly ICache _cache;\n private readonly IProductRepository _repository;\n\n public ProductService(\n IBloomFilter bloomFilter,\n ICache cache,\n IProductRepository repository)\n {\n _bloomFilter = bloomFilter;\n _cache = cache;\n _repository = repository;\n }\n\n public async Task GetProductAsync(string productId)\n {\n // First layer: Bloom filter\n if (!_bloomFilter.Contains(productId))\n {\n // Product definitely doesn't exist, return null directly\n return null;\n }\n\n // Second layer: Cache\n var cached = await _cache.GetAsync(productId);\n if (cached != null)\n {\n return cached;\n }\n\n // Third layer: Database\n var product = await _repository.GetByIdAsync(productId);\n if (product != null)\n {\n await _cache.SetAsync(productId, product);\n }\n\n return product;\n }\n\n public async Task CreateProductAsync(Product product)\n {\n // Save to database\n await _repository.SaveAsync(product);\n\n // Add to Bloom filter\n _bloomFilter.Add(product.Id);\n\n // Update cache\n await _cache.SetAsync(product.Id, product);\n }\n}\n```\n\n#### 2. URL Deduplication (Web Crawler)\n\n```csharp\npublic class WebCrawler\n{\n private readonly IBloomFilter _visitedUrls;\n private readonly Queue _urlQueue;\n\n public WebCrawler(IBloomFilter bloomFilter)\n {\n _visitedUrls = bloomFilter;\n _urlQueue = new Queue();\n }\n\n public async Task CrawlAsync(string startUrl)\n {\n _urlQueue.Enqueue(startUrl);\n\n while (_urlQueue.Count > 0)\n {\n var url = _urlQueue.Dequeue();\n\n // Check if already visited\n if (_visitedUrls.Contains(url))\n {\n continue; // Skip already visited URLs\n }\n\n // Mark as visited\n _visitedUrls.Add(url);\n\n // Download page\n var page = await DownloadPageAsync(url);\n\n // Process page\n await ProcessPageAsync(page);\n\n // Extract new URLs\n var newUrls = ExtractUrls(page);\n foreach (var newUrl in newUrls)\n {\n if (!_visitedUrls.Contains(newUrl))\n {\n _urlQueue.Enqueue(newUrl);\n }\n }\n }\n }\n}\n```\n\n#### 3. Distributed Deduplication (Multiple Instances)\n\n```csharp\n// Configure distributed Bloom filter\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseRedis(new FilterRedisOptions\n {\n Name = \"GlobalDeduplication\",\n RedisKey = \"BF:Dedup\",\n Endpoints = new List { \"redis-cluster:6379\" },\n ExpectedElements = 100_000_000,\n ErrorRate = 0.0001\n });\n});\n\n// Use across multiple service instances\npublic class MessageProcessor\n{\n private readonly IBloomFilter _bloomFilter;\n\n public async Task ProcessMessageAsync(Message message)\n {\n // All instances share the same Redis Bloom filter\n if (await _bloomFilter.ContainsAsync(message.Id))\n {\n // Message already processed by another instance\n return;\n }\n\n // Mark as processed\n await _bloomFilter.AddAsync(message.Id);\n\n // Process message\n await HandleMessageAsync(message);\n }\n}\n```\n\n## Hash Algorithms\n\nBloomFilter.NetCore supports 20+ hash algorithms, choose based on performance and accuracy requirements:\n\n### Algorithm Categories\n\n| Category | Algorithms | Characteristics | Use Cases |\n|----------|-----------|-----------------|-----------|\n| **LCG-based** | LCGWithFNV1
LCGWithFNV1a
LCGModifiedFNV1 | Extremely fast, lower quality | Extremely high performance requirements, can tolerate high false positive rates |\n| **RNG-based** | RNGWithFNV1
RNGWithFNV1a
RNGModifiedFNV1 | High quality, slower | Scenarios requiring high accuracy |\n| **Checksum** | CRC32
CRC64
Adler32 | Balanced performance and quality | General scenarios |\n| **Murmur Family** | Murmur3
Murmur32BitsX86
Murmur128BitsX64
Murmur128BitsX86 | **Recommended**, good performance, high quality | Recommended for production |\n| **Cryptographic** | SHA1
SHA256
SHA384
SHA512 | Highest quality, slowest | Scenarios requiring extreme security |\n| **XXHash Family** | XXHash32
XXHash64
XXHash3
XXHash128 | **Fastest**, excellent quality | First choice for high performance |\n\n### Selection Recommendations\n\n```csharp\n// Recommended: Default Murmur3 for production (balanced performance and quality)\nvar bf1 = FilterBuilder.Build(10_000_000, 0.01, HashMethod.Murmur3);\n\n// High Performance: Choose XXHash3 for extreme performance requirements\nvar bf2 = FilterBuilder.Build(10_000_000, 0.01, HashMethod.XXHash3);\n\n// High Precision: Choose SHA256 + lower errorRate for minimal false positive rate\nvar bf3 = FilterBuilder.Build(10_000_000, 0.0001, HashMethod.SHA256);\n\n// Distributed: Recommend XXHash64 for Redis (fast and good cross-language support)\nvar bf4 = FilterRedisBuilder.Build(\n \"localhost:6379\",\n \"MyFilter\",\n 10_000_000,\n 0.01,\n HashMethod.XXHash64\n);\n```\n\n## Performance Benchmarks\n\n### Test Environment\n\n```\nBenchmarkDotNet=v0.13.5\nOS: Windows 11 (10.0.22621.1778/22H2)\nCPU: AMD Ryzen 7 5800X, 1 CPU, 16 logical cores, 8 physical cores\n.NET SDK: 7.0.304\nRuntime: .NET 7.0.7 (7.0.723.27404), X64 RyuJIT AVX2\n```\n\n### Performance Rankings (64-byte data)\n\n| Rank | Algorithm | Mean Time | Relative Speed |\n|------|-----------|-----------|----------------|\n| 🥇 1 | XXHash3 | 33.14 ns | Baseline (Fastest) |\n| 🥈 2 | XXHash128 | 36.01 ns | 1.09x |\n| 🥉 3 | CRC64 | 38.83 ns | 1.17x |\n| 4 | XXHash64 | 50.62 ns | 1.53x |\n| 5 | Murmur3 | 70.98 ns | 2.14x |\n| ... | ... | ... | ... |\n| 28 | SHA512 | 1,368.20 ns | 41.28x (Slowest) |\n\n### Complete Performance Data\n\n\nClick to expand full benchmark results
\n\n#### 64-byte Data\n\n| Algorithm | Mean Time | Error | StdDev | Allocated |\n|-----------|-----------|-------|--------|-----------|\n| XXHash3 | 33.14 ns | 0.295 ns | 0.276 ns | 80 B |\n| XXHash128 | 36.01 ns | 0.673 ns | 0.749 ns | 80 B |\n| CRC64 | 38.83 ns | 0.399 ns | 0.333 ns | 80 B |\n| XXHash64 | 50.62 ns | 0.756 ns | 0.670 ns | 80 B |\n| Murmur3 | 70.98 ns | 1.108 ns | 1.036 ns | 80 B |\n| XXHash32 | 73.15 ns | 0.526 ns | 0.466 ns | 80 B |\n| Murmur128BitsX64 | 80.15 ns | 0.783 ns | 0.653 ns | 120 B |\n| Murmur128BitsX86 | 82.73 ns | 1.211 ns | 1.011 ns | 120 B |\n| LCGWithFNV1 | 91.27 ns | 1.792 ns | 2.134 ns | 80 B |\n| CRC32 | 145.63 ns | 1.528 ns | 1.429 ns | 328 B |\n| Adler32 | 150.07 ns | 0.664 ns | 0.589 ns | 336 B |\n| RNGWithFNV1 | 445.32 ns | 8.463 ns | 9.747 ns | 384 B |\n| SHA256 | 922.30 ns | 4.478 ns | 3.739 ns | 496 B |\n| SHA1 | 1,045.67 ns | 6.411 ns | 5.997 ns | 464 B |\n| SHA384 | 1,173.67 ns | 5.050 ns | 3.942 ns | 456 B |\n| SHA512 | 1,368.20 ns | 10.967 ns | 9.722 ns | 504 B |\n\n#### 1 MB Data\n\n| Algorithm | Mean Time |\n|-----------|-----------|\n| XXHash3 | 30,258.92 ns (~30 μs) |\n| XXHash128 | 33,778.68 ns (~34 μs) |\n| CRC64 | 56,321.74 ns (~56 μs) |\n| XXHash64 | 100,570.79 ns (~101 μs) |\n| Murmur128BitsX64 | 163,915.44 ns (~164 μs) |\n| ... | ... |\n| SHA1 | 3,381,425.73 ns (~3.4 ms) |\n\n \n\n### Performance Recommendations\n\n1. **General Scenarios**: Use `Murmur3` (default), balanced performance and quality\n2. **Extreme Performance**: Use `XXHash3`, 2x faster than Murmur3\n3. **Large Data**: Use `XXHash128` or `Murmur128BitsX64`, 128-bit output reduces collisions\n4. **Avoid**: LCG series (poor quality), SHA series (too slow)\n\n## Advanced Usage\n\n### Serialization and Deserialization\n\n```csharp\n// Export Bloom filter state\nvar bf = FilterBuilder.Build(1_000_000, 0.01);\nbf.Add(\"item1\");\nbf.Add(\"item2\");\n\n// Get internal state (for persistence)\nvar memory = (FilterMemory)bf;\nvar buckets = memory.Buckets; // BitArray[]\nvar bucketBytes = memory.BucketBytes; // byte[][]\n\n// Restore Bloom filter from state\nvar options = new FilterMemoryOptions\n{\n Name = \"RestoredFilter\",\n ExpectedElements = 1_000_000,\n ErrorRate = 0.01,\n Buckets = buckets // Or use BucketBytes\n};\nvar restoredBf = FilterBuilder.Build(options);\n\nConsole.WriteLine(restoredBf.Contains(\"item1\")); // True\n```\n\n### Batch Operations\n\n```csharp\n// Batch add\nvar items = Enumerable.Range(1, 10000)\n .Select(i => Encoding.UTF8.GetBytes($\"user:{i}\"))\n .ToArray();\n\nvar addResults = bf.Add(items);\nConsole.WriteLine($\"Successfully added: {addResults.Count(r => r)} elements\");\n\n// Batch check\nvar checkResults = bf.Contains(items);\nConsole.WriteLine($\"Exist: {checkResults.Count(r => r)} elements\");\n\n// Check if all elements exist\nbool allExist = bf.All(items);\n\n// Async batch operations\nvar asyncAddResults = await bf.AddAsync(items);\nvar asyncCheckResults = await bf.ContainsAsync(items);\nbool asyncAllExist = await bf.AllAsync(items);\n```\n\n### Custom Hash Function\n\n```csharp\nusing BloomFilter.HashAlgorithms;\n\n// Implement custom hash algorithm\npublic class MyCustomHash : HashFunction\n{\n public override long ComputeHash(ReadOnlySpan data)\n {\n // Custom hash logic\n long hash = 0;\n foreach (var b in data)\n {\n hash = hash * 31 + b;\n }\n return hash;\n }\n}\n\n// Use custom hash\nvar customHash = new MyCustomHash();\nvar bf = FilterBuilder.Build(1_000_000, 0.01, customHash);\n```\n\n### Calculate Actual False Positive Rate\n\n```csharp\nvar bf = FilterBuilder.Build(100_000, 0.01);\n\n// Add 50,000 elements\nfor (int i = 0; i < 50_000; i++)\n{\n bf.Add($\"item:{i}\");\n}\n\n// Calculate theoretical false positive rate\nvar filter = (Filter)bf;\ndouble theoreticalErrorRate = Filter.BestP(\n filter.Hashes,\n filter.Capacity,\n 50_000\n);\n\nConsole.WriteLine($\"Theoretical error rate: {theoreticalErrorRate:P4}\");\n\n// Test actual false positive rate\nint falsePositives = 0;\nint testCount = 100_000;\n\nfor (int i = 50_000; i < 50_000 + testCount; i++)\n{\n if (bf.Contains($\"item:{i}\"))\n {\n falsePositives++;\n }\n}\n\ndouble actualErrorRate = (double)falsePositives / testCount;\nConsole.WriteLine($\"Actual error rate: {actualErrorRate:P4}\");\nConsole.WriteLine($\"False positives: {falsePositives} / {testCount}\");\n```\n\n### Monitoring and Statistics\n\n```csharp\npublic class BloomFilterMonitor\n{\n private readonly IBloomFilter _filter;\n private long _addCount;\n private long _hitCount;\n private long _missCount;\n\n public BloomFilterMonitor(IBloomFilter filter)\n {\n _filter = filter;\n }\n\n public bool Add(string item)\n {\n Interlocked.Increment(ref _addCount);\n return _filter.Add(item);\n }\n\n public bool Contains(string item)\n {\n var result = _filter.Contains(item);\n if (result)\n Interlocked.Increment(ref _hitCount);\n else\n Interlocked.Increment(ref _missCount);\n return result;\n }\n\n public void PrintStats()\n {\n Console.WriteLine($\"Total adds: {_addCount}\");\n Console.WriteLine($\"Hits: {_hitCount}\");\n Console.WriteLine($\"Misses: {_missCount}\");\n Console.WriteLine($\"Hit rate: {(double)_hitCount / (_hitCount + _missCount):P2}\");\n }\n}\n```\n\n## API Reference\n\n### IBloomFilter Interface\n\n```csharp\npublic interface IBloomFilter : IDisposable\n{\n // Properties\n string Name { get; }\n\n // Synchronous methods\n bool Add(ReadOnlySpan data);\n IList Add(IEnumerable elements);\n bool Contains(ReadOnlySpan element);\n IList Contains(IEnumerable elements);\n bool All(IEnumerable elements);\n void Clear();\n long[] ComputeHash(ReadOnlySpan data);\n\n // Asynchronous methods\n ValueTask AddAsync(ReadOnlyMemory data);\n ValueTask> AddAsync(IEnumerable elements);\n ValueTask ContainsAsync(ReadOnlyMemory element);\n ValueTask> ContainsAsync(IEnumerable elements);\n ValueTask AllAsync(IEnumerable elements);\n ValueTask ClearAsync();\n}\n```\n\n### Filter Base Class\n\n```csharp\npublic abstract class Filter : IBloomFilter\n{\n // Properties\n public string Name { get; }\n public HashFunction Hash { get; }\n public long Capacity { get; }\n public int Hashes { get; }\n public long ExpectedElements { get; }\n public double ErrorRate { get; }\n\n // Static methods (mathematical calculations)\n public static long BestM(long n, double p);\n public static int BestK(long n, long m);\n public static long BestN(int k, long m);\n public static double BestP(int k, long m, long insertedElements);\n}\n```\n\n### FilterBuilder\n\n```csharp\npublic static class FilterBuilder\n{\n // Using expected elements and error rate\n public static IBloomFilter Build(long expectedElements, double errorRate);\n public static IBloomFilter Build(long expectedElements, double errorRate, HashMethod method);\n public static IBloomFilter Build(long expectedElements, double errorRate, HashFunction hash);\n\n // Using capacity and number of hash functions\n public static IBloomFilter Build(long capacity, int hashes, HashMethod method);\n public static IBloomFilter Build(long capacity, int hashes, HashFunction hash);\n\n // Using configuration object\n public static IBloomFilter Build(FilterMemoryOptions options);\n}\n```\n\n### FilterRedisBuilder\n\n```csharp\npublic static class FilterRedisBuilder\n{\n public static IBloomFilter Build(\n string redisHost,\n string name,\n long expectedElements,\n double errorRate,\n HashMethod method = HashMethod.Murmur3);\n}\n```\n\n### Extension Methods\n\n```csharp\n// Service registration\npublic static class ServiceCollectionExtensions\n{\n public static IServiceCollection AddBloomFilter(\n this IServiceCollection services,\n Action setupAction);\n}\n\n// Configuration extensions\npublic static class BloomFilterOptionsExtensions\n{\n public static BloomFilterOptions UseInMemory(\n this BloomFilterOptions options,\n Action setup = null);\n\n public static BloomFilterOptions UseRedis(\n this BloomFilterOptions options,\n FilterRedisOptions setup);\n\n public static BloomFilterOptions UseCSRedis(\n this BloomFilterOptions options,\n FilterCSRedisOptions setup);\n\n public static BloomFilterOptions UseFreeRedis(\n this BloomFilterOptions options,\n FilterFreeRedisOptions setup);\n\n public static BloomFilterOptions UseEasyCachingRedis(\n this BloomFilterOptions options,\n FilterEasyCachingRedisOptions setup);\n}\n```\n\n## Frequently Asked Questions (FAQ)\n\n### 1. What is the false positive rate of a Bloom filter?\n\nThe false positive rate is determined by the `errorRate` parameter you specify when creating the filter. For example:\n\n```csharp\n// 1% false positive rate\nvar bf = FilterBuilder.Build(1_000_000, 0.01);\n\n// 0.1% false positive rate (more accurate, but uses more memory)\nvar bf2 = FilterBuilder.Build(1_000_000, 0.001);\n```\n\n**Note**: Lower error rates require more memory space.\n\n### 2. How to choose expectedElements?\n\n`expectedElements` should be set to the number of elements you expect to add. If the actual number exceeds this, the false positive rate will increase.\n\nRecommendations:\n- Estimate actual element count\n- Add 20%-50% buffer\n- Monitor actual false positive rate regularly\n\n### 3. In-Memory vs Redis Mode - How to Choose?\n\n| Scenario | Recommended Mode | Reason |\n|----------|-----------------|---------|\n| Single-instance application | In-Memory | Highest performance, no network overhead |\n| Multi-instance application | Redis | Shared state, distributed support |\n| Persistence required | Redis | Redis provides persistence |\n| Temporary deduplication | In-Memory | Simple and fast |\n| Cross-service sharing | Redis | Multi-language access support |\n\n### 4. How to clear a Bloom filter?\n\n```csharp\n// Synchronous clear\nbf.Clear();\n\n// Asynchronous clear\nawait bf.ClearAsync();\n```\n\n**Note**: Clear operation deletes all data, use with caution!\n\n### 5. How much memory does a Bloom filter use?\n\nMemory usage depends on capacity (m):\n\n```\nMemory (bytes) = m / 8\n```\n\nExample calculation:\n\n```csharp\n// 10 million elements, 1% false positive rate\nvar bf = FilterBuilder.Build(10_000_000, 0.01);\nvar filter = (Filter)bf;\n\n// Calculate memory usage\nlong bits = filter.Capacity;\nlong bytes = bits / 8;\ndouble mb = bytes / (1024.0 * 1024.0);\n\nConsole.WriteLine($\"Bit array size: {bits:N0} bits\");\nConsole.WriteLine($\"Memory usage: {bytes:N0} bytes ({mb:F2} MB)\");\n// Output: approximately 11.4 MB\n```\n\n### 6. Can elements be deleted?\n\n**No**. Standard Bloom filters do not support deletion because:\n- Multiple elements may map to the same bits\n- Deleting one element may affect detection of other elements\n\nIf deletion is needed, consider:\n- Counting Bloom Filter\n- Cuckoo Filter\n\n### 7. Is it thread-safe?\n\nYes, BloomFilter.NetCore is thread-safe:\n\n```csharp\n// Multi-threaded concurrent access\nvar bf = FilterBuilder.Build(10_000_000, 0.01);\n\nParallel.For(0, 1000, i =>\n{\n bf.Add($\"item:{i}\"); // Thread-safe\n});\n\nParallel.For(0, 1000, i =>\n{\n var exists = bf.Contains($\"item:{i}\"); // Thread-safe\n});\n```\n\n### 8. How to monitor Redis connections?\n\n```csharp\n// Use StackExchange.Redis connection monitoring\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseRedis(new FilterRedisOptions\n {\n Name = \"MyFilter\",\n RedisKey = \"BF:Key\",\n Endpoints = new List { \"localhost:6379\" },\n // Enable connection logging\n AbortOnConnectFail = false,\n ConnectTimeout = 5000,\n ConnectRetry = 3\n });\n});\n\n// Get Redis connection information\nvar bf = serviceProvider.GetService();\nif (bf is FilterRedis redisFilter)\n{\n var connection = redisFilter.Connection;\n Console.WriteLine($\"Connection status: {connection.IsConnected}\");\n Console.WriteLine($\"Endpoints: {string.Join(\", \", connection.GetEndPoints())}\");\n}\n```\n\n## Contributing\n\nWe welcome community contributions!\n\n### How to Contribute\n\n1. Fork this repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Create a Pull Request\n\n### Development Guidelines\n\n```bash\n# Clone repository\ngit clone https://github.com/vla/BloomFilter.NetCore.git\ncd BloomFilter.NetCore\n\n# Restore dependencies\ndotnet restore\n\n# Build project\ndotnet build\n\n# Run tests\ndotnet test\n\n# Run benchmarks\ncd test/BenchmarkTest\ndotnet run -c Release\n```\n\n### Code Standards\n\n- Follow C# coding conventions\n- Add XML documentation comments\n- Write unit tests\n- Update relevant documentation\n\n## Acknowledgments\n\nThanks to all developers who contributed to this project!\n\nSpecial thanks to:\n- .NET Foundation\n- StackExchange.Redis team\n- All dependency library authors\n\nIf this project helps you, please give us a ⭐️ Star!\n"
},
{
"path": "README.zh-CN.md",
"content": "# BloomFilter.NetCore\n\n[](https://opensource.org/licenses/MIT)\n[](https://dotnet.microsoft.com/)\n\n一个高性能、功能完整的 .NET 布隆过滤器实现库，支持内存存储和多种 Redis 分布式后端。\n\n## 目录\n\n- [项目概述](#项目概述)\n- [主要特性](#主要特性)\n- [包和状态](#包和状态)\n- [整体架构](#整体架构)\n- [核心功能](#核心功能)\n- [安装](#安装)\n- [快速开始](#快速开始)\n- [使用示例](#使用示例)\n - [内存模式](#内存模式)\n - [依赖注入配置](#依赖注入配置)\n - [Redis 分布式模式](#redis-分布式模式)\n- [哈希算法](#哈希算法)\n- [性能基准测试](#性能基准测试)\n- [高级用法](#高级用法)\n- [API 参考](#api-参考)\n- [贡献指南](#贡献指南)\n- [许可证](#许可证)\n\n## 项目概述\n\nBloomFilter.NetCore 是一个企业级的布隆过滤器库，专为 .NET 生态系统设计。布隆过滤器是一种空间效率极高的概率型数据结构,用于测试一个元素是否属于一个集合。它的核心特点是:\n\n- **空间高效**: 相比传统的 HashSet,占用空间极小\n- **时间复杂度 O(1)**: 添加和查询操作都是常数时间\n- **允许一定误报率**: 可能返回假阳性(false positive),但绝不会出现假阴性(false negative)\n\n本项目提供了两大类实现:\n\n1. **内存布隆过滤器 (FilterMemory)**: 基于 BitArray 的内存实现,适用于单进程场景\n2. **分布式布隆过滤器 (FilterRedis 系列)**: 基于 Redis 的分布式实现,支持多应用程序并发访问\n\n### 主要用途\n\n- **缓存穿透防护**: 防止恶意查询不存在的数据导致缓存击穿\n- **去重场景**: URL 去重、邮箱去重、用户 ID 去重等\n- **推荐系统**: 判断用户是否已看过某个内容\n- **爬虫系统**: 判断 URL 是否已被爬取\n- **分布式系统**: 多服务实例间共享状态判断\n- **大数据场景**: 海量数据的存在性判断\n\n## 主要特性\n\n### 🎯 灵活配置\n\n- **参数完全可配置**: 位数组大小 (m)、哈希函数数量 (k)\n- **自动参数计算**: 根据容忍的误报率 (p) 和预期元素数量 (n) 自动计算最优参数\n- **20+ 种哈希算法**: 支持 CRC、MD5、SHA、Murmur、LCGs、xxHash 等或自定义算法\n\n### ⚡ 高性能\n\n- **快速生成**: 布隆过滤器的生成和操作都极快\n- **优化实现**: 使用 Span、ReadOnlyMemory 等零拷贝技术\n- **不安全代码优化**: 在性能关键路径使用 unsafe 代码块\n- **拒绝采样**: 实现了拒绝采样和哈希链,考虑雪崩效应以提高哈希质量\n\n### 🔒 并发安全\n\n- **线程安全**: 使用 AsyncLock 机制确保多线程并发访问安全\n- **异步支持**: 全面的 async/await 支持,所有操作都有异步版本\n- **分布式锁**: Redis 实现支持跨应用程序的并发访问\n\n### 🌐 多后端支持\n\n- **StackExchange.Redis**: 官方推荐的 Redis 客户端\n- **CSRedisCore**: 高性能的 Redis 客户端\n- **FreeRedis**: 轻量级 Redis 客户端\n- **EasyCaching**: 支持 EasyCaching 抽象层,可切换多种缓存提供程序\n\n### 📦 现代 .NET 支持\n\n- **多框架支持**: net462, netstandard2.0, net6.0, net7.0, net8.0, net9.0, net10.0\n- **依赖注入**: 原生支持 Microsoft.Extensions.DependencyInjection\n- **可空引用类型**: 启用可空引用类型,提高代码安全性\n\n## 包和状态\n\n| 包名 | NuGet | 说明 |\n|------|-------|------|\n|**BloomFilter.NetCore**|[](https://www.nuget.org/packages/BloomFilter.NetCore)| 核心包,提供内存布隆过滤器 |\n|**BloomFilter.Redis.NetCore**|[](https://www.nuget.org/packages/BloomFilter.Redis.NetCore)| StackExchange.Redis 实现 |\n|**BloomFilter.CSRedis.NetCore**|[](https://www.nuget.org/packages/BloomFilter.CSRedis.NetCore)| CSRedisCore 实现 |\n|**BloomFilter.FreeRedis.NetCore**|[](https://www.nuget.org/packages/BloomFilter.FreeRedis.NetCore)| FreeRedis 实现 |\n|**BloomFilter.EasyCaching.NetCore**|[](https://www.nuget.org/packages/BloomFilter.EasyCaching.NetCore)| EasyCaching 集成 |\n\n## 整体架构\n\n### 核心接口层\n\n```\nIBloomFilter (接口)\n ├── Add / AddAsync - 添加元素\n ├── Contains / ContainsAsync - 检查元素\n ├── All / AllAsync - 批量检查\n ├── Clear / ClearAsync - 清空过滤器\n └── ComputeHash - 计算哈希值\n```\n\n### 实现层次结构\n\n```\nFilter (抽象基类)\n ├── FilterMemory (内存实现)\n │ └── 使用 BitArray 存储\n │\n └── Redis 系列 (分布式实现)\n ├── FilterRedis (StackExchange.Redis)\n ├── FilterCSRedis (CSRedisCore)\n ├── FilterFreeRedis (FreeRedis)\n └── FilterEasyCachingRedis (EasyCaching)\n```\n\n### 配置系统\n\n```\nBloomFilterOptions\n ├── FilterMemoryOptions - 内存模式配置\n ├── FilterRedisOptions - StackExchange.Redis 配置\n ├── FilterCSRedisOptions - CSRedisCore 配置\n ├── FilterFreeRedisOptions - FreeRedis 配置\n └── FilterEasyCachingOptions - EasyCaching 配置\n```\n\n## 核心功能\n\n### 数学模型\n\nBloomFilter.NetCore 实现了完整的布隆过滤器数学模型:\n\n#### 1. 最优位数组大小 (m)\n\n给定预期元素数 `n` 和误报率 `p`,计算最优的位数组大小:\n\n```\nm = -(n * ln(p)) / (ln(2)^2)\n```\n\n#### 2. 最优哈希函数数量 (k)\n\n给定元素数 `n` 和位数组大小 `m`,计算最优的哈希函数数量:\n\n```\nk = (m / n) * ln(2)\n```\n\n#### 3. 实际误报率 (p)\n\n给定已插入元素数、哈希函数数量和位数组大小,计算实际误报率:\n\n```\np = (1 - e^(-k*n/m))^k\n```\n\n这些计算由 `Filter` 基类提供的静态方法实现:\n\n```csharp\n// 计算最优位数组大小\nlong m = Filter.BestM(expectedElements, errorRate);\n\n// 计算最优哈希函数数量\nint k = Filter.BestK(expectedElements, capacity);\n\n// 计算最优元素数量\nlong n = Filter.BestN(hashes, capacity);\n\n// 计算实际误报率\ndouble p = Filter.BestP(hashes, capacity, insertedElements);\n```\n\n### 存储机制\n\n#### 内存存储\n\n- **BitArray**: 使用 .NET 的 BitArray 作为底层存储\n- **分桶策略**: 当容量超过 2GB (MaxInt = 2,147,483,640) 时,自动分成多个 BitArray\n- **序列化支持**: 支持序列化/反序列化以持久化或传输过滤器状态\n\n#### Redis 存储\n\n- **SETBIT/GETBIT**: 使用 Redis 的位操作命令\n- **分布式访问**: 多个应用实例可以并发访问同一个过滤器\n- **持久化**: 利用 Redis 的持久化机制保证数据安全\n\n### 并发控制\n\n```csharp\n// AsyncLock 确保线程安全\npublic class AsyncLock\n{\n private readonly SemaphoreSlim _semaphore = new(1, 1);\n\n public async ValueTask LockAsync()\n {\n await _semaphore.WaitAsync();\n return new Release(_semaphore);\n }\n}\n```\n\n## 安装\n\n### 通过 NuGet 安装\n\n**内存模式 (核心包):**\n\n```bash\ndotnet add package BloomFilter.NetCore\n```\n\n**Redis 分布式模式 (选择一个):**\n\n```bash\n# StackExchange.Redis\ndotnet add package BloomFilter.Redis.NetCore\n\n# CSRedisCore\ndotnet add package BloomFilter.CSRedis.NetCore\n\n# FreeRedis\ndotnet add package BloomFilter.FreeRedis.NetCore\n\n# EasyCaching\ndotnet add package BloomFilter.EasyCaching.NetCore\n```\n\n## 快速开始\n\n### 最简单的示例\n\n```csharp\nusing BloomFilter;\n\n// 创建一个布隆过滤器:预期 1000 万元素,1% 误报率\nvar bf = FilterBuilder.Build(10_000_000, 0.01);\n\n// 添加元素\nbf.Add(\"user:123\");\nbf.Add(\"user:456\");\n\n// 检查元素是否存在\nConsole.WriteLine(bf.Contains(\"user:123\")); // True\nConsole.WriteLine(bf.Contains(\"user:789\")); // False (可能极小概率为 True)\n\n// 清空过滤器\nbf.Clear();\n```\n\n### 异步操作\n\n```csharp\n// 异步添加\nawait bf.AddAsync(Encoding.UTF8.GetBytes(\"user:123\"));\n\n// 异步检查\nbool exists = await bf.ContainsAsync(Encoding.UTF8.GetBytes(\"user:123\"));\n\n// 批量异步操作\nvar users = new[] {\n Encoding.UTF8.GetBytes(\"user:1\"),\n Encoding.UTF8.GetBytes(\"user:2\"),\n Encoding.UTF8.GetBytes(\"user:3\")\n};\n\nawait bf.AddAsync(users);\nvar results = await bf.ContainsAsync(users);\n```\n\n### Fluent API（v3.0 新增）\n\nv3.0 引入了现代化的流式 API，提供更好的可发现性和表达力：\n\n```csharp\n// 内存模式 Fluent API\nvar filter = FilterBuilder.Create()\n .WithName(\"UserFilter\")\n .ExpectingElements(10_000_000)\n .WithErrorRate(0.001)\n .UsingHashMethod(HashMethod.XXHash3)\n .BuildInMemory();\n\n// Redis Fluent API (StackExchange.Redis)\nvar redisFilter = FilterRedisBuilder.Create()\n .WithRedisConnection(\"localhost:6379\")\n .WithRedisKey(\"bloom:users\")\n .WithName(\"UserFilter\")\n .ExpectingElements(10_000_000)\n .WithErrorRate(0.001)\n .BuildRedis();\n\n// CSRedis Fluent API\nvar csredisFilter = FilterCSRedisBuilder.Create()\n .WithRedisClient(csredisClient)\n .WithRedisKey(\"bloom:users\")\n .ExpectingElements(10_000_000)\n .BuildCSRedis();\n\n// FreeRedis Fluent API\nvar freeRedisFilter = FilterFreeRedisBuilder.Create()\n .WithRedisClient(redisClient)\n .WithRedisKey(\"bloom:users\")\n .ExpectingElements(10_000_000)\n .BuildFreeRedis();\n\n// EasyCaching Fluent API\nvar easyCachingFilter = FilterEasyCachingBuilder.Create()\n .WithRedisCachingProvider(provider)\n .WithRedisKey(\"bloom:users\")\n .ExpectingElements(10_000_000)\n .BuildEasyCaching();\n\n// 所有通用配置方法：\n// - WithName(string) - 设置过滤器名称\n// - ExpectingElements(long) - 设置预期元素数量\n// - WithErrorRate(double) - 设置误报率 (0-1)\n// - UsingHashMethod(HashMethod) - 使用预定义哈希算法\n// - UsingCustomHash(HashFunction) - 使用自定义哈希函数\n// - WithSerializer(IFilterMemorySerializer) - 设置自定义序列化器（仅内存模式）\n```\n\n**为什么使用 Fluent API？**\n- 🔍 通过 IntelliSense 更好的可发现性\n- 📖 代码更易读、更自文档化\n- ⛓️ 可链式调用方法\n- 🎯 类型安全的配置\n- ✅ 向后兼容 - 旧的静态方法仍然可用！\n\n## 使用示例\n\n### 内存模式\n\n#### 基本用法\n\n```csharp\nusing BloomFilter;\n\npublic class UserService\n{\n // 静态共享的布隆过滤器\n private static readonly IBloomFilter _bloomFilter =\n FilterBuilder.Build(10_000_000, 0.01);\n\n public void AddUser(string userId)\n {\n // 添加用户 ID\n _bloomFilter.Add(userId);\n }\n\n public bool MayExistUser(string userId)\n {\n // 检查用户是否可能存在\n return _bloomFilter.Contains(userId);\n }\n}\n```\n\n#### 自定义配置\n\n```csharp\nusing BloomFilter;\n\n// 方式 1: 指定哈希算法\nvar bf1 = FilterBuilder.Build(\n expectedElements: 1_000_000,\n errorRate: 0.001,\n hashMethod: HashMethod.Murmur3\n);\n\n// 方式 2: 使用自定义哈希函数\nvar hashFunction = new Murmur128BitsX64();\nvar bf2 = FilterBuilder.Build(\n expectedElements: 1_000_000,\n errorRate: 0.001,\n hashFunction: hashFunction\n);\n\n// 方式 3: 手动指定参数 (高级用法)\nvar bf3 = FilterBuilder.Build(\n capacity: 9585059, // 位数组大小\n hashes: 10, // 哈希函数数量\n hashMethod: HashMethod.XXHash3\n);\n\n// 方式 4: 使用配置对象\nvar options = new FilterMemoryOptions\n{\n Name = \"MyFilter\",\n ExpectedElements = 5_000_000,\n ErrorRate = 0.01,\n Method = HashMethod.Murmur3\n};\nvar bf4 = FilterBuilder.Build(options);\n```\n\n### 依赖注入配置\n\n#### ASP.NET Core 集成\n\n```csharp\nusing BloomFilter;\nusing Microsoft.Extensions.DependencyInjection;\n\npublic class Startup\n{\n public void ConfigureServices(IServiceCollection services)\n {\n // 注册布隆过滤器服务\n services.AddBloomFilter(setupAction =>\n {\n setupAction.UseInMemory(options =>\n {\n options.Name = \"MainFilter\";\n options.ExpectedElements = 10_000_000;\n options.ErrorRate = 0.01;\n options.Method = HashMethod.Murmur3;\n });\n });\n\n services.AddControllers();\n }\n}\n\n// 在控制器或服务中使用\npublic class UserController : ControllerBase\n{\n private readonly IBloomFilter _bloomFilter;\n\n public UserController(IBloomFilter bloomFilter)\n {\n _bloomFilter = bloomFilter;\n }\n\n [HttpPost(\"users/{userId}\")]\n public IActionResult CheckUser(string userId)\n {\n if (_bloomFilter.Contains(userId))\n {\n // 用户可能存在,继续查询数据库\n return Ok(\"用户可能存在\");\n }\n else\n {\n // 用户一定不存在,无需查询数据库\n return NotFound(\"用户不存在\");\n }\n }\n}\n```\n\n#### 多个过滤器实例\n\n```csharp\nservices.AddBloomFilter(setupAction =>\n{\n // 用户过滤器\n setupAction.UseInMemory(options =>\n {\n options.Name = \"UserFilter\";\n options.ExpectedElements = 10_000_000;\n options.ErrorRate = 0.01;\n });\n\n // 邮箱过滤器\n setupAction.UseInMemory(options =>\n {\n options.Name = \"EmailFilter\";\n options.ExpectedElements = 5_000_000;\n options.ErrorRate = 0.001;\n });\n});\n\n// 使用工厂获取指定过滤器\npublic class MyService\n{\n private readonly IBloomFilter _userFilter;\n private readonly IBloomFilter _emailFilter;\n\n public MyService(IBloomFilterFactory factory)\n {\n _userFilter = factory.Get(\"UserFilter\");\n _emailFilter = factory.Get(\"EmailFilter\");\n }\n}\n```\n\n### Redis 分布式模式\n\n#### StackExchange.Redis\n\n```csharp\nusing BloomFilter;\n\n// 方式 1: 直接构建\nvar bf = FilterRedisBuilder.Build(\n redisHost: \"localhost:6379\",\n name: \"DistributedFilter\",\n expectedElements: 5_000_000,\n errorRate: 0.001\n);\n\nbf.Add(\"item:123\");\nConsole.WriteLine(bf.Contains(\"item:123\")); // True\n\n// 方式 2: 依赖注入\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseRedis(new FilterRedisOptions\n {\n Name = \"UserFilter\",\n RedisKey = \"BloomFilter:Users\",\n Endpoints = new List { \"localhost:6379\" },\n Database = 0,\n ExpectedElements = 10_000_000,\n ErrorRate = 0.01,\n Method = HashMethod.Murmur3\n });\n});\n\n// 方式 3: 高级配置 (主从、哨兵、集群)\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseRedis(new FilterRedisOptions\n {\n Name = \"ProductFilter\",\n RedisKey = \"BloomFilter:Products\",\n Endpoints = new List\n {\n \"redis-master:6379\",\n \"redis-slave1:6379\",\n \"redis-slave2:6379\"\n },\n Password = \"your-redis-password\",\n Ssl = true,\n ConnectTimeout = 5000,\n SyncTimeout = 3000,\n ExpectedElements = 20_000_000,\n ErrorRate = 0.001\n });\n});\n```\n\n#### CSRedisCore\n\n```csharp\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseCSRedis(new FilterCSRedisOptions\n {\n Name = \"OrderFilter\",\n RedisKey = \"BloomFilter:Orders\",\n ConnectionStrings = new List\n {\n \"localhost:6379,password=123456,defaultDatabase=0,poolsize=50,prefix=myapp:\"\n },\n ExpectedElements = 5_000_000,\n ErrorRate = 0.01\n });\n});\n```\n\n#### FreeRedis\n\n```csharp\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseFreeRedis(new FilterFreeRedisOptions\n {\n Name = \"CartFilter\",\n RedisKey = \"BloomFilter:Carts\",\n ConnectionStrings = new List { \"localhost:6379,password=123456\" },\n ExpectedElements = 1_000_000,\n ErrorRate = 0.01\n });\n});\n```\n\n#### EasyCaching 集成\n\nEasyCaching 提供了统一的缓存抽象层,允许您轻松切换底层缓存实现:\n\n```csharp\nusing EasyCaching.Core.Configurations;\nusing Microsoft.Extensions.DependencyInjection;\n\nvar services = new ServiceCollection();\n\n// 1. 配置 EasyCaching\nservices.AddEasyCaching(options =>\n{\n // 配置 Redis 提供程序\n options.UseRedis(config =>\n {\n config.DBConfig.Endpoints.Add(new ServerEndPoint(\"127.0.0.1\", 6379));\n config.DBConfig.Database = 0;\n }, \"redis-provider-1\");\n\n // 可以配置多个提供程序\n options.UseRedis(config =>\n {\n config.DBConfig.Endpoints.Add(new ServerEndPoint(\"127.0.0.1\", 6379));\n config.DBConfig.Database = 1;\n }, \"redis-provider-2\");\n});\n\n// 2. 配置 BloomFilter\nservices.AddBloomFilter(setupAction =>\n{\n // 使用第一个 Redis 提供程序\n setupAction.UseEasyCachingRedis(new FilterEasyCachingRedisOptions\n {\n Name = \"BF1\",\n RedisKey = \"BloomFilter1\",\n ProviderName = \"redis-provider-1\",\n ExpectedElements = 10_000_000,\n ErrorRate = 0.01\n });\n\n // 使用第二个 Redis 提供程序\n setupAction.UseEasyCachingRedis(new FilterEasyCachingRedisOptions\n {\n Name = \"BF2\",\n RedisKey = \"BloomFilter2\",\n ProviderName = \"redis-provider-2\",\n ExpectedElements = 5_000_000,\n ErrorRate = 0.001\n });\n});\n\nvar provider = services.BuildServiceProvider();\n\n// 使用默认过滤器\nvar bf = provider.GetService();\nbf.Add(\"value1\");\n\n// 使用指定名称的过滤器\nvar factory = provider.GetService();\nvar bf1 = factory.Get(\"BF1\");\nvar bf2 = factory.Get(\"BF2\");\n\nbf1.Add(\"item1\");\nbf2.Add(\"item2\");\n```\n\n### 实际应用场景\n\n#### 1. 防止缓存穿透\n\n```csharp\npublic class ProductService\n{\n private readonly IBloomFilter _bloomFilter;\n private readonly ICache _cache;\n private readonly IProductRepository _repository;\n\n public ProductService(\n IBloomFilter bloomFilter,\n ICache cache,\n IProductRepository repository)\n {\n _bloomFilter = bloomFilter;\n _cache = cache;\n _repository = repository;\n }\n\n public async Task GetProductAsync(string productId)\n {\n // 第一层防护: 布隆过滤器\n if (!_bloomFilter.Contains(productId))\n {\n // 商品一定不存在,直接返回 null\n return null;\n }\n\n // 第二层: 缓存\n var cached = await _cache.GetAsync(productId);\n if (cached != null)\n {\n return cached;\n }\n\n // 第三层: 数据库\n var product = await _repository.GetByIdAsync(productId);\n if (product != null)\n {\n await _cache.SetAsync(productId, product);\n }\n\n return product;\n }\n\n public async Task CreateProductAsync(Product product)\n {\n // 保存到数据库\n await _repository.SaveAsync(product);\n\n // 添加到布隆过滤器\n _bloomFilter.Add(product.Id);\n\n // 更新缓存\n await _cache.SetAsync(product.Id, product);\n }\n}\n```\n\n#### 2. URL 去重 (爬虫系统)\n\n```csharp\npublic class WebCrawler\n{\n private readonly IBloomFilter _visitedUrls;\n private readonly Queue _urlQueue;\n\n public WebCrawler(IBloomFilter bloomFilter)\n {\n _visitedUrls = bloomFilter;\n _urlQueue = new Queue();\n }\n\n public async Task CrawlAsync(string startUrl)\n {\n _urlQueue.Enqueue(startUrl);\n\n while (_urlQueue.Count > 0)\n {\n var url = _urlQueue.Dequeue();\n\n // 检查是否已访问\n if (_visitedUrls.Contains(url))\n {\n continue; // 跳过已访问的 URL\n }\n\n // 标记为已访问\n _visitedUrls.Add(url);\n\n // 抓取页面\n var page = await DownloadPageAsync(url);\n\n // 处理页面\n await ProcessPageAsync(page);\n\n // 提取新的 URL\n var newUrls = ExtractUrls(page);\n foreach (var newUrl in newUrls)\n {\n if (!_visitedUrls.Contains(newUrl))\n {\n _urlQueue.Enqueue(newUrl);\n }\n }\n }\n }\n}\n```\n\n#### 3. 分布式去重 (多实例)\n\n```csharp\n// 配置分布式布隆过滤器\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseRedis(new FilterRedisOptions\n {\n Name = \"GlobalDeduplication\",\n RedisKey = \"BF:Dedup\",\n Endpoints = new List { \"redis-cluster:6379\" },\n ExpectedElements = 100_000_000,\n ErrorRate = 0.0001\n });\n});\n\n// 在多个服务实例中使用\npublic class MessageProcessor\n{\n private readonly IBloomFilter _bloomFilter;\n\n public async Task ProcessMessageAsync(Message message)\n {\n // 所有实例共享同一个 Redis 布隆过滤器\n if (await _bloomFilter.ContainsAsync(message.Id))\n {\n // 消息已被其他实例处理\n return;\n }\n\n // 标记为已处理\n await _bloomFilter.AddAsync(message.Id);\n\n // 处理消息\n await HandleMessageAsync(message);\n }\n}\n```\n\n## 哈希算法\n\nBloomFilter.NetCore 支持 20+ 种哈希算法,可根据性能和准确性需求选择:\n\n### 算法分类\n\n| 类别 | 算法 | 特点 | 适用场景 |\n|------|------|------|----------|\n| **LCG 类** | LCGWithFNV1
LCGWithFNV1a
LCGModifiedFNV1 | 极快,但质量较低 | 性能要求极高,可容忍高误报率 |\n| **RNG 类** | RNGWithFNV1
RNGWithFNV1a
RNGModifiedFNV1 | 质量高,但较慢 | 对准确性要求高的场景 |\n| **校验和** | CRC32
CRC64
Adler32 | 平衡性能和质量 | 通用场景 |\n| **Murmur 系列** | Murmur3
Murmur32BitsX86
Murmur128BitsX64
Murmur128BitsX86 | **推荐**,性能好,质量高 | 生产环境推荐 |\n| **加密哈希** | SHA1
SHA256
SHA384
SHA512 | 质量最高,但最慢 | 安全性要求极高的场景 |\n| **XXHash 系列** | XXHash32
XXHash64
XXHash3
XXHash128 | **最快**,质量优秀 | 高性能场景首选 |\n\n### 选择建议\n\n```csharp\n// 推荐: 生产环境默认选择 Murmur3 (平衡性能和质量)\nvar bf1 = FilterBuilder.Build(10_000_000, 0.01, HashMethod.Murmur3);\n\n// 高性能: 对性能要求极高,选择 XXHash3\nvar bf2 = FilterBuilder.Build(10_000_000, 0.01, HashMethod.XXHash3);\n\n// 高精度: 对误报率要求极低,选择 SHA256 + 更低的 errorRate\nvar bf3 = FilterBuilder.Build(10_000_000, 0.0001, HashMethod.SHA256);\n\n// 分布式: Redis 场景推荐 XXHash64 (速度快且跨语言支持好)\nvar bf4 = FilterRedisBuilder.Build(\n \"localhost:6379\",\n \"MyFilter\",\n 10_000_000,\n 0.01,\n HashMethod.XXHash64\n);\n```\n\n## 性能基准测试\n\n### 测试环境\n\n```\nBenchmarkDotNet=v0.13.5\nOS: Windows 11 (10.0.22621.1778/22H2)\nCPU: AMD Ryzen 7 5800X, 1 CPU, 16 logical cores, 8 physical cores\n.NET SDK: 7.0.304\nRuntime: .NET 7.0.7 (7.0.723.27404), X64 RyuJIT AVX2\n```\n\n### 性能排名 (64 字节数据)\n\n| 排名 | 算法 | 平均时间 | 相对速度 |\n|------|------|----------|----------|\n| 🥇 1 | XXHash3 | 33.14 ns | 基准 (最快) |\n| 🥈 2 | XXHash128 | 36.01 ns | 1.09x |\n| 🥉 3 | CRC64 | 38.83 ns | 1.17x |\n| 4 | XXHash64 | 50.62 ns | 1.53x |\n| 5 | Murmur3 | 70.98 ns | 2.14x |\n| ... | ... | ... | ... |\n| 28 | SHA512 | 1,368.20 ns | 41.28x (最慢) |\n\n### 完整性能数据\n\n\n点击展开完整基准测试结果
\n\n#### 64 字节数据\n\n| 算法 | 平均时间 | 误差 | 标准差 | 内存分配 |\n|------|---------|------|--------|---------|\n| XXHash3 | 33.14 ns | 0.295 ns | 0.276 ns | 80 B |\n| XXHash128 | 36.01 ns | 0.673 ns | 0.749 ns | 80 B |\n| CRC64 | 38.83 ns | 0.399 ns | 0.333 ns | 80 B |\n| XXHash64 | 50.62 ns | 0.756 ns | 0.670 ns | 80 B |\n| Murmur3 | 70.98 ns | 1.108 ns | 1.036 ns | 80 B |\n| XXHash32 | 73.15 ns | 0.526 ns | 0.466 ns | 80 B |\n| Murmur128BitsX64 | 80.15 ns | 0.783 ns | 0.653 ns | 120 B |\n| Murmur128BitsX86 | 82.73 ns | 1.211 ns | 1.011 ns | 120 B |\n| LCGWithFNV1 | 91.27 ns | 1.792 ns | 2.134 ns | 80 B |\n| CRC32 | 145.63 ns | 1.528 ns | 1.429 ns | 328 B |\n| Adler32 | 150.07 ns | 0.664 ns | 0.589 ns | 336 B |\n| RNGWithFNV1 | 445.32 ns | 8.463 ns | 9.747 ns | 384 B |\n| SHA256 | 922.30 ns | 4.478 ns | 3.739 ns | 496 B |\n| SHA1 | 1,045.67 ns | 6.411 ns | 5.997 ns | 464 B |\n| SHA384 | 1,173.67 ns | 5.050 ns | 3.942 ns | 456 B |\n| SHA512 | 1,368.20 ns | 10.967 ns | 9.722 ns | 504 B |\n\n#### 1 MB 数据\n\n| 算法 | 平均时间 |\n|------|---------|\n| XXHash3 | 30,258.92 ns (~30 μs) |\n| XXHash128 | 33,778.68 ns (~34 μs) |\n| CRC64 | 56,321.74 ns (~56 μs) |\n| XXHash64 | 100,570.79 ns (~101 μs) |\n| Murmur128BitsX64 | 163,915.44 ns (~164 μs) |\n| ... | ... |\n| SHA1 | 3,381,425.73 ns (~3.4 ms) |\n\n \n\n### 性能建议\n\n1. **通用场景**: 使用 `Murmur3` (默认),性能和质量平衡\n2. **极限性能**: 使用 `XXHash3`,比 Murmur3 快 2 倍\n3. **大数据**: 使用 `XXHash128` 或 `Murmur128BitsX64`,128 位输出减少碰撞\n4. **避免使用**: LCG 系列 (质量差)、SHA 系列 (太慢)\n\n## 高级用法\n\n### 序列化和反序列化\n\n```csharp\n// 导出布隆过滤器状态\nvar bf = FilterBuilder.Build(1_000_000, 0.01);\nbf.Add(\"item1\");\nbf.Add(\"item2\");\n\n// 获取内部状态 (用于持久化)\nvar memory = (FilterMemory)bf;\nvar buckets = memory.Buckets; // BitArray[]\nvar bucketBytes = memory.BucketBytes; // byte[][]\n\n// 从状态恢复布隆过滤器\nvar options = new FilterMemoryOptions\n{\n Name = \"RestoredFilter\",\n ExpectedElements = 1_000_000,\n ErrorRate = 0.01,\n Buckets = buckets // 或使用 BucketBytes\n};\nvar restoredBf = FilterBuilder.Build(options);\n\nConsole.WriteLine(restoredBf.Contains(\"item1\")); // True\n```\n\n### 批量操作\n\n```csharp\n// 批量添加\nvar items = Enumerable.Range(1, 10000)\n .Select(i => Encoding.UTF8.GetBytes($\"user:{i}\"))\n .ToArray();\n\nvar addResults = bf.Add(items);\nConsole.WriteLine($\"成功添加: {addResults.Count(r => r)} 个元素\");\n\n// 批量检查\nvar checkResults = bf.Contains(items);\nConsole.WriteLine($\"存在: {checkResults.Count(r => r)} 个元素\");\n\n// 检查所有元素是否都存在\nbool allExist = bf.All(items);\n\n// 异步批量操作\nvar asyncAddResults = await bf.AddAsync(items);\nvar asyncCheckResults = await bf.ContainsAsync(items);\nbool asyncAllExist = await bf.AllAsync(items);\n```\n\n### 自定义哈希函数\n\n```csharp\nusing BloomFilter.HashAlgorithms;\n\n// 实现自定义哈希算法\npublic class MyCustomHash : HashFunction\n{\n public override long ComputeHash(ReadOnlySpan data)\n {\n // 自定义哈希逻辑\n long hash = 0;\n foreach (var b in data)\n {\n hash = hash * 31 + b;\n }\n return hash;\n }\n}\n\n// 使用自定义哈希\nvar customHash = new MyCustomHash();\nvar bf = FilterBuilder.Build(1_000_000, 0.01, customHash);\n```\n\n### 计算实际误报率\n\n```csharp\nvar bf = FilterBuilder.Build(100_000, 0.01);\n\n// 添加 50,000 个元素\nfor (int i = 0; i < 50_000; i++)\n{\n bf.Add($\"item:{i}\");\n}\n\n// 计算理论误报率\nvar filter = (Filter)bf;\ndouble theoreticalErrorRate = Filter.BestP(\n filter.Hashes,\n filter.Capacity,\n 50_000\n);\n\nConsole.WriteLine($\"理论误报率: {theoreticalErrorRate:P4}\");\n\n// 测试实际误报率\nint falsePositives = 0;\nint testCount = 100_000;\n\nfor (int i = 50_000; i < 50_000 + testCount; i++)\n{\n if (bf.Contains($\"item:{i}\"))\n {\n falsePositives++;\n }\n}\n\ndouble actualErrorRate = (double)falsePositives / testCount;\nConsole.WriteLine($\"实际误报率: {actualErrorRate:P4}\");\nConsole.WriteLine($\"误报数量: {falsePositives} / {testCount}\");\n```\n\n### 监控和统计\n\n```csharp\npublic class BloomFilterMonitor\n{\n private readonly IBloomFilter _filter;\n private long _addCount;\n private long _hitCount;\n private long _missCount;\n\n public BloomFilterMonitor(IBloomFilter filter)\n {\n _filter = filter;\n }\n\n public bool Add(string item)\n {\n Interlocked.Increment(ref _addCount);\n return _filter.Add(item);\n }\n\n public bool Contains(string item)\n {\n var result = _filter.Contains(item);\n if (result)\n Interlocked.Increment(ref _hitCount);\n else\n Interlocked.Increment(ref _missCount);\n return result;\n }\n\n public void PrintStats()\n {\n Console.WriteLine($\"总添加: {_addCount}\");\n Console.WriteLine($\"命中: {_hitCount}\");\n Console.WriteLine($\"未命中: {_missCount}\");\n Console.WriteLine($\"命中率: {(double)_hitCount / (_hitCount + _missCount):P2}\");\n }\n}\n```\n\n## API 参考\n\n### IBloomFilter 接口\n\n```csharp\npublic interface IBloomFilter : IDisposable\n{\n // 属性\n string Name { get; }\n\n // 同步方法\n bool Add(ReadOnlySpan data);\n IList Add(IEnumerable elements);\n bool Contains(ReadOnlySpan element);\n IList Contains(IEnumerable elements);\n bool All(IEnumerable elements);\n void Clear();\n long[] ComputeHash(ReadOnlySpan data);\n\n // 异步方法\n ValueTask AddAsync(ReadOnlyMemory data);\n ValueTask> AddAsync(IEnumerable elements);\n ValueTask ContainsAsync(ReadOnlyMemory element);\n ValueTask> ContainsAsync(IEnumerable elements);\n ValueTask AllAsync(IEnumerable elements);\n ValueTask ClearAsync();\n}\n```\n\n### Filter 基类\n\n```csharp\npublic abstract class Filter : IBloomFilter\n{\n // 属性\n public string Name { get; }\n public HashFunction Hash { get; }\n public long Capacity { get; }\n public int Hashes { get; }\n public long ExpectedElements { get; }\n public double ErrorRate { get; }\n\n // 静态方法 (数学计算)\n public static long BestM(long n, double p);\n public static int BestK(long n, long m);\n public static long BestN(int k, long m);\n public static double BestP(int k, long m, long insertedElements);\n}\n```\n\n### FilterBuilder\n\n```csharp\npublic static class FilterBuilder\n{\n // 使用预期元素数和误报率\n public static IBloomFilter Build(long expectedElements, double errorRate);\n public static IBloomFilter Build(long expectedElements, double errorRate, HashMethod method);\n public static IBloomFilter Build(long expectedElements, double errorRate, HashFunction hash);\n\n // 使用容量和哈希函数数量\n public static IBloomFilter Build(long capacity, int hashes, HashMethod method);\n public static IBloomFilter Build(long capacity, int hashes, HashFunction hash);\n\n // 使用配置对象\n public static IBloomFilter Build(FilterMemoryOptions options);\n}\n```\n\n### FilterRedisBuilder\n\n```csharp\npublic static class FilterRedisBuilder\n{\n public static IBloomFilter Build(\n string redisHost,\n string name,\n long expectedElements,\n double errorRate,\n HashMethod method = HashMethod.Murmur3);\n}\n```\n\n### 扩展方法\n\n```csharp\n// 服务注册\npublic static class ServiceCollectionExtensions\n{\n public static IServiceCollection AddBloomFilter(\n this IServiceCollection services,\n Action setupAction);\n}\n\n// 配置扩展\npublic static class BloomFilterOptionsExtensions\n{\n public static BloomFilterOptions UseInMemory(\n this BloomFilterOptions options,\n Action setup = null);\n\n public static BloomFilterOptions UseRedis(\n this BloomFilterOptions options,\n FilterRedisOptions setup);\n\n public static BloomFilterOptions UseCSRedis(\n this BloomFilterOptions options,\n FilterCSRedisOptions setup);\n\n public static BloomFilterOptions UseFreeRedis(\n this BloomFilterOptions options,\n FilterFreeRedisOptions setup);\n\n public static BloomFilterOptions UseEasyCachingRedis(\n this BloomFilterOptions options,\n FilterEasyCachingRedisOptions setup);\n}\n```\n\n## 常见问题 (FAQ)\n\n### 1. 布隆过滤器的误报率是多少?\n\n误报率由您在创建时指定的 `errorRate` 参数决定。例如:\n\n```csharp\n// 1% 误报率\nvar bf = FilterBuilder.Build(1_000_000, 0.01);\n\n// 0.1% 误报率 (更准确,但占用更多内存)\nvar bf2 = FilterBuilder.Build(1_000_000, 0.001);\n```\n\n**注意**: 误报率越低,需要的内存空间越大。\n\n### 2. 如何选择 expectedElements?\n\n`expectedElements` 应设置为您预期要添加的元素数量。如果实际添加的元素超过这个数量,误报率会增加。\n\n建议:\n- 估算实际元素数量\n- 留出 20%-50% 的冗余\n- 定期监控实际误报率\n\n### 3. 内存模式 vs Redis 模式如何选择?\n\n| 场景 | 推荐模式 | 原因 |\n|------|---------|------|\n| 单实例应用 | 内存模式 | 性能最高,无网络开销 |\n| 多实例应用 | Redis 模式 | 共享状态,支持分布式 |\n| 需要持久化 | Redis 模式 | Redis 提供持久化 |\n| 临时去重 | 内存模式 | 简单快速 |\n| 跨服务共享 | Redis 模式 | 支持多语言访问 |\n\n### 4. 如何清空布隆过滤器?\n\n```csharp\n// 同步清空\nbf.Clear();\n\n// 异步清空\nawait bf.ClearAsync();\n```\n\n**注意**: 清空操作会删除所有数据,谨慎使用!\n\n### 5. 布隆过滤器占用多少内存?\n\n内存占用取决于容量 (m):\n\n```\n内存 (字节) = m / 8\n```\n\n示例计算:\n\n```csharp\n// 1000 万元素, 1% 误报率\nvar bf = FilterBuilder.Build(10_000_000, 0.01);\nvar filter = (Filter)bf;\n\n// 计算内存占用\nlong bits = filter.Capacity;\nlong bytes = bits / 8;\ndouble mb = bytes / (1024.0 * 1024.0);\n\nConsole.WriteLine($\"位数组大小: {bits:N0} bits\");\nConsole.WriteLine($\"内存占用: {bytes:N0} bytes ({mb:F2} MB)\");\n// 输出: 约 11.4 MB\n```\n\n### 6. 可以删除元素吗?\n\n**不可以**。标准布隆过滤器不支持删除操作,因为:\n- 多个元素可能映射到相同的位\n- 删除一个元素可能影响其他元素的检测\n\n如果需要删除功能,考虑使用:\n- Counting Bloom Filter (计数布隆过滤器)\n- Cuckoo Filter (布谷鸟过滤器)\n\n### 7. 线程安全吗?\n\n是的,BloomFilter.NetCore 是线程安全的:\n\n```csharp\n// 多线程并发访问\nvar bf = FilterBuilder.Build(10_000_000, 0.01);\n\nParallel.For(0, 1000, i =>\n{\n bf.Add($\"item:{i}\"); // 线程安全\n});\n\nParallel.For(0, 1000, i =>\n{\n var exists = bf.Contains($\"item:{i}\"); // 线程安全\n});\n```\n\n### 8. 如何监控 Redis 连接?\n\n```csharp\n// 使用 StackExchange.Redis 的连接监控\nservices.AddBloomFilter(setupAction =>\n{\n setupAction.UseRedis(new FilterRedisOptions\n {\n Name = \"MyFilter\",\n RedisKey = \"BF:Key\",\n Endpoints = new List { \"localhost:6379\" },\n // 启用连接日志\n AbortOnConnectFail = false,\n ConnectTimeout = 5000,\n ConnectRetry = 3\n });\n});\n\n// 获取 Redis 连接信息\nvar bf = serviceProvider.GetService();\nif (bf is FilterRedis redisFilter)\n{\n var connection = redisFilter.Connection;\n Console.WriteLine($\"连接状态: {connection.IsConnected}\");\n Console.WriteLine($\"端点: {string.Join(\", \", connection.GetEndPoints())}\");\n}\n```\n\n## 贡献指南\n\n我们欢迎社区贡献!\n\n### 如何贡献\n\n1. Fork 本仓库\n2. 创建特性分支 (`git checkout -b feature/amazing-feature`)\n3. 提交更改 (`git commit -m 'Add amazing feature'`)\n4. 推送到分支 (`git push origin feature/amazing-feature`)\n5. 创建 Pull Request\n\n### 开发指南\n\n```bash\n# 克隆仓库\ngit clone https://github.com/vla/BloomFilter.NetCore.git\ncd BloomFilter.NetCore\n\n# 还原依赖\ndotnet restore\n\n# 构建项目\ndotnet build\n\n# 运行测试\ndotnet test\n\n# 运行基准测试\ncd test/BenchmarkTest\ndotnet run -c Release\n```\n\n### 代码规范\n\n- 遵循 C# 编码规范\n- 添加 XML 文档注释\n- 编写单元测试\n- 更新相关文档\n\n## 致谢\n\n感谢所有为本项目做出贡献的开发者!\n\n特别感谢:\n- .NET Foundation\n- StackExchange.Redis 团队\n- 所有依赖库的作者\n\n如果这个项目对您有帮助,请给我们一个 ⭐️ Star!\n"
},
{
"path": "VERSION",
"content": "3.0.0\n"
},
{
"path": "build.cmd",
"content": "set artifacts=%~dp0artifacts\n\nif exist %artifacts% rd /q /s %artifacts%\n\nset /p ver=Specifies that null is allowed as an input even if the corresponding type disallows it.\n[AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property, Inherited = false)]\ninternal sealed class AllowNullAttribute : Attribute { }\n\n/// Specifies that null is disallowed as an input even if the corresponding type allows it.\n[AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property, Inherited = false)]\ninternal sealed class DisallowNullAttribute : Attribute { }\n\n/// Specifies that an output may be null even if the corresponding type disallows it.\n[AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, Inherited = false)]\ninternal sealed class MaybeNullAttribute : Attribute { }\n\n/// Specifies that an output will not be null even if the corresponding type allows it.\n[AttributeUsage(AttributeTargets.Field | AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, Inherited = false)]\ninternal sealed class NotNullAttribute : Attribute { }\n\n/// Specifies that when a method returns , the parameter may be null even if the corresponding type disallows it.\n[AttributeUsage(AttributeTargets.Parameter, Inherited = false)]\ninternal sealed class MaybeNullWhenAttribute : Attribute\n{\n /// Initializes the attribute with the specified return value condition.\n /// \n /// The return value condition. If the method returns this value, the associated parameter may be null.\n /// \n public MaybeNullWhenAttribute(bool returnValue) => ReturnValue = returnValue;\n\n /// Gets the return value condition.\n public bool ReturnValue { get; }\n}\n\n/// Specifies that when a method returns , the parameter will not be null even if the corresponding type allows it.\n[AttributeUsage(AttributeTargets.Parameter, Inherited = false)]\ninternal sealed class NotNullWhenAttribute : Attribute\n{\n /// Initializes the attribute with the specified return value condition.\n /// \n /// The return value condition. If the method returns this value, the associated parameter will not be null.\n /// \n public NotNullWhenAttribute(bool returnValue) => ReturnValue = returnValue;\n\n /// Gets the return value condition.\n public bool ReturnValue { get; }\n}\n\n/// Specifies that the output will be non-null if the named parameter is non-null.\n[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property | AttributeTargets.ReturnValue, AllowMultiple = true, Inherited = false)]\ninternal sealed class NotNullIfNotNullAttribute : Attribute\n{\n /// Initializes the attribute with the associated parameter name.\n /// \n /// The associated parameter name. The output will be non-null if the argument to the parameter specified is non-null.\n /// \n public NotNullIfNotNullAttribute(string parameterName) => ParameterName = parameterName;\n\n /// Gets the associated parameter name.\n public string ParameterName { get; }\n}\n\n/// Applied to a method that will never return under any circumstance.\n[AttributeUsage(AttributeTargets.Method, Inherited = false)]\ninternal sealed class DoesNotReturnAttribute : Attribute { }\n\n/// Specifies that the method will not return if the associated Boolean parameter is passed the specified value.\n[AttributeUsage(AttributeTargets.Parameter, Inherited = false)]\ninternal sealed class DoesNotReturnIfAttribute : Attribute\n{\n /// Initializes the attribute with the specified parameter value.\n /// \n /// The condition parameter value. Code after the method will be considered unreachable by diagnostics if the argument to\n /// the associated parameter matches this value.\n /// \n public DoesNotReturnIfAttribute(bool parameterValue) => ParameterValue = parameterValue;\n\n /// Gets the condition parameter value.\n public bool ParameterValue { get; }\n}\n\n\n/// Specifies that the method or property will ensure that the listed field and property members have not-null values.\n[AttributeUsage(AttributeTargets.Method | AttributeTargets.Property, Inherited = false, AllowMultiple = true)]\ninternal sealed class MemberNotNullAttribute : Attribute\n{\n/// Initializes the attribute with a field or property member.\n/// \n/// The field or property member that is promised to be not-null.\n/// \npublic MemberNotNullAttribute(string member) => Members = new[] { member };\n\n/// Initializes the attribute with the list of field and property members.\n/// \n/// The list of field and property members that are promised to be not-null.\n/// \npublic MemberNotNullAttribute(params string[] members) => Members = members;\n\n/// Gets field or property member names.\npublic string[] Members { get; }\n}\n\n/// Specifies that the method or property will ensure that the listed field and property members have not-null values when returning with the specified return value condition.\n[AttributeUsage(AttributeTargets.Method | AttributeTargets.Property, Inherited = false, AllowMultiple = true)]\ninternal sealed class MemberNotNullWhenAttribute : Attribute\n{\n/// Initializes the attribute with the specified return value condition and a field or property member.\n/// \n/// The return value condition. If the method returns this value, the associated parameter will not be null.\n/// \n/// \n/// The field or property member that is promised to be not-null.\n/// \npublic MemberNotNullWhenAttribute(bool returnValue, string member)\n{\n ReturnValue = returnValue;\n Members = new[] { member };\n}\n\n/// Initializes the attribute with the specified return value condition and list of field and property members.\n/// \n/// The return value condition. If the method returns this value, the associated parameter will not be null.\n/// \n/// \n/// The list of field and property members that are promised to be not-null.\n/// \npublic MemberNotNullWhenAttribute(bool returnValue, params string[] members)\n{\n ReturnValue = returnValue;\n Members = members;\n}\n\n/// Gets the return value condition.\npublic bool ReturnValue { get; }\n\n/// Gets field or property member names.\npublic string[] Members { get; }\n}\n#endif\n\n#if NETSTANDARD2_1\n\nnamespace System.Diagnostics.CodeAnalysis;\n\n/// Specifies that the method or property will ensure that the listed field and property members have not-null values.\n[AttributeUsage(AttributeTargets.Method | AttributeTargets.Property, Inherited = false, AllowMultiple = true)]\ninternal sealed class MemberNotNullAttribute : Attribute\n{\n /// Initializes the attribute with a field or property member.\n /// \n /// The field or property member that is promised to be not-null.\n /// \n public MemberNotNullAttribute(string member) => Members = new[] { member };\n\n /// Initializes the attribute with the list of field and property members.\n /// \n /// The list of field and property members that are promised to be not-null.\n /// \n public MemberNotNullAttribute(params string[] members) => Members = members;\n\n /// Gets field or property member names.\n public string[] Members { get; }\n}\n\n/// Specifies that the method or property will ensure that the listed field and property members have not-null values when returning with the specified return value condition.\n[AttributeUsage(AttributeTargets.Method | AttributeTargets.Property, Inherited = false, AllowMultiple = true)]\ninternal sealed class MemberNotNullWhenAttribute : Attribute\n{\n /// Initializes the attribute with the specified return value condition and a field or property member.\n /// \n /// The return value condition. If the method returns this value, the associated parameter will not be null.\n /// \n /// \n /// The field or property member that is promised to be not-null.\n /// \n public MemberNotNullWhenAttribute(bool returnValue, string member)\n {\n ReturnValue = returnValue;\n Members = new[] { member };\n }\n\n /// Initializes the attribute with the specified return value condition and list of field and property members.\n /// \n /// The return value condition. If the method returns this value, the associated parameter will not be null.\n /// \n /// \n /// The list of field and property members that are promised to be not-null.\n /// \n public MemberNotNullWhenAttribute(bool returnValue, params string[] members)\n {\n ReturnValue = returnValue;\n Members = members;\n }\n\n /// Gets the return value condition.\n public bool ReturnValue { get; }\n\n /// Gets field or property member names.\n public string[] Members { get; }\n}\n\n#endif"
},
{
"path": "src/BloomFilter/AsyncLock.cs",
"content": "using System;\nusing System.Runtime.CompilerServices;\nusing System.Threading;\nusing System.Threading.Tasks;\n\nnamespace BloomFilter;\n\n/// \n/// AsyncLock\n/// \ninternal readonly struct AsyncLock : IDisposable\n{\n private readonly SemaphoreSlim _semaphore;\n private readonly Releaser _releaser;\n private readonly Task _releaserTask;\n\n public int MaxCount { get; }\n\n public AsyncLock() : this(1)\n {\n }\n\n public AsyncLock(int maxCount = 1)\n {\n MaxCount = maxCount;\n _semaphore = new SemaphoreSlim(maxCount);\n _releaser = new Releaser(_semaphore);\n _releaserTask = Task.FromResult(_releaser);\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public Releaser Acquire()\n {\n _semaphore.Wait();\n return _releaser;\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public Task AcquireAsync(bool continueOnCapturedContext = false)\n {\n var acquireAsync = _semaphore.WaitAsync();\n return Return(acquireAsync, continueOnCapturedContext);\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public void Dispose() => _semaphore.Dispose();\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n private Task Return(Task acquireAsync, bool continueOnCapturedContext)\n {\n return acquireAsync.Status == TaskStatus.RanToCompletion\n ? _releaserTask\n : WaitForAcquireAsync(acquireAsync, continueOnCapturedContext);\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n private async Task WaitForAcquireAsync(Task acquireAsync, bool continueOnCapturedContext)\n {\n await acquireAsync.ConfigureAwait(continueOnCapturedContext);\n return _releaser;\n }\n\n public readonly struct Releaser(SemaphoreSlim? semaphore) : IDisposable\n {\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public void Dispose() => semaphore?.Release();\n }\n\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public int GetRemainingCount()\n {\n return MaxCount - _semaphore.CurrentCount;\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public int GetCurrentCount()\n {\n return _semaphore.CurrentCount;\n }\n}"
},
{
"path": "src/BloomFilter/BinaryHelper.cs",
"content": "using System;\nusing System.Collections;\nusing System.Numerics;\nusing System.Runtime.CompilerServices;\n\n#if NET6_0_OR_GREATER\nusing System.Buffers.Binary;\n#endif\n\nnamespace BloomFilter;\n\ninternal class BinaryHelper\n{\n public static int BitToIntOne(BitArray bit, int from, int to)\n {\n const int size = 32;\n int len = to - from;\n int bitCount = bit.Count;\n int result = 0;\n\n for (int i = 0; i < len && i < bitCount && i < size; i++)\n {\n result = bit[i + from] ? result + (1 << i) : result;\n }\n\n return result;\n }\n\n /// \n /// Perform rejection sampling on a 32-bit,\n /// https://en.wikipedia.org/wiki/Rejection_sampling\n /// \n /// The random.\n /// integer output range.\n /// \n public static long Rejection(long random, long m)\n {\n var intMax = (long)uint.MaxValue;\n random = Math.Abs(random);\n if (random > (intMax - intMax % m) || random == uint.MinValue)\n return -1;\n return random % m;\n }\n\n public static uint NumberOfTrailingZeros(uint i)\n {\n // HD, Figure 5-14\n uint y;\n if (i == 0) return 32;\n uint n = 31;\n y = i << 16; if (y != 0) { n -= 16; i = y; }\n y = i << 8; if (y != 0) { n -= 8; i = y; }\n y = i << 4; if (y != 0) { n -= 4; i = y; }\n y = i << 2; if (y != 0) { n -= 2; i = y; }\n return n - ((i << 1) >> 31);\n }\n\n public static uint NumberOfLeadingZeros(uint i)\n {\n // HD, Figure 5-6\n if (i == 0)\n return 32;\n uint n = 1;\n if (i >> 16 == 0) { n += 16; i <<= 16; }\n if (i >> 24 == 0) { n += 8; i <<= 8; }\n if (i >> 28 == 0) { n += 4; i <<= 4; }\n if (i >> 30 == 0) { n += 2; i <<= 2; }\n n -= i >> 31;\n return n;\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public static int RotateLeft(int i, int distance)\n {\n#if NET6_0_OR_GREATER\n return (int)BitOperations.RotateLeft((uint)i, distance);\n#else\n return (i << distance) | (int)((uint)i >> -distance);\n#endif\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public static uint RotateLeft(uint i, int distance)\n {\n#if NET6_0_OR_GREATER\n return BitOperations.RotateLeft(i, distance);\n#else\n return (i << distance) | (i >> -distance);\n#endif\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public static int RotateRight(int i, int distance)\n {\n#if NET6_0_OR_GREATER\n return (int)BitOperations.RotateRight((uint)i, distance);\n#else\n return (int)((uint)i >> distance) | (i << -distance);\n#endif\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public static uint RotateRight(uint i, int distance)\n {\n#if NET6_0_OR_GREATER\n return BitOperations.RotateRight(i, distance);\n#else\n return (i >> distance) | (i << -distance);\n#endif\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public static long RotateLeft(long i, int distance)\n {\n#if NET6_0_OR_GREATER\n return (long)BitOperations.RotateLeft((ulong)i, distance);\n#else\n return (i << distance) | (long)((ulong)i >> -distance);\n#endif\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public static ulong RotateLeft(ulong i, int distance)\n {\n#if NET6_0_OR_GREATER\n return BitOperations.RotateLeft(i, distance);\n#else\n return (i << distance) | (i >> -distance);\n#endif\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public static long RotateRight(long i, int distance)\n {\n#if NET6_0_OR_GREATER\n return (long)BitOperations.RotateRight((ulong)i, distance);\n#else\n return (long)((ulong)i >> distance) | (i << -distance);\n#endif\n }\n\n [MethodImpl(MethodImplOptions.AggressiveInlining)]\n public static ulong RotateRight(ulong i, int distance)\n {\n#if NET6_0_OR_GREATER\n return BitOperations.RotateRight(i, distance);\n#else\n return (i >> distance) | (i << -distance);\n#endif\n }\n\n public static int RightMove(int value, int pos)\n {\n if (pos != 0)\n {\n var mask = 0x7fffffff;\n value >>= 1;\n value &= mask;\n value >>= pos - 1;\n }\n\n return value;\n }\n\n public static long RightMove(long value, int pos)\n {\n if (pos != 0)\n {\n var mask = 0x7fffffff;\n value >>= 1;\n value &= mask;\n value >>= pos - 1;\n }\n\n return value;\n }\n\n public static uint RightMove(uint value, int pos)\n {\n if (pos != 0)\n {\n uint mask = 0x7fffffff;\n value >>= 1;\n value &= mask;\n value >>= pos - 1;\n }\n\n return value;\n }\n}"
},
{
"path": "src/BloomFilter/BloomFilter.csproj",
"content": "\n\t\n\t\tBloomFilter\n\t\tBloomFilter\n\t\tBloomFilter.NetCore\n\t\tnet462;netstandard2.0;net6.0;net7.0;net8.0;net9.0;net10.0\n\t\ttrue\n\t\ttrue\n\t\tenable\n\t\ttrue\n\t\t$(NoWarn);CS1591\n\t\n\n\t\n\t\t\n\t\t\n\t\t\n\t\n\n\t\n\t\t\n\t\n\t\n\n"
},
{
"path": "src/BloomFilter/BloomFilterConstValue.cs",
"content": "namespace BloomFilter;\n\npublic class BloomFilterConstValue\n{\n /// \n /// The default name of the in-memory.\n /// \n public const string DefaultInMemoryName = \"DefaultInMemory\";\n\n /// \n /// The default name of the redis.\n /// \n public const string DefaultRedisName = \"DefaultRedis\";\n}"
},
{
"path": "src/BloomFilter/BloomFilterExtensions.cs",
"content": "using System;\nusing System.Collections.Generic;\nusing System.Linq;\nusing System.Text;\nusing System.Threading.Tasks;\n\nnamespace BloomFilter;\n\n/// \n/// BloomFilterExtensions\n/// \npublic static class BloomFilterExtensions\n{\n #region Byte\n\n public static bool Add(this IBloomFilter bloomFilter, byte data) => bloomFilter.Add(new[] { data });\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, byte data) => bloomFilter.AddAsync(new[] { data });\n\n public static bool Contains(this IBloomFilter bloomFilter, byte data) => bloomFilter.Contains(new[] { data });\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, byte data) => bloomFilter.ContainsAsync(new[] { data });\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => new byte[] { data }));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => new byte[] { data }));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => new byte[] { data }));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => new byte[] { data }));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => new byte[] { data }));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => new byte[] { data }));\n\n #endregion Byte\n\n #region String\n\n public static bool Add(this IBloomFilter bloomFilter, string data) => bloomFilter.Add(Encoding.UTF8.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, string data) => bloomFilter.AddAsync(Encoding.UTF8.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, string data) => bloomFilter.Contains(Encoding.UTF8.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, string data) => bloomFilter.ContainsAsync(Encoding.UTF8.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => Encoding.UTF8.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => Encoding.UTF8.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => Encoding.UTF8.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => Encoding.UTF8.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => Encoding.UTF8.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => Encoding.UTF8.GetBytes(data)));\n\n #endregion String\n\n #region ReadOnlySpan\n\n public static bool Add(this IBloomFilter bloomFilter, ReadOnlySpan data) => bloomFilter.Add(data.ToUtf8().Span);\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, ReadOnlyMemory data) => bloomFilter.AddAsync(data.Span.ToUtf8());\n\n public static bool Contains(this IBloomFilter bloomFilter, ReadOnlySpan data) => bloomFilter.Contains(data.ToUtf8().Span);\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, ReadOnlyMemory data) => bloomFilter.ContainsAsync(data.Span.ToUtf8());\n\n #endregion String\n\n #region Double\n\n public static bool Add(this IBloomFilter bloomFilter, double data) => bloomFilter.Add(BitConverter.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, double data) => bloomFilter.AddAsync(BitConverter.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, double data) => bloomFilter.Contains(BitConverter.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, double data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n #endregion Double\n\n #region Single\n\n public static bool Add(this IBloomFilter bloomFilter, float data) => bloomFilter.Add(BitConverter.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, float data) => bloomFilter.AddAsync(BitConverter.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, float data) => bloomFilter.Contains(BitConverter.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, float data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n #endregion Single\n\n #region Int16\n\n public static bool Add(this IBloomFilter bloomFilter, short data) => bloomFilter.Add(BitConverter.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, short data) => bloomFilter.AddAsync(BitConverter.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, short data) => bloomFilter.Contains(BitConverter.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, short data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n #endregion Int16\n\n #region Int32\n\n public static bool Add(this IBloomFilter bloomFilter, int data) => bloomFilter.Add(BitConverter.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, int data) => bloomFilter.AddAsync(BitConverter.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, int data) => bloomFilter.Contains(BitConverter.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, int data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n #endregion Int32\n\n #region Int64\n\n public static bool Add(this IBloomFilter bloomFilter, long data) => bloomFilter.Add(BitConverter.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, long data) => bloomFilter.AddAsync(BitConverter.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, long data) => bloomFilter.Contains(BitConverter.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, long data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n #endregion Int64\n\n #region UInt16\n\n public static bool Add(this IBloomFilter bloomFilter, ushort data) => bloomFilter.Add(BitConverter.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, ushort data) => bloomFilter.AddAsync(BitConverter.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, ushort data) => bloomFilter.Contains(BitConverter.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, ushort data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n #endregion UInt16\n\n #region UInt32\n\n public static bool Add(this IBloomFilter bloomFilter, uint data) => bloomFilter.Add(BitConverter.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, uint data) => bloomFilter.AddAsync(BitConverter.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, uint data) => bloomFilter.Contains(BitConverter.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, uint data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n #endregion UInt32\n\n #region UInt64\n\n public static bool Add(this IBloomFilter bloomFilter, ulong data) => bloomFilter.Add(BitConverter.GetBytes(data));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, ulong data) => bloomFilter.AddAsync(BitConverter.GetBytes(data));\n\n public static bool Contains(this IBloomFilter bloomFilter, ulong data) => bloomFilter.Contains(BitConverter.GetBytes(data));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, ulong data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data)));\n\n #endregion UInt64\n\n #region DateTime\n\n public static bool Add(this IBloomFilter bloomFilter, DateTime data) => bloomFilter.Add(BitConverter.GetBytes(data.Ticks));\n\n public static ValueTask AddAsync(this IBloomFilter bloomFilter, DateTime data) => bloomFilter.AddAsync(BitConverter.GetBytes(data.Ticks));\n\n public static bool Contains(this IBloomFilter bloomFilter, DateTime data) => bloomFilter.Contains(BitConverter.GetBytes(data.Ticks));\n\n public static ValueTask ContainsAsync(this IBloomFilter bloomFilter, DateTime data) => bloomFilter.ContainsAsync(BitConverter.GetBytes(data.Ticks));\n\n public static IList Add(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Add(elements.Select(data => BitConverter.GetBytes(data.Ticks)));\n\n public static ValueTask> AddAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AddAsync(elements.Select(data => BitConverter.GetBytes(data.Ticks)));\n\n public static IList Contains(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.Contains(elements.Select(data => BitConverter.GetBytes(data.Ticks)));\n\n public static ValueTask> ContainsAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.ContainsAsync(elements.Select(data => BitConverter.GetBytes(data.Ticks)));\n\n public static bool All(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.All(elements.Select(data => BitConverter.GetBytes(data.Ticks)));\n\n public static ValueTask AllAsync(this IBloomFilter bloomFilter, IEnumerable elements) => bloomFilter.AllAsync(elements.Select(data => BitConverter.GetBytes(data.Ticks)));\n\n #endregion DateTime\n}"
},
{
"path": "src/BloomFilter/Configurations/BloomFilterOptions.cs",
"content": "using System;\nusing System.Collections.Generic;\n\nnamespace BloomFilter.Configurations;\n\n/// \n/// BloomFilterOptions\n/// \npublic class BloomFilterOptions\n{\n /// \n /// Gets the extensions.\n /// \n /// The extensions.\n internal IList Extensions { get; } = new List();\n\n /// \n /// Registers the extension.\n /// \n /// Extension.\n public void RegisterExtension(IBloomFilterOptionsExtension extension)\n {\n#if NET6_0_OR_GREATER\n ArgumentNullException.ThrowIfNull(extension);\n#else\n if (extension == null) throw new ArgumentNullException(nameof(extension));\n#endif\n Extensions.Add(extension);\n }\n}"
},
{
"path": "src/BloomFilter/Configurations/FilterMemoryOptions.cs",
"content": "using System.Collections;\nusing System.Collections.Generic;\n\nnamespace BloomFilter.Configurations;\n\npublic class FilterMemoryOptions\n{\n /// \n /// The Name\n /// \n public string Name { get; set; } = BloomFilterConstValue.DefaultInMemoryName;\n\n /// \n /// The expected elements\n /// \n public long ExpectedElements { get; set; } = 1_000_000;\n\n /// \n /// The error rate\n /// \n public double ErrorRate { get; set; } = 0.01;\n\n /// \n /// The Hash Method\n /// \n public HashMethod Method { get; set; } = HashMethod.Murmur3;\n\n /// \n /// Multiple bitmap\n /// \n public BitArray[]? Buckets { get; set; }\n\n /// \n /// Multiple bitmap from bytes\n /// \n public IList? BucketBytes { get; set; }\n}"
},
{
"path": "src/BloomFilter/Configurations/FilterMemoryOptionsExtension.cs",
"content": "using System;\nusing Microsoft.Extensions.DependencyInjection;\nusing Microsoft.Extensions.DependencyInjection.Extensions;\n\nnamespace BloomFilter.Configurations;\n\npublic class FilterMemoryOptionsExtension : IBloomFilterOptionsExtension\n{\n private readonly FilterMemoryOptions _options;\n private readonly Type? _serializerType;\n\n /// \n /// Initializes a new instance of the class.\n /// \n /// Configure.\n /// \n public FilterMemoryOptionsExtension(FilterMemoryOptions options, Type? serializerType = null)\n {\n _options = options;\n _serializerType = serializerType;\n }\n\n public void AddServices(IServiceCollection services)\n {\n services.TryAddSingleton();\n\n if (_serializerType is null)\n {\n services.TryAddSingleton();\n }\n else\n {\n services.TryAddSingleton(typeof(IFilterMemorySerializer), _serializerType);\n }\n\n services.AddSingleton(x =>\n {\n return new FilterMemory(_options, x.GetRequiredService());\n });\n }\n}"
},
{
"path": "src/BloomFilter/Configurations/IBloomFilterOptionsExtension.cs",
"content": "using Microsoft.Extensions.DependencyInjection;\n\nnamespace BloomFilter.Configurations;\n\n/// \n/// BloomFilter options extension.\n/// \npublic interface IBloomFilterOptionsExtension\n{\n /// \n /// Adds the services.\n /// \n /// Services.\n void AddServices(IServiceCollection services);\n}"
},
{
"path": "src/BloomFilter/DefaultBloomFilterFactory.cs",
"content": "using System;\nusing System.Collections.Generic;\nusing System.Diagnostics.CodeAnalysis;\nusing System.Linq;\n\nnamespace BloomFilter;\n\npublic class DefaultBloomFilterFactory : IBloomFilterFactory\n{\n private readonly IEnumerable _bloomFilters;\n\n public DefaultBloomFilterFactory(IEnumerable bloomFilters)\n {\n _bloomFilters = bloomFilters;\n }\n\n public IBloomFilter Get(string name)\n {\n#if NET6_0_OR_GREATER\n ArgumentNullException.ThrowIfNull(name);\n#else\n if (name == null) throw new ArgumentNullException(nameof(name));\n#endif\n\n var filter = _bloomFilters.FirstOrDefault(x => x.Name.Equals(name, StringComparison.OrdinalIgnoreCase));\n\n if (filter == null) throw new ArgumentException(\"can not find a match BloomFilter\");\n\n return filter;\n }\n\n public bool TryGet(string name,\n#if NET5_0_OR_GREATER\n [MaybeNullWhen(false)]\n#endif\n out IBloomFilter bloomFilter)\n {\n bloomFilter = _bloomFilters.FirstOrDefault(x => x.Name.Equals(name, StringComparison.OrdinalIgnoreCase));\n return bloomFilter != null;\n }\n}"
},
{
"path": "src/BloomFilter/DefaultFilterMemorySerializer.cs",
"content": "using System;\nusing System.Collections;\nusing System.IO;\nusing System.Text;\nusing System.Threading.Tasks;\n\nnamespace BloomFilter;\n\npublic class DefaultFilterMemorySerializer : IFilterMemorySerializer\n{\n public async ValueTask SerializeAsync(FilterMemorySerializerParam param, Stream stream)\n {\n byte[] nameBytes = Encoding.UTF8.GetBytes(param.Name ?? string.Empty);\n await stream.WriteAsync(BitConverter.GetBytes(nameBytes.Length), 0, 4);\n await stream.WriteAsync(nameBytes, 0, nameBytes.Length);\n\n await stream.WriteAsync(BitConverter.GetBytes(param.ExpectedElements), 0, 8);\n await stream.WriteAsync(BitConverter.GetBytes(param.ErrorRate), 0, 8);\n await stream.WriteAsync(BitConverter.GetBytes((int)param.Method), 0, 4);\n\n await stream.WriteAsync(BitConverter.GetBytes(param.Buckets.Length), 0, 4);\n foreach (var bucket in param.Buckets)\n {\n byte[] bucketBytes = new byte[bucket.Length / 8 + Mod(bucket.Length)];\n bucket.CopyTo(bucketBytes, 0);\n await stream.WriteAsync(BitConverter.GetBytes(bucketBytes.Length), 0, 4).ConfigureAwait(false);\n await stream.WriteAsync(bucketBytes, 0, bucketBytes.Length).ConfigureAwait(false);\n }\n }\n\n public async ValueTask DeserializeAsync(Stream stream)\n {\n byte[] lengthBytes = new byte[4];\n byte[] int64Bytes = new byte[8];\n\n // Read name\n await ReadExactlyAsync(stream, lengthBytes);\n int nameLength = BitConverter.ToInt32(lengthBytes, 0);\n byte[] nameBytes = new byte[nameLength];\n await ReadExactlyAsync(stream, nameBytes);\n string name = Encoding.UTF8.GetString(nameBytes);\n\n // Read expected elements\n await ReadExactlyAsync(stream, int64Bytes);\n long expectedElements = BitConverter.ToInt64(int64Bytes, 0);\n\n // Read error rate\n await ReadExactlyAsync(stream, int64Bytes);\n double errorRate = BitConverter.ToDouble(int64Bytes, 0);\n\n // Read method\n await ReadExactlyAsync(stream, lengthBytes);\n HashMethod method = (HashMethod)BitConverter.ToInt32(lengthBytes, 0);\n\n // Read buckets\n await ReadExactlyAsync(stream, lengthBytes);\n int bucketsLength = BitConverter.ToInt32(lengthBytes, 0);\n var buckets = new BitArray[bucketsLength];\n\n for (int i = 0; i < bucketsLength; i++)\n {\n await ReadExactlyAsync(stream, lengthBytes);\n int bitArrayLength = BitConverter.ToInt32(lengthBytes, 0);\n\n byte[] bucketBytes = new byte[bitArrayLength];\n await ReadExactlyAsync(stream, bucketBytes);\n\n buckets[i] = new BitArray(bucketBytes);\n }\n\n // Create param with object initializer (compatible with init properties)\n return new FilterMemorySerializerParam\n {\n Name = name,\n ExpectedElements = expectedElements,\n ErrorRate = errorRate,\n Method = method,\n Buckets = buckets\n };\n }\n\n private async Task ReadExactlyAsync(Stream stream, byte[] data)\n {\n#if NET7_0_OR_GREATER\n await stream.ReadExactlyAsync(data, 0, data.Length).ConfigureAwait(false);\n#else\n await stream.ReadAsync(data, 0, data.Length).ConfigureAwait(false);\n#endif\n }\n\n private int Mod(int len) => len % 8 > 0 ? 1 : 0;\n}"
},
{
"path": "src/BloomFilter/Filter.cs",
"content": "using System;\nusing System.Collections.Generic;\nusing System.Threading.Tasks;\n\nnamespace BloomFilter;\n\n/// \n/// Represents a Bloom filter and provides\n/// \n/// \npublic abstract class Filter : IBloomFilter\n{\n //256MB\n protected const int MaxInt = 2_147_483_640;\n\n /// \n /// Gets the name specified by BloomFilter.\n /// \n public string Name { get; }\n\n /// \n /// \n /// \n public HashFunction Hash { get; private set; }\n\n /// \n /// the Capacity of the Bloom filter\n /// \n public long Capacity { get; private set; }\n\n /// \n /// number of hash functions\n /// \n public int Hashes { get; private set; }\n\n /// \n /// the expected elements.\n /// \n public long ExpectedElements { get; private set; }\n\n /// \n /// the number of expected elements\n /// \n public double ErrorRate { get; private set; }\n\n /// \n /// Initializes a new instance of the class.\n /// \n /// \n /// The expected elements.\n /// The error rate.\n /// The hash function.\n /// \n /// expectedElements - expectedElements must be > 0\n /// or\n /// errorRate\n /// \n /// hashFunction\n public Filter(string name, long expectedElements, double errorRate, HashFunction hashFunction)\n {\n if (expectedElements < 1)\n throw new ArgumentOutOfRangeException(\"expectedElements\", expectedElements, \"expectedElements must be > 0\");\n if (errorRate >= 1 || errorRate <= 0)\n throw new ArgumentOutOfRangeException(\"errorRate\", errorRate, string.Format(\"errorRate must be between 0 and 1, exclusive. Was {0}\", errorRate));\n\n#if NET6_0_OR_GREATER\n ArgumentNullException.ThrowIfNull(hashFunction);\n#else\n if (hashFunction == null)\n throw new ArgumentNullException(nameof(hashFunction));\n#endif\n\n Name = name;\n ExpectedElements = expectedElements;\n ErrorRate = errorRate;\n Hash = hashFunction;\n\n Capacity = BestM(expectedElements, errorRate);\n Hashes = BestK(expectedElements, Capacity);\n }\n\n /// \n /// Initializes a new instance of the class.\n /// \n /// \n /// The capacity.\n /// The hashes.\n /// The hash function.\n /// \n /// capacity - capacity must be > 0\n /// or\n /// hashes - hashes must be > 0\n /// \n /// hashFunction\n public Filter(string name, long capacity, int hashes, HashFunction hashFunction)\n {\n if (capacity < 1)\n throw new ArgumentOutOfRangeException(\"capacity\", capacity, \"capacity must be > 0\");\n if (hashes < 1)\n throw new ArgumentOutOfRangeException(\"hashes\", hashes, \"hashes must be > 0\");\n\n#if NET6_0_OR_GREATER\n ArgumentNullException.ThrowIfNull(hashFunction);\n#else\n if (hashFunction == null)\n throw new ArgumentNullException(nameof(hashFunction));\n#endif\n\n Name = name;\n Capacity = capacity;\n Hashes = hashes;\n Hash = hashFunction;\n\n ExpectedElements = BestN(hashes, capacity);\n ErrorRate = BestP(hashes, capacity, ExpectedElements);\n }\n\n protected void SetFilterParam(long expectedElements, double errorRate, HashMethod method)\n {\n if (expectedElements < 1)\n throw new ArgumentOutOfRangeException(\"expectedElements\", expectedElements, \"expectedElements must be > 0\");\n if (errorRate >= 1 || errorRate <= 0)\n throw new ArgumentOutOfRangeException(\"errorRate\", errorRate, string.Format(\"errorRate must be between 0 and 1, exclusive. Was {0}\", errorRate));\n\n ExpectedElements = expectedElements;\n ErrorRate = errorRate;\n Hash = HashFunction.Functions[method];\n\n Capacity = BestM(expectedElements, errorRate);\n Hashes = BestK(expectedElements, Capacity);\n }\n\n /// \n /// Adds the passed value to the filter.\n /// \n /// \n /// \n public abstract bool Add(ReadOnlySpan data);\n\n /// \n /// Async Adds the passed value to the filter.\n /// \n /// \n /// \n public abstract ValueTask AddAsync(ReadOnlyMemory data);\n\n /// \n /// Adds the specified elements.\n /// \n /// The elements.\n /// \n public abstract IList Add(IEnumerable elements);\n\n /// \n /// Async Adds the specified elements.\n /// \n /// The elements.\n /// \n public abstract ValueTask> AddAsync(IEnumerable elements);\n\n /// \n /// Removes all elements from the filter\n /// \n public abstract void Clear();\n\n /// \n /// Async Removes all elements from the filter\n /// \n public abstract ValueTask ClearAsync();\n\n /// \n /// Tests whether an element is present in the filter\n /// \n /// \n /// \n public abstract bool Contains(ReadOnlySpan element);\n\n /// \n /// Async Tests whether an element is present in the filter\n /// \n /// \n /// \n public abstract ValueTask ContainsAsync(ReadOnlyMemory element);\n\n /// \n /// Tests whether an elements is present in the filter\n /// \n /// \n /// \n public abstract IList Contains(IEnumerable elements);\n\n /// \n /// Async Tests whether an elements is present in the filter\n /// \n /// \n /// \n public abstract ValueTask> ContainsAsync(IEnumerable elements);\n\n ///