Update documentation for DistinctUntilChanged

Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.DistinctUntilChanged.md

@@ -0,0 +1,27 @@
+---
+uid: SuperLinq.SuperEnumerable.DistinctUntilChanged``1(System.Collections.Generic.IEnumerable{``0})
+example: [*content]
+---
+The following code example demonstrates how to get distinct elements from a sequence using `DistinctUntilChanged`.
+[!code-csharp[](SuperLinq/DistinctUntilChanged/DistinctUntilChanged1.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.DistinctUntilChanged``1(System.Collections.Generic.IEnumerable{``0},System.Collections.Generic.IEqualityComparer{``0})
+example: [*content]
+---
+The following code example demonstrates how to get distinct elements from a sequence using `DistinctUntilChanged`.
+[!code-csharp[](SuperLinq/DistinctUntilChanged/DistinctUntilChanged2.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.DistinctUntilChanged``2(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1})
+example: [*content]
+---
+The following code example demonstrates how to get distinct elements from a sequence using `DistinctUntilChanged`.
+[!code-csharp[](SuperLinq/DistinctUntilChanged/DistinctUntilChanged3.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.DistinctUntilChanged``2(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},System.Collections.Generic.IEqualityComparer{``1})
+example: [*content]
+---
+The following code example demonstrates how to get distinct elements from a sequence using `DistinctUntilChanged`.
+[!code-csharp[](SuperLinq/DistinctUntilChanged/DistinctUntilChanged4.linq#L6-)]

Docs/SuperLinq.Docs/apidoc/SuperLinq/DistinctUntilChanged/DistinctUntilChanged1.linq

@@ -0,0 +1,52 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = new Item[]
+{
+	new(key: 3, text: "1"),
+	new(key: 3, text: "2"),
+	new(key: 2, text: "3"),
+	new(key: 2, text: "4"),
+	new(key: 1, text: "5"),
+	new(key: 1, text: "6"),
+	new(key: 3, text: "7"),
+	new(key: 3, text: "8"),
+	new(key: 2, text: "9"),
+	new(key: 2, text: "10"),
+	new(key: 1, text: "11"),
+	new(key: 1, text: "12"),
+};
+
+// Get distinct 
+var result = sequence.DistinctUntilChanged();
+
+Console.WriteLine(
+	"[" +
+	string.Join(", ", result) +
+	"]");
+
+// This code produces the following output:
+// [(3, 1), (2, 3), (1, 5), (3, 7), (2, 9), (1, 11)]
+
+class Item : IEquatable<Item>
+{
+	public Item(int key, string text)
+	{
+		Key = key;
+		Text = text;
+	}
+
+	public int Key { get; }
+	public string Text { get; }
+
+	public bool Equals(Item other) =>
+		this.Key == other.Key;
+
+	public override int GetHashCode() =>
+		this.Key.GetHashCode();
+
+	public override string ToString() =>
+		$"({this.Key}, {this.Text})";
+}

Docs/SuperLinq.Docs/apidoc/SuperLinq/DistinctUntilChanged/DistinctUntilChanged2.linq

@@ -0,0 +1,57 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = new Item[]
+{
+	new(key: 3, text: "1"),
+	new(key: 3, text: "2"),
+	new(key: 2, text: "3"),
+	new(key: 2, text: "4"),
+	new(key: 1, text: "5"),
+	new(key: 1, text: "6"),
+	new(key: 3, text: "7"),
+	new(key: 3, text: "8"),
+	new(key: 2, text: "9"),
+	new(key: 2, text: "10"),
+	new(key: 1, text: "11"),
+	new(key: 1, text: "12"),
+};
+
+// Get distinct 
+var result = sequence
+	.DistinctUntilChanged(
+		new ItemComparer());
+
+Console.WriteLine(
+	"[" +
+	string.Join(", ", result) +
+	"]");
+
+// This code produces the following output:
+// [(3, 1), (2, 3), (1, 5), (3, 7), (2, 9), (1, 11)]
+
+class Item
+{
+	public Item(int key, string text)
+	{
+		Key = key;
+		Text = text;
+	}
+
+	public int Key { get; }
+	public string Text { get; }
+
+	public override string ToString() =>
+		$"({this.Key}, {this.Text})";
+}
+
+class ItemComparer : IEqualityComparer<Item>
+{
+	public bool Equals(Item x, Item y) =>
+		x.Key == y.Key;
+
+	public int GetHashCode(Item obj) =>
+		obj.Key.GetHashCode();
+}

Docs/SuperLinq.Docs/apidoc/SuperLinq/DistinctUntilChanged/DistinctUntilChanged3.linq

@@ -0,0 +1,32 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = new[]
+{
+	(key: 3, text: "1"),
+	(key: 3, text: "2"),
+	(key: 2, text: "3"),
+	(key: 2, text: "4"),
+	(key: 1, text: "5"),
+	(key: 1, text: "6"),
+	(key: 3, text: "7"),
+	(key: 3, text: "8"),
+	(key: 2, text: "9"),
+	(key: 2, text: "10"),
+	(key: 1, text: "11"),
+	(key: 1, text: "12"),
+};
+
+// Get distinct 
+var result = sequence
+	.DistinctUntilChanged(x => x.key);
+
+Console.WriteLine(
+	"[" +
+	string.Join(", ", result) +
+	"]");
+
+// This code produces the following output:
+// [(3, 1), (2, 3), (1, 5), (3, 7), (2, 9), (1, 11)]

Docs/SuperLinq.Docs/apidoc/SuperLinq/DistinctUntilChanged/DistinctUntilChanged4.linq

@@ -0,0 +1,34 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = new[]
+{
+	(key: "aa", text: "1"),
+	(key: "Aa", text: "2"),
+	(key: "AA", text: "3"),
+	(key: "BB", text: "4"),
+	(key: "bB", text: "5"),
+	(key: "Cc", text: "6"),
+	(key: "CC", text: "7"),
+	(key: "Aa", text: "8"),
+	(key: "aA", text: "9"),
+	(key: "bb", text: "10"),
+	(key: "bB", text: "11"),
+	(key: "CC", text: "12"),
+};
+
+// Get distinct 
+var result = sequence
+	.DistinctUntilChanged(
+		x => x.key,
+		StringComparer.OrdinalIgnoreCase);
+
+Console.WriteLine(
+	"[" +
+	string.Join(", ", result) +
+	"]");
+
+// This code produces the following output:
+// [(aa, 1), (BB, 4), (Cc, 6), (Aa, 8), (bb, 10), (CC, 12)]

Source/SuperLinq/DistinctUntilChanged.cs

@@ -3,58 +3,121 @@
 public static partial class SuperEnumerable
 {
 	/// <summary>
-	/// Returns consecutive distinct elements by using the default equality comparer to compare values.
+	///		Returns consecutive distinct elements by using the default equality comparer to compare values.
 	/// </summary>
-	/// <typeparam name="TSource">Source sequence element type.</typeparam>
-	/// <param name="source">Source sequence.</param>
-	/// <returns>Sequence without adjacent non-distinct elements.</returns>
-	/// <exception cref="ArgumentNullException"><paramref name="source"/> is <see langword="null"/>.</exception>
+	/// <typeparam name="TSource">
+	///		Source sequence element type.
+	/// </typeparam>
+	/// <param name="source">
+	///		Source sequence.
+	/// </param>
+	/// <returns>
+	///		Sequence without adjacent non-distinct elements.
+	/// </returns>
+	/// <exception cref="ArgumentNullException">
+	///		<paramref name="source"/> is <see langword="null"/>.
+	/// </exception>
+	/// <remarks>
+	/// <para>
+	///		This method uses deferred execution semantics and streams its results.
+	/// </para>
+	/// </remarks>
 	public static IEnumerable<TSource> DistinctUntilChanged<TSource>(this IEnumerable<TSource> source)
 	{
 		return DistinctUntilChanged(source, Identity, comparer: null);
 	}
 
 	/// <summary>
-	/// Returns consecutive distinct elements by using the specified equality comparer to compare values.
+	///		Returns consecutive distinct elements by using the specified equality comparer to compare values.
 	/// </summary>
-	/// <typeparam name="TSource">Source sequence element type.</typeparam>
-	/// <param name="source">Source sequence.</param>
-	/// <param name="comparer">Comparer used to compare values.</param>
-	/// <returns>Sequence without adjacent non-distinct elements.</returns>
-	/// <exception cref="ArgumentNullException"><paramref name="source"/> is <see langword="null"/>.</exception>
+	/// <typeparam name="TSource">
+	///		Source sequence element type.
+	/// </typeparam>
+	/// <param name="source">
+	///		Source sequence.
+	/// </param>
+	/// <param name="comparer">
+	///		Comparer used to compare values.
+	/// </param>
+	///	<returns>
+	///		Sequence without adjacent non-distinct elements.
+	/// </returns>
+	/// <exception cref="ArgumentNullException">
+	///		<paramref name="source"/> is <see langword="null"/>.
+	/// </exception>
+	/// <remarks>
+	/// <para>
+	///		This method uses deferred execution semantics and streams its results.
+	/// </para>
+	/// </remarks>
 	public static IEnumerable<TSource> DistinctUntilChanged<TSource>(this IEnumerable<TSource> source, IEqualityComparer<TSource>? comparer)
 	{
 		Guard.IsNotNull(source);
 		return DistinctUntilChanged(source, Identity, comparer);
 	}
 
 	/// <summary>
-	/// Returns consecutive distinct elements based on a key value by using the specified equality comparer to compare
-	/// key values.
+	///	    Returns consecutive distinct elements based on a key value by using the specified equality comparer to
+	///	    compare key values.
 	/// </summary>
-	/// <typeparam name="TSource">Source sequence element type.</typeparam>
-	/// <typeparam name="TKey">Key type.</typeparam>
-	/// <param name="source">Source sequence.</param>
-	/// <param name="keySelector">Key selector.</param>
-	/// <returns>Sequence without adjacent non-distinct elements.</returns>
-	/// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="keySelector"/> is <see
-	/// langword="null"/>.</exception>
+	/// <typeparam name="TSource">
+	///	    Source sequence element type.
+	/// </typeparam>
+	/// <typeparam name="TKey">
+	///	    Key type.
+	/// </typeparam>
+	/// <param name="source">
+	///	    Source sequence.
+	/// </param>
+	/// <param name="keySelector">
+	///	    Key selector.
+	/// </param>
+	/// <returns>
+	///	    Sequence without adjacent non-distinct elements.
+	/// </returns>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
+	/// </exception>
+	/// <remarks>
+	/// <para>
+	///	    This method uses deferred execution semantics and streams its results.
+	/// </para>
+	/// </remarks>
 	public static IEnumerable<TSource> DistinctUntilChanged<TSource, TKey>(this IEnumerable<TSource> source, Func<TSource, TKey> keySelector)
 	{
 		return DistinctUntilChanged(source, keySelector, comparer: null);
 	}
 
 	/// <summary>
-	/// Returns consecutive distinct elements based on a key value by using the specified equality comparer to compare key values.
+	///	    Returns consecutive distinct elements based on a key value by using the specified equality comparer to
+	///     compare key values.
 	/// </summary>
-	/// <typeparam name="TSource">Source sequence element type.</typeparam>
-	/// <typeparam name="TKey">Key type.</typeparam>
-	/// <param name="source">Source sequence.</param>
-	/// <param name="keySelector">Key selector.</param>
-	/// <param name="comparer">Comparer used to compare key values.</param>
-	/// <returns>Sequence without adjacent non-distinct elements.</returns>
-	/// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="keySelector"/> is <see
-	/// langword="null"/>.</exception>
+	/// <typeparam name="TSource">
+	///	    Source sequence element type.
+	/// </typeparam>
+	/// <typeparam name="TKey">
+	///	    Key type.
+	/// </typeparam>
+	/// <param name="source">
+	///	    Source sequence.
+	/// </param>
+	/// <param name="keySelector">
+	///	    Key selector.
+	/// </param>
+	/// <param name="comparer">
+	///	    Comparer used to compare key values.
+	/// </param>
+	/// <returns>
+	///	    Sequence without adjacent non-distinct elements.
+	/// </returns>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
+	/// </exception>
+	/// <remarks>
+	/// <para>
+	///	    This method uses deferred execution semantics and streams its results.
+	/// </para>
+	/// </remarks>
 	public static IEnumerable<TSource> DistinctUntilChanged<TSource, TKey>(this IEnumerable<TSource> source, Func<TSource, TKey> keySelector, IEqualityComparer<TKey>? comparer)
 	{
 		Guard.IsNotNull(source);