Wolfgang.Extensions.IEquatable 0.3.0

Wolfgang.Extensions.IEquatable

A collection of extension methods for types that implement IEquatable<T> — concise membership checks (IsInSet / IsNotInSet) and a fluent NotEqual complement to Equals.

📦 Installation

dotnet add package Wolfgang.Extensions.IEquatable

NuGet Package: Wolfgang.Extensions.IEquatable

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

📚 Documentation

• GitHub Repository: https://github.com/Chris-Wolfgang/IEquatable-Extensions
• API Documentation: https://Chris-Wolfgang.github.io/IEquatable-Extensions/
• CHANGELOG: CHANGELOG.md
• Contributing Guide: CONTRIBUTING.md

🚀 Quick Start

using Wolfgang.Extensions.IEquatable;

// Membership checks against a literal set of items
if (status.IsInSet("active", "pending"))
{
    // ...
}

if (statusCode.IsNotInSet(200, 201, 204))
{
    // ...
}

// Membership against an existing collection
var allowedRoles = new[] { "admin", "editor", "owner" };
if (currentRole.IsInSet(allowedRoles))
{
    // ...
}

// Fluent !Equals
if (lhs.NotEqual(rhs))
{
    // ...
}

All methods are pure: they return a bool and never mutate the input or the set.

Equality semantics depend on the overload:

• Single-pair overloads (IsInSet(T t1), IsInSet(T t1, T t2), NotEqual(T), ...) use static object.Equals(object, object). That call boxes value types and uses Object.Equals virtual dispatch — it does not prefer the strongly-typed IEquatable<T>.Equals(T) overload. A future revision may switch to EqualityComparer<T>.Default to avoid both the boxing and the virtual call (tracked separately).
• Collection overloads (params T[], IEnumerable<T>, ICollection<T>) use Enumerable.Contains / ICollection<T>.Contains, both of which route through EqualityComparer<T>.Default. That comparer does prefer IEquatable<T>.Equals(T) when T implements it.

✨ Features

The table below is a snapshot of the public API at the time of writing. For the authoritative list (kept in sync with source on every release), see the API documentation.

Methods

Overload-set notes

• Nullable annotations. On net5.0+ (and net8.0/net10.0 builds) all parameters are declared T? so nullability flows through the call site. On net462 / netstandard2.0 builds — which predate the framework's nullable reference annotations — they're declared as plain T. The runtime behaviour is identical; only the compile-time analysis differs.
• Collection overload preference. When the source is already an ICollection<T>, the ICollection<T> overload calls ICollection<T>.Contains directly — for types like HashSet<T> that's an O(1) hash lookup. When the source is an IEnumerable<T> the enumerable overload delegates to Enumerable.Contains (LINQ), which is O(N) and routes through EqualityComparer<T>.Default.

Examples

// HTTP status filter
var success = response.StatusCode.IsInSet(200, 201, 204);

// Reverse: anything but a known good code
var problem = response.StatusCode.IsNotInSet(200, 201, 204);

// Role check against a pre-built set
var allowed = new HashSet<string> { "admin", "editor" };
if (user.Role.IsInSet(allowed))
{
    // ...
}

// Replace `if (a != b)` with `if (a.NotEqual(b))` when the LHS reads
// awkwardly with a leading negation
if (currentVersion.NotEqual(supportedVersion))
{
    return Outdated();
}

🧪 Target Frameworks

The package multi-targets to keep the dependency footprint small on the modern runtimes while still supporting legacy .NET Framework consumers.

🔍 Code Quality & Static Analysis

This project enforces strict code quality standards through 8 specialized analyzers, an <TreatWarningsAsErrors>true</TreatWarningsAsErrors> Release gate, and custom rules:

Analyzers in Use

1. Microsoft.CodeAnalysis.NetAnalyzers — Built-in .NET analyzers for correctness and performance
2. Roslynator.Analyzers — Advanced refactoring and code quality rules
3. AsyncFixer — Async/await best practices and anti-pattern detection
4. Microsoft.VisualStudio.Threading.Analyzers — Thread safety and async patterns
5. Microsoft.CodeAnalysis.BannedApiAnalyzers — Prevents usage of banned APIs (see BannedSymbols.txt); the async-blocking bans in the shared list are inert here since the library is fully synchronous
6. Meziantou.Analyzer — Comprehensive code quality rules
7. SonarAnalyzer.CSharp — Industry-standard code analysis
8. Microsoft.CodeAnalysis.PublicApiAnalyzers — Tracks the public API surface via PublicAPI.Shipped.txt / PublicAPI.Unshipped.txt; surfaces additions/removals at compile time as a breaking-change review gate

🛠️ Building from source

git clone https://github.com/Chris-Wolfgang/IEquatable-Extensions.git
cd IEquatable-Extensions
dotnet restore
dotnet build -c Release
dotnet test  -c Release --no-build

Requires the .NET 10.0 SDK (or newer) — earlier SDKs cannot build the net10.0 target. The tests run against every framework the source supports.

🤝 Contributing

See CONTRIBUTING.md for the development workflow, coding conventions, and PR checklist.