Update documentation for Segment

Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.Segment.md

@@ -0,0 +1,21 @@
+---
+uid: SuperLinq.SuperEnumerable.Segment``1(System.Collections.Generic.IEnumerable{``0},System.Func{``0,System.Boolean})
+example: [*content]
+---
+The following code example demonstrates how to split a sequence based on a segment detector using `Segment`.
+[!code-csharp[](SuperLinq/Segment/Segment1.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.Segment``1(System.Collections.Generic.IEnumerable{``0},System.Func{``0,System.Int32,System.Boolean})
+example: [*content]
+---
+The following code example demonstrates how to split a sequence based on a segment detector using `Segment`.
+[!code-csharp[](SuperLinq/Segment/Segment2.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.Segment``1(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``0,System.Int32,System.Boolean})
+example: [*content]
+---
+The following code example demonstrates how to split a sequence based on a segment detector using `Segment`.
+[!code-csharp[](SuperLinq/Segment/Segment3.linq#L6-)]
+

Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment1.linq

@@ -0,0 +1,38 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = new[]
+{
+	(key: "jan", value: 123),
+	(key: "Jan", value: 456),
+	(key: "JAN", value: 789),
+	(key: "feb", value: 987),
+	(key: "Feb", value: 654),
+	(key: "FEB", value: 321),
+	(key: "mar", value: 789),
+	(key: "Mar", value: 456),
+	(key: "MAR", value: 123),
+	(key: "jan", value: 123),
+	(key: "Jan", value: 456),
+	(key: "JAN", value: 781),
+};
+
+// Group adjacent items
+var result = sequence
+	.Segment(
+		x => x.key[0] == 'm');
+
+Console.WriteLine(
+	"[" + Environment.NewLine + 
+	string.Join(
+		", " + Environment.NewLine, 
+		result.Select(c => "   [" + string.Join(", ", c) + "]")) +
+	Environment.NewLine + "]");
+
+// This code produces the following output:
+// [
+//    [(jan, 123), (Jan, 456), (JAN, 789), (feb, 987), (Feb, 654), (FEB, 321)],
+//    [(mar, 789), (Mar, 456), (MAR, 123), (jan, 123), (Jan, 456), (JAN, 781)]
+// ]

Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment2.linq

@@ -0,0 +1,40 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = new[]
+{
+	(key: "jan", value: 123),
+	(key: "Jan", value: 456),
+	(key: "JAN", value: 789),
+	(key: "feb", value: 987),
+	(key: "Feb", value: 654),
+	(key: "FEB", value: 321),
+	(key: "mar", value: 789),
+	(key: "Mar", value: 456),
+	(key: "MAR", value: 123),
+	(key: "jan", value: 123),
+	(key: "Jan", value: 456),
+	(key: "JAN", value: 781),
+};
+
+// Group adjacent items
+var result = sequence
+	.Segment(
+		(x, i) => i % 3 == 0);
+
+Console.WriteLine(
+	"[" + Environment.NewLine + 
+	string.Join(
+		", " + Environment.NewLine, 
+		result.Select(c => "   [" + string.Join(", ", c) + "]")) +
+	Environment.NewLine + "]");
+
+// This code produces the following output:
+// [
+//    [(jan, 123), (Jan, 456), (JAN, 789)],
+//    [(feb, 987), (Feb, 654), (FEB, 321)],
+//    [(mar, 789), (Mar, 456), (MAR, 123)],
+//    [(jan, 123), (Jan, 456), (JAN, 781)]
+// ]

Docs/SuperLinq.Docs/apidoc/SuperLinq/Segment/Segment3.linq

@@ -0,0 +1,40 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = new[]
+{
+	(key: "jan", value: 123),
+	(key: "Jan", value: 456),
+	(key: "JAN", value: 789),
+	(key: "feb", value: 987),
+	(key: "Feb", value: 654),
+	(key: "FEB", value: 321),
+	(key: "mar", value: 789),
+	(key: "Mar", value: 456),
+	(key: "MAR", value: 123),
+	(key: "jan", value: 123),
+	(key: "Jan", value: 456),
+	(key: "JAN", value: 781),
+};
+
+// Group adjacent items
+var result = sequence
+	.Segment(
+		(cur, prev, i) => !string.Equals(cur.key[..1], prev.key[..1], StringComparison.OrdinalIgnoreCase));
+
+Console.WriteLine(
+	"[" + Environment.NewLine + 
+	string.Join(
+		", " + Environment.NewLine, 
+		result.Select(c => "   [" + string.Join(", ", c) + "]")) +
+	Environment.NewLine + "]");
+
+// This code produces the following output:
+// [
+//    [(jan, 123), (Jan, 456), (JAN, 789)],
+//    [(feb, 987), (Feb, 654), (FEB, 321)],
+//    [(mar, 789), (Mar, 456), (MAR, 123)],
+//    [(jan, 123), (Jan, 456), (JAN, 781)]
+// ]

Source/SuperLinq/Segment.cs

@@ -3,16 +3,31 @@
 public static partial class SuperEnumerable
 {
 	/// <summary>
-	/// Divides a sequence into multiple sequences by using a segment detector based on the original sequence
+	///	    Divides a sequence into multiple sequences by using a segment detector based on the original sequence
 	/// </summary>
-	/// <typeparam name="T">The type of the elements in the sequence</typeparam>
-	/// <param name="source">The sequence to segment</param>
-	/// <param name="newSegmentPredicate">A function, which returns <see langword="true"/> if the given element begins a new segment, and <see langword="false"/> otherwise</param>
-	/// <returns>A sequence of segment, each of which is a portion of the original sequence</returns>
+	/// <typeparam name="T">
+	///	    The type of the elements in the sequence
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence to segment
+	/// </param>
+	/// <param name="newSegmentPredicate">
+	///	    A function, which returns <see langword="true"/> if the given element begins a new segment, and <see
+	///     langword="false"/> otherwise
+	/// </param>
 	/// <exception cref="ArgumentNullException">
-	/// Thrown if either <paramref name="source"/> or <paramref name="newSegmentPredicate"/> are <see langword="null"/>.
+	///	    <paramref name="source"/> or <paramref name="newSegmentPredicate"/> is <see langword="null"/>.
 	/// </exception>
-
+	/// <returns>
+	///	    A sequence of segment, each of which is a portion of the original sequence
+	/// </returns>
+	/// <remarks>
+	/// <para>
+	///	    This method is implemented by using deferred execution and streams the groupings. The grouping elements,
+	///     however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next
+	///     grouping occurs.
+	/// </para>
+	/// </remarks>
 	public static IEnumerable<IEnumerable<T>> Segment<T>(this IEnumerable<T> source, Func<T, bool> newSegmentPredicate)
 	{
 		Guard.IsNotNull(newSegmentPredicate);
@@ -21,16 +36,31 @@ public static IEnumerable<IEnumerable<T>> Segment<T>(this IEnumerable<T> source,
 	}
 
 	/// <summary>
-	/// Divides a sequence into multiple sequences by using a segment detector based on the original sequence
+	///	    Divides a sequence into multiple sequences by using a segment detector based on the original sequence
 	/// </summary>
-	/// <typeparam name="T">The type of the elements in the sequence</typeparam>
-	/// <param name="source">The sequence to segment</param>
-	/// <param name="newSegmentPredicate">A function, which returns <see langword="true"/> if the given element or index indicate a new segment, and <see langword="false"/> otherwise</param>
-	/// <returns>A sequence of segment, each of which is a portion of the original sequence</returns>
+	/// <typeparam name="T">
+	///	    The type of the elements in the sequence
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence to segment
+	/// </param>
+	/// <param name="newSegmentPredicate">
+	///	    A function, which returns <see langword="true"/> if the given element and index begins a new segment, and
+	///     <see langword="false"/> otherwise
+	/// </param>
 	/// <exception cref="ArgumentNullException">
-	/// Thrown if either <paramref name="source"/> or <paramref name="newSegmentPredicate"/> are <see langword="null"/>.
+	///	    <paramref name="source"/> or <paramref name="newSegmentPredicate"/> is <see langword="null"/>.
 	/// </exception>
-
+	/// <returns>
+	///	    A sequence of segment, each of which is a portion of the original sequence
+	/// </returns>
+	/// <remarks>
+	/// <para>
+	///	    This method is implemented by using deferred execution and streams the groupings. The grouping elements,
+	///     however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next
+	///     grouping occurs.
+	/// </para>
+	/// </remarks>
 	public static IEnumerable<IEnumerable<T>> Segment<T>(this IEnumerable<T> source, Func<T, int, bool> newSegmentPredicate)
 	{
 		Guard.IsNotNull(newSegmentPredicate);
@@ -39,16 +69,31 @@ public static IEnumerable<IEnumerable<T>> Segment<T>(this IEnumerable<T> source,
 	}
 
 	/// <summary>
-	/// Divides a sequence into multiple sequences by using a segment detector based on the original sequence
+	///	    Divides a sequence into multiple sequences by using a segment detector based on the original sequence
 	/// </summary>
-	/// <typeparam name="T">The type of the elements in the sequence</typeparam>
-	/// <param name="source">The sequence to segment</param>
-	/// <param name="newSegmentPredicate">A function, which returns <see langword="true"/> if the given current element, previous element or index indicate a new segment, and <see langword="false"/> otherwise</param>
-	/// <returns>A sequence of segment, each of which is a portion of the original sequence</returns>
+	/// <typeparam name="T">
+	///	    The type of the elements in the sequence
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence to segment
+	/// </param>
+	/// <param name="newSegmentPredicate">
+	///	    A function, which returns <see langword="true"/> if the given current element, previous element, and index
+	///     begins a new segment, and <see langword="false"/> otherwise
+	/// </param>
 	/// <exception cref="ArgumentNullException">
-	/// Thrown if either <paramref name="source"/> or <paramref name="newSegmentPredicate"/> are <see langword="null"/>.
+	///	    <paramref name="source"/> or <paramref name="newSegmentPredicate"/> is <see langword="null"/>.
 	/// </exception>
-
+	/// <returns>
+	///	    A sequence of segment, each of which is a portion of the original sequence
+	/// </returns>
+	/// <remarks>
+	/// <para>
+	///	    This method is implemented by using deferred execution and streams the groupings. The grouping elements,
+	///     however, are buffered. Each grouping is therefore yielded as soon as it is complete and before the next
+	///     grouping occurs.
+	/// </para>
+	/// </remarks>
 	public static IEnumerable<IEnumerable<T>> Segment<T>(this IEnumerable<T> source, Func<T, T, int, bool> newSegmentPredicate)
 	{
 		Guard.IsNotNull(source);