Added some additional document source comparison helpers

Author: daveaglick

RELEASE.md

@@ -1,5 +1,7 @@
 # 1.0.0-beta.72
 
+- Added a `DocumentSourceComparer` class that implements `IEqualityComparer<IDocument>` and can be used to compare documents by source path.
+- Added a `IEnumerable<IDocument>.ContainsBySource()` extension method to check if a collection of documents contains a document with a given source path.
 - Added an improved warning message and early exit out of recursive settings expansion. 
 - Added a `MediaTypes.IsMediaType()` method to help determine if a given path matches specified media type(s).
 

src/core/Statiq.Common/Documents/DocumentSourceComparer.cs

@@ -0,0 +1,17 @@
+using System.Collections.Generic;
+
+namespace Statiq.Common
+{
+    /// <summary>
+    /// A simple <see cref="IEqualityComparer{IDocument}"/> that compares documents by <see cref="IDocument.Source"/>.
+    /// </summary>
+    public class DocumentSourceComparer : IEqualityComparer<IDocument>
+    {
+        public static DocumentSourceComparer Instance { get; } = new DocumentSourceComparer();
+
+        public bool Equals(IDocument x, IDocument y) =>
+            (x is null && y is null) || (x is object && y is object && x.Source.Equals(y.Source));
+
+        public int GetHashCode(IDocument obj) => obj?.Source.GetHashCode() ?? 0;
+    }
+}

src/core/Statiq.Common/Documents/IDocumentEnumerableExtensions.cs

@@ -208,9 +208,29 @@ public static TDocument FirstOrDefaultDestination<TDocument>(this IEnumerable<TD
             where TDocument : IDocument =>
             documents.FirstOrDefaultDestination((IEnumerable<string>)patterns);
 
+        /// <summary>
+        /// Determines whether a document is contained in a document collection by ID.
+        /// </summary>
+        /// <remarks>
+        /// Note that the document ID my get "out of sync" when caching is being used. For example, if comparing
+        /// the ID of documents read from disk on a subsequent execution against the same documents cached from
+        /// an earlier execution, the IDs won't match even if the document is the same.
+        /// </remarks>
+        /// <param name="documents">The documents to check.</param>
+        /// <param name="document">The document to check for.</param>
+        /// <returns><c>true</c> if the document is contained in the collection, <c>false</c> otherwise.</returns>
         public static bool ContainsById(this IEnumerable<IDocument> documents, IDocument document) =>
             documents.Contains(document, DocumentIdComparer.Instance);
 
+        /// <summary>
+        /// Determines whether a document is contained in a document collection by source.
+        /// </summary>
+        /// <param name="documents">The documents to check.</param>
+        /// <param name="document">The document to check for.</param>
+        /// <returns><c>true</c> if the document is contained in the collection, <c>false</c> otherwise.</returns>
+        public static bool ContainsBySource(this IEnumerable<IDocument> documents, IDocument document) =>
+            documents.Contains(document, DocumentSourceComparer.Instance);
+
         /// <summary>
         /// Flattens a tree structure.
         /// </summary>