Refactor reflection utilities: enums, lookup, equality

Major improvements to reflection and collection utilities:
- Introduced `EqualityComparisonResult` and `MemberLookupState` enums for standardized equality and lookup results.
- Refactored method and parameter lookup APIs to return lookup states instead of throwing exceptions.
- Simplified `ParameterDescriptor` and improved validation in `ParameterDescriptorList`.
- Added `IsEmpty` and `HasItems` properties to list view interfaces.
- Provided static `Equals` methods for comparing list views and backing lists.
- Replaced indexer-based method lookup with `TryGetMethod` supporting generic parameters and ambiguity handling.
- Enhanced `ParameterListEqualityComparer` with nuanced equality checks.
- Improved documentation, validation, and code consistency throughout.

Author: BionicCode

src/BionicCode.Utilities.Net.Common/Exception/ArgumentExceptionHelpers.cs

@@ -704,15 +704,11 @@ public static void ThrowIfContainsDuplicate<TItem>(IEnumerable<TItem> items, IEq
         ArgumentNullException.ThrowIfNull(items);
         equalityComparer ??= EqualityComparer<TItem>.Default;
 
-        var set = new HashSet<TItem>(equalityComparer);
-        foreach (TItem item in items)
+        if (items.HasDuplicates(equalityComparer))
         {
-            if (!set.Add(item))
-            {
-                throw new ArgumentException(
-                    message ?? "The sequence contains duplicate items.",
-                    paramName);
-            }
+            throw new ArgumentException(
+                message ?? "The sequence contains duplicate items.",
+                paramName);
         }
     }
 }

src/BionicCode.Utilities.Net.Common/Extensions/CollectionHelperExtensions.cs

@@ -30,8 +30,7 @@ static HelperExtensionsCommon()
     /// <param name="source"></param>
     /// <returns><see langword="true"/> if <paramref name="source"/> is empty. Otherwise <see langword="false"/></returns>
     /// <exception cref="ArgumentNullException"><paramref name="source"/> is <see langword="null"/>.</exception>
-    public static bool IsEmpty<TItem>(this IEnumerable<TItem> source)
-      => !source.Any();
+    public static bool IsEmpty<TItem>(this IEnumerable<TItem> source) => !source.Any();
 
     /// <summary>
     /// Determines whether a sequence is empty.
@@ -1193,5 +1192,30 @@ public static TCollection OrEmpty<TCollection>(this TCollection? source, Func<TC
     /// <param name="source">The <see cref="List{TItem}"/> to return if it is not <see langword="null"/>.</param>
     /// <returns>The original <see cref="List{TItem}"/> if it is not <see langword="null"/>; otherwise, an empty <see cref="List{TItem}"/>.</returns>
     public static List<TItem> OrEmpty<TItem>(this List<TItem>? source) => source ?? [];
+
+    /// <summary>
+    /// Determines whether the specified collection contains duplicate elements.
+    /// </summary>
+    /// <typeparam name="TItem">The type of the elements in the collection.</typeparam>
+    /// <param name="items">The collection to check for duplicates.</param>
+    /// <param name="equalityComparer">The equality comparer to use for comparing elements.</param>
+    /// <returns><see langword="true"/> if the collection contains duplicate elements; otherwise, <see langword="false"/>.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="items"/> is <see langword="null"/>.</exception>
+    public static bool HasDuplicates<TItem>(this IEnumerable<TItem> items, IEqualityComparer<TItem>? equalityComparer = null)
+    {
+        ArgumentNullException.ThrowIfNull(items);
+        equalityComparer ??= EqualityComparer<TItem>.Default;
+
+        var set = new HashSet<TItem>(equalityComparer);
+        foreach (TItem item in items)
+        {
+            if (!set.Add(item))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
 }
 

src/BionicCode.Utilities.Reflection/ConstructorList.cs

@@ -293,26 +293,34 @@ public bool Equals(IConstructorListView? other)
         return true;
     }
 
-    internal bool Equals(ConstructorList? other)
+    internal static bool Equals(IConstructorListView? constructorDataViews, ConstructorList? constructorList)
     {
-        if (other is null)
+        // Return FALSE if exactly one of the constructor lists is NULL, otherwise compare the constructor lists for equality.
+        if (constructorDataViews is null ^ constructorList is null)
         {
             return false;
         }
 
-        if (Count != other.Count)
+        // If the constructor list view is NULL, the constructor list must also be NULL at this point, so return TRUE.
+        // If both constructor lists are NULL, consider them equal.
+        if (constructorDataViews is null)
+        {
+            return true;
+        }
+
+        if (constructorDataViews.Count != constructorList!.Count)
         {
             return false;
         }
 
-        if (!ReferenceEquals(DeclaringType, other.DeclaringTypeData.View))
+        if (!ReferenceEquals(constructorDataViews.DeclaringType, constructorList.DeclaringTypeData.View))
         {
             return false;
         }
 
-        for (int index = 0; index < Count; index++)
+        for (int index = 0; index < constructorDataViews.Count; index++)
         {
-            if (!Constructors[index].Equals(other.Constructors[index].View))
+            if (!ReferenceEquals(constructorDataViews[index], constructorList.Constructors[index].View))
             {
                 return false;
             }

src/BionicCode.Utilities.Reflection/EqualityComparisonResult.cs

@@ -0,0 +1,8 @@
+namespace BionicCode.Utilities.Net.Reflection;
+
+public enum EqualityComparisonResult
+{
+    True,
+    False,
+    TrueButAmbiguous,
+}

src/BionicCode.Utilities.Reflection/EventList.cs

@@ -360,26 +360,34 @@ public bool Equals(IEventListView? other)
         return true;
     }
 
-    internal bool Equals(EventList? other)
+    internal static bool Equals(IEventListView? eventDataViews, EventList? eventList)
     {
-        if (other is null)
+        // Return FALSE if exactly one of the event lists is NULL, otherwise compare the event lists for equality.
+        if (eventList is null ^ eventDataViews is null)
         {
             return false;
         }
 
-        if (Count != other.Count)
+        // If the event list view is NULL, the event list must also be NULL at this point, so return TRUE.
+        // If both event lists are NULL, consider them equal.
+        if (eventDataViews is null)
+        {
+            return true;
+        }
+
+        if (eventDataViews.Count != eventList!.Count)
         {
             return false;
         }
 
-        if (!ReferenceEquals(DeclaringType, other.DeclaringTypeData.View))
+        if (!ReferenceEquals(eventDataViews.DeclaringType, eventList.DeclaringTypeData.View))
         {
             return false;
         }
 
-        for (int index = 0; index < Count; index++)
+        for (int index = 0; index < eventDataViews.Count; index++)
         {
-            if (!Events[index].Equals(other.Events[index].View))
+            if (!ReferenceEquals(eventDataViews[index], eventList.Events[index].View))
             {
                 return false;
             }

src/BionicCode.Utilities.Reflection/FieldList.cs

@@ -332,27 +332,35 @@ public bool Equals(IFieldListView? other)
         return true;
     }
 
-    internal bool Equals(FieldList? other)
+    internal static bool Equals(IFieldListView? fieldListView, FieldList? fieldList)
     {
-        if (other is null)
+        // Return FALSE if exactly one of the field lists is NULL, otherwise compare the field lists for equality.
+        if (fieldList is null ^ fieldListView is null)
         {
             return false;
         }
 
-        if (Count != other.Count)
+        // If the field list view is NULL, the field list must also be NULL at this point, so return TRUE.
+        // If both field lists are NULL, consider them equal.
+        if (fieldListView is null)
+        {
+            return true;
+        }
+
+        if (fieldListView.Count != fieldList!.Count)
         {
             return false;
         }
 
-        if (!ReferenceEquals(DeclaringType, other.DeclaringTypeData.View))
+        if (!ReferenceEquals(fieldListView.DeclaringType, fieldList.DeclaringTypeData.View))
         {
             return false;
         }
 
         bool isEqual = false;
-        for (int index = 0; index < Count && !isEqual; index++)
+        for (int index = 0; index < fieldListView.Count && !isEqual; index++)
         {
-            if (!ReferenceEquals(Fields[index], other.Fields[index].View))
+            if (!ReferenceEquals(fieldListView.Fields[index], fieldList.Fields[index].View))
             {
                 return false;
             }

src/BionicCode.Utilities.Reflection/IConstructorListView.cs

@@ -6,6 +6,8 @@
 public interface IConstructorListView : ICollection, IReadOnlyList<IConstructorDataView>, IEquatable<IConstructorListView>
 {
     new int Count { get; }
+    bool IsEmpty { get; }
+    bool HasItems { get; }
     ImmutableList<IConstructorDataView> Constructors { get; }
     ITypeDataView DeclaringType { get; }
 }

src/BionicCode.Utilities.Reflection/IEventListView.cs

@@ -6,6 +6,8 @@
 public interface IEventListView : ICollection, IReadOnlyList<IEventDataView>, IEquatable<IEventListView>
 {
     new int Count { get; }
+    bool IsEmpty { get; }
+    bool HasItems { get; }
     ITypeDataView DeclaringType { get; }
     ImmutableList<IEventDataView> Events { get; }
     bool TryGetEventByName(string eventName, out IEventDataView? eventData);

src/BionicCode.Utilities.Reflection/IMethodListView.cs

@@ -6,7 +6,6 @@
 public interface IMethodListView : ICollection, IReadOnlyList<IMethodDataView>, IEquatable<IMethodListView>
 {
     new int Count { get; }
-    IMethodDataView this[string? methodName, ParameterDescriptorList? methodParameters] { get; }
     ITypeDataView DeclaringType { get; }
     bool HasItems { get; }
     bool IsEmpty { get; }
@@ -17,4 +16,14 @@ public interface IMethodListView : ICollection, IReadOnlyList<IMethodDataView>,
     new IEnumerator<IMethodDataView> GetEnumerator();
     int GetHashCode();
     bool TryGetMethodsByName(string methodName, out IMethodListView methodList);
+
+    /// <summary>
+    /// Gets the method data for the method with the specified name and parameter signature.
+    /// </summary>
+    /// <param name="methodName">The name of the method to retrieve. This value is case-sensitive.</param>
+    /// <param name="genericMethodParameters">Optional. A <see cref="TypeList"/> of generic method parameter types that describe the expected generic parameters for the method. Should be <see langword="null"/> or empty if the method is not generic. If the method is a generic method, consider providing the expected generic parameters to disambiguate the method.</param>
+    /// <param name="methodParameters">Optional. A <see cref="ParameterDescriptorList"/> of parameter information objects that describe the expected parameter types, positions, and modifiers for the method signature. Should be <see langword="null"/> or empty if method is parameterless. If the method has parameters, consider providing the expected parameters to disambiguate the method.</param>
+    /// <param name="methodDataView">When this method returns, contains the method data that matches the specified name and parameter signature, if found; otherwise, null.</param>
+    /// <returns>A <see cref="MemberLookupState"/> value indicating the result of the method lookup.</returns>
+    MemberLookupState TryGetMethod(string? methodName, ITypeListView? genericMethodParameters, ParameterDescriptorList? methodParameters, out IMethodDataView? methodDataView);
 }

src/BionicCode.Utilities.Reflection/IParameterListView.cs

@@ -6,6 +6,8 @@
 public interface IParameterListView : ICollection, IReadOnlyList<IParameterDataView>, IEquatable<IParameterListView>
 {
     new int Count { get; }
+    bool IsEmpty { get; }
+    bool HasItems { get; }
     IParameterizedMemberDataView DeclaringMember { get; }
     ImmutableList<IParameterDataView> Parameters { get; }
     bool TryGetParameterByName(string parameterName, out IParameterDataView? parameterData);